Alibaba Cloud Model Studio：串連狀態管理

本章節介紹 AOQ Client SDK 的串連狀態機器及其對應的 API 呼叫。

串連狀態圖

下圖描述了 AOQ Client SDK 的串連狀態遷移關係：

AOQ Client SDK 串連狀態遷移圖

狀態說明

狀態	枚舉值	說明
連結中（Connecting）	1	調用 connect 後進入，正在與 AI Service 建立串連
已串連（Connected）	2	串連建立成功，可正常收發音視頻和資料訊息
失敗（Failed）	3	串連異常（鑒權失敗/逾時/服務端拒絕等），SDK 內部會自動遷移到已斷開
已斷開（Disconnected）	0	初始狀態/主動斷開/異常斷開後的終態

狀態遷移規則

1. App 調用 connect → 進入 Connecting 狀態。
2. 連結成功 → 從 Connecting 遷移到 Connected。
3. 連結異常 → 從 Connecting 遷移到 Failed，隨後 SDK 自動遷移到 Disconnected。
4. 連結異常 → 從 Connected 遷移到 Failed，隨後 SDK 自動遷移到 Disconnected。
5. App 調用 disconnect → 從 Connected 遷移到 Disconnected。

connect API

調用 connect 發起與 AI Service 的串連，傳入由 AppServer allocate 介面返回的鑒權憑證。

方法簽名

Android：

public abstract int connect(@NonNull AoqConnectConfig config);

iOS：

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

Ohos：

connect(config: AoqConnectConfig): number;

傳回值：0 表示調用成功（非同步建連）；< 0 表示失敗。

行為說明

• 調用後觸發 onConnectionStatusChange(connecting) 回調。
• 如果連結成功時觸發 onConnectionStatusChange(connected) 回調。
• 如果連結失敗時觸發 onConnectionStatusChange(failed) 回調。

disconnect API

調用 disconnect 主動斷開與 AI Service 的串連。

方法簽名

Android：

public abstract int disconnect();

iOS：

- (int)disconnect;

Ohos：

disconnect(): number;

傳回值：0 表示成功；< 0 表示失敗。

行為說明

• 調用後觸發 onConnectionStatusChange(Disconnected) 回調。
• 引擎不會自動釋放，可重新調用 connect 進行重連。
• 未串連狀態下調用 disconnect 是安全的，返回 0。

onConnectionStatusChange 回調

串連狀態變化時，SDK 通過此回調通知業務層。

Android：

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

iOS：

- (void)onConnectionStatusChange:(AoqConnectionStatus)status;

Ohos：

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

範例程式碼

func onConnectionStatusChange(_ status: AoqConnectionStatus) {
    switch status {
    case .connecting:
        print("正在串連...")
    case .connected:
        print("串連成功")
        // 串連成功後可發送 session.update
    case .failed:
        print("串連失敗")
        // SDK 會自動遷移到 disconnected，無需手動 disconnect
    case .disconnected:
        print("已斷開")
        // 可根據業務決定是否重連
    }
}