Connection state management-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

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

111

State descriptions

State	Enum value	Description
Connecting	1	Entered after calling `connect`. The SDK is establishing a connection to the AI Service.
Connected	2	Connection established. Audio, video, and data messages can be sent and received normally.
Failed	3	Connection error (authentication failure, timeout, server rejection, and so on). The SDK automatically transitions to Disconnected.
Disconnected	0	Initial state, or the terminal state after an intentional or unexpected disconnection.

State transition rules

App calls connect → enters Connecting.
Connection succeeds → transitions from Connecting to Connected.
Connection fails → transitions from Connecting to Failed, then the SDK automatically transitions to Disconnected.
Connection fails → transitions from Connected to Failed, then the SDK automatically transitions to Disconnected.
App calls disconnect → transitions from Connected to Disconnected.

Note: 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:

public abstract int connect(@NonNull AoqConnectConfig config);

iOS:

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

HarmonyOS:

connect(config: AoqConnectConfig): number;

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:

public abstract int disconnect();

iOS:

- (int)disconnect;

HarmonyOS:

disconnect(): number;

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:

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

iOS:

- (void)onConnectionStatusChange:(AoqConnectionStatus)status;

HarmonyOS:

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

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
    }
}