Skip to main content
功能參考

串連狀態管理

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

串連狀態圖

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

狀態說明

狀態

枚舉值

說明

連結中(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
說明Failed 是瞬態,SDK 觸發 onConnectionStatusChange(Failed) 後會自動遷移到 Disconnected,業務層無需手動調用 disconnect。

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("已斷開")
        // 可根據業務決定是否重連
    }
}