本章节介绍 AOQ Client SDK 的连接状态机及其对应的 API 调用。
连接状态图
下图描述了 AOQ Client SDK 的连接状态迁移关系：
AOQ Client SDK 连接状态迁移图
状态说明
状态 | 枚举值 | 说明 |
链接中（Connecting） | 1 | 调用 |
已连接（Connected） | 2 | 连接建立成功，可正常收发音视频和数据消息 |
失败（Failed） | 3 | 连接异常（鉴权失败/超时/服务端拒绝等），SDK 内部会自动迁移到已断开 |
已断开（Disconnected） | 0 | 初始状态/主动断开/异常断开后的终态 |
状态迁移规则
App 调用
connect→ 进入Connecting状态。链接成功 → 从
Connecting迁移到Connected。链接异常 → 从
Connecting迁移到Failed，随后 SDK 自动迁移到Disconnected。链接异常 → 从
Connected迁移到Failed，随后 SDK 自动迁移到Disconnected。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("已断开")
// 可根据业务决定是否重连
}
}