Alibaba Cloud Model Studio:Connection state management

Descreve a máquina de estados de conexão do AOQ Client SDK e as chamadas de API correspondentes.

Diagrama de estados de conexão

O diagrama a seguir ilustra as transições de estado de conexão do AOQ Client SDK:

Diagrama de estados de conexão do AOQ Client SDK

Descrições dos estados

Estado	Valor do enum	Descrição
Connecting	1	Estado atingido após a chamada de connect. O SDK está estabelecendo uma conexão com o AI Service.
Connected	2	Conexão estabelecida. Mensagens de áudio, vídeo e dados são enviadas e recebidas normalmente.
Failed	3	Erro de conexão (falha de autenticação, timeout, rejeição pelo servidor, entre outros). O SDK faz a transição automática para Disconnected.
Disconnected	0	Estado inicial ou final após uma desconexão intencional ou inesperada.

Regras de transição de estado

1. O aplicativo chama connect → entra em Connecting.
2. Conexão bem-sucedida → transição de Connecting para Connected.
3. Falha na conexão → transição de Connecting para Failed; em seguida, o SDK passa automaticamente para Disconnected.
4. O aplicativo chama disconnect → transição de Connected para Disconnected.

Nota: Failed é um estado transitório. Após o SDK disparar onConnectionStatusChange(Failed), ele transita automaticamente para Disconnected. A camada de aplicação não precisa chamar disconnect manualmente.

API connect

Chame connect para iniciar uma conexão com o AI Service. Utilize as credenciais de autenticação retornadas pelo endpoint allocate do AppServer.

Assinatura do método

Android:

public abstract int connect(@NonNull AoqConnectConfig config);

iOS:

- (int)connect:(AoqConnectConfig * _Nonnull)config;

HarmonyOS:

connect(config: AoqConnectConfig): number;

Valor de retorno: 0 indica que a chamada foi bem-sucedida (a conexão é estabelecida de forma assíncrona). < 0 indica falha.

Comportamento

• Dispara o callback onConnectionStatusChange(connecting) imediatamente após a chamada.
• Aciona o callback onConnectionStatusChange(connected) se a conexão for estabelecida com sucesso.
• Invoca o callback onConnectionStatusChange(failed) caso ocorra falha na conexão.

API disconnect

Utilize disconnect para encerrar intencionalmente a conexão com o AI Service.

Assinatura do método

Android:

public abstract int disconnect();

iOS:

- (int)disconnect;

HarmonyOS:

disconnect(): number;

Valor de retorno: 0 indica sucesso. < 0 sinaliza falha.

Comportamento

• Dispara o callback onConnectionStatusChange(Disconnected) após a execução da chamada.
• O engine não é liberado automaticamente. Chame connect novamente para reconectar.
• A invocação de disconnect sem uma conexão ativa é segura e retorna 0.

Callback onConnectionStatusChange

O SDK dispara este callback sempre que o estado de conexão muda.

Android:

public void onConnectionStatusChange(
    @NonNull AoqClientEngine.AoqConnectionStatus status) {}

iOS:

- (void)onConnectionStatusChange:(AoqConnectionStatus)status;

HarmonyOS:

onConnectionStatusChange?: (status: AoqConnectionStatus) => void;

Exemplo

func onConnectionStatusChange(_ status: AoqConnectionStatus) {
    switch status {
    case .connecting:
        print("Connecting...")
    case .connected:
        print("Connected")
        // You can send session.update after the connection is established
    case .failed:
        print("Connection failed")
        // The SDK will automatically transition to disconnected; no need to call disconnect manually
    case .disconnected:
        print("Disconnected")
        // Decide whether to reconnect based on your application logic
    }
}