Skip to main content
QwenCloud home page
Docs
AOQ SDK Features

Connection management

AOQ SDK connection state diagram, migration rules, and API

Describes the connection state machine of the AOQ Client SDK and the corresponding API calls.

Connection state diagram

The following diagram shows the connection state transitions of the AOQ Client SDK:
AOQ Client SDK connection state diagram

State descriptions

StateEnum valueDescription
Connecting1Entered after calling connect. The SDK is establishing a connection to the AI Service.
Connected2Connection established. Audio, video, and data messages can be sent and received normally.
Failed3Connection error (authentication failure, timeout, server rejection, and so on). The SDK automatically transitions to Disconnected.
Disconnected0Initial state, or the terminal state after an intentional or unexpected disconnection.

State transition rules

  1. App calls connect → enters Connecting.
  2. Connection succeeds → transitions from Connecting to Connected.
  3. Connection fails → transitions from Connecting to Failed, then the SDK automatically transitions to Disconnected.
  4. Connection fails → transitions from Connected to Failed, then the SDK automatically transitions to Disconnected.
  5. App calls disconnect → transitions from Connected to Disconnected.
Failed is a transient state. After the SDK fires onConnectionStatusChange(Failed), it automatically transitions to Disconnected. The application layer does not need to call disconnect manually.

connect API

Call connect to initiate a connection to the AI Service. Pass the authentication credentials returned by the AppServer allocate endpoint.

Method signature

  • Android
  • iOS
  • HarmonyOS
public abstract int connect(@NonNull AoqConnectConfig config);
Return value: 0 indicates the call succeeded (connection is established asynchronously). < 0 indicates failure.

Behavior

  • Fires the onConnectionStatusChange(connecting) callback immediately after the call.
  • Fires the onConnectionStatusChange(connected) callback if the connection succeeds.
  • Fires the onConnectionStatusChange(failed) callback if the connection fails.

disconnect API

Call disconnect to intentionally close the connection to the AI Service.

Method signature

  • Android
  • iOS
  • HarmonyOS
public abstract int disconnect();
Return value: 0 indicates success. < 0 indicates failure.

Behavior

  • Fires the onConnectionStatusChange(Disconnected) callback after the call.
  • The engine is not released automatically. You can call connect again to reconnect.
  • Calling disconnect when not connected is safe and returns 0.

onConnectionStatusChange callback

The SDK fires this callback whenever the connection state changes.
  • Android
  • iOS
  • HarmonyOS
public void onConnectionStatusChange(
  @NonNull AoqClientEngine.AoqConnectionStatus status) {}

Example

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
  }
}
Connection management - QwenCloud