@tencentcloud/sdk-mcp 1.7.7 → 1.7.9-beta.1

package/resource/knowledge/iot/client-api/device/android-smart-device.md

@@ -0,0 +1,813 @@
+---
+product: iot
+framework:
+  - android
+types:
+  - api
+retrievable_scope: always
+feature_domain: client_api
+---
+
+## 概述
+
+本文档描述设备端公开 Android API，TXIoTDeviceEngine 是整个 SDK 的入口，通过 getInstance(Context) 获取单例，使用前须先调用 login 完成设备验证登录。
+
+> **说明：**
+> 线程模型：SDK 接口可在任意线程调用；回调均在主线程（UI 线程）触发，调用方可在回调中直接操作 UI。
+>
+
+#### SDK 模块总览
+
+|模块|说明|
+|---------|---------|
+|TXIoTDeviceEngine 设备引擎管理|核心生命周期，登录（连接与设备身份）。|
+|TXIoTDataModelSession 物模型|物模型（属性 / 事件 / 行为）。|
+|TXIoTMonitorSession IPC 监控|IPC 监控。|
+|TXIoTCallSession 音视频通话|音视频通话。|
+|TXIoTAITalkSession AI 对话|AI 对话（AITalk）。|
+|TXIoTError 错误码|SDK 统一错误码。|
+
+### 设备引擎管理（TXIoTDeviceEngine）
+
+|方法签名|描述|
+|---------|---------|
+|getInstance|获取 TXIoTDeviceEngine 单例。|
+|addListener|添加引擎事件监听器。|
+|removeListener|移除引擎事件监听器。|
+|initSDK|初始化 SDK 核心（创建 IoT 消息循环并异步完成内部模块初始化）。|
+|uninitSDK|反初始化 SDK，阻塞等待内部清理完成后返回。|
+|login|使用三元组登录（异步 MQTT 连接，内部可重试）。|
+|logout|登出并清除本地凭证（异步，无独立完成回调）。|
+|dynamicRegister|动态注册设备（同一时刻仅允许一路）。|
+|getNTPTime|读取 NTP 同步后的 UTC 毫秒时间戳。|
+
+### 物模型（TXIoTDataModelSession）
+
+|方法签名|描述|
+|---------|---------|
+|getInstance|获取 TXIoTDataModelSession 单例。|
+|addListener|添加物模型事件监听器。|
+|removeListener|移除物模型事件监听器。|
+|reportProperty|上报属性（异步）。|
+|reportEvent|上报事件（异步）。|
+
+### IPC 监控（TXIoTMonitorSession）
+
+|方法签名|描述|
+|---------|---------|
+|getInstance|获取 TXIoTMonitorSession 单例。|
+|addListener|添加监控事件监听器。|
+|removeListener|移除监控事件监听器。|
+|openCamera|打开监控相机并推流。|
+|closeCamera|关闭监控相机。|
+|openMicrophone|打开麦克风。|
+|closeMicrophone|关闭麦克风。|
+|switchVideoQuality|切换视频清晰度。|
+
+### 音视频通话（TXIoTCallSession）
+
+|方法签名|描述|
+|---------|---------|
+|getInstance|获取 TXIoTCallSession 单例。|
+|addListener|添加通话事件监听器。|
+|removeListener|移除通话事件监听器。|
+|getContacts|分页拉取联系人列表（异步）。|
+|call|发起呼叫（异步）。|
+|accept|接听呼叫（异步）。|
+|reject|拒接呼叫（异步）。|
+|hangup|挂断通话（异步）。|
+|openCamera|打开本地相机并预览。|
+|switchCamera|切换前/后摄像头。|
+|closeCamera|关闭本地相机。|
+|openMicrophone|打开麦克风。|
+|closeMicrophone|关闭麦克风。|
+|startRemoteView|渲染远端用户画面。|
+|stopRemoteView|停止渲染远端画面。|
+|muteRemoteAudio|静音/取消静音远端音频。|
+
+### AI 对话（TXIoTAITalkSession）
+
+|方法签名|描述|
+|---------|---------|
+|getInstance|获取 TXIoTAITalkSession 单例。|
+|addListener|添加 AI 对话事件监听器。|
+|removeListener|移除 AI 对话事件监听器。|
+|startSpeak|发起语音对话（异步）。|
+|stopSpeak|停止语音对话。|
+|sendText|发送文本消息。|
+|interrupt|打断当前 Bot 发言。|
+
+## 设备引擎管理
+
+### getInstance
+
+**获取 TXIoTDeviceEngine 单例**
+
+|参数|描述|
+|---------|---------|
+|context|`Context`；Android 上下文。|
+
+### addListener
+
+**添加引擎事件监听器**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTDeviceEngine.Listener；监听器实例。|
+
+### removeListener
+
+**移除引擎事件监听器**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTDeviceEngine.Listener；监听器实例。|
+
+### initSDK
+
+**初始化 SDK**
+
+|参数|描述|
+|---------|---------|
+|config|TXIoTDeviceEngine.Config；初始化配置，含存储路径、日志级别与接入地域。|
+
+### uninitSDK
+
+反初始化 SDK，释放相关资源。
+
+### login
+
+**登录 SDK（异步）**
+
+|参数|描述|
+|---------|---------|
+|deviceInfo|TXIoTDeviceEngine.DeviceInfo；设备信息。|
+|callback|TXIoTCallback；异步回调，通过 onSuccess / onError 通知结果。|
+
+### logout
+
+**登出 SDK**
+
+|参数|描述|
+|---------|---------|
+|callback|TXIoTCallback；异步回调，通过 onSuccess / onError 通知结果。|
+
+### dynamicRegister
+
+**动态注册（异步），使用产品级密钥为设备申请 deviceSecret**
+
+|参数|描述|
+|---------|---------|
+|params|TXIoTDeviceEngine.DynamicRegisterParams；动态注册参数。|
+|callback|TXIoTValueCallback<String>；异步回调，通过 onSuccess / onError 通知结果。|
+
+### getNTPTime
+
+**获取 NTP 网络时间（异步）**
+
+|参数|描述|
+|---------|---------|
+|callback|TXIoTValueCallback<Long>；异步回调，通过 onSuccess / onError 通知结果。|
+
+### 事件回调
+
+`TXIoTDeviceEngine.Listener` 是接口类型，所有回调方法均提供默认空实现，调用方可按需覆写。回调均在主线程（UI 线程）触发。
+
+|回调方法|说明|
+|---------|---------|
+|onLog(TXIoTDeviceEngine.LogLevel level, String log)|SDK 日志回调，level 为日志级别，log 为日志内容。|
+|onDeviceStateChanged(DeviceState oldState, DeviceState newState)|设备与云端连接状态变更，oldState 为变更前状态，newState 为变更后状态（离线 / 在线 / 重连中）。|
+
+### 数据结构
+
+以下类型定义于 `TXIoTDeviceEngine` 接口中，作为设备引擎相关接口的共用数据类型。
+
+#### TXIoTDeviceEngine.Config
+
+SDK 初始化配置。在 `initSDK` 接口中使用，用于指定本地存储路径、日志级别与接入地域。
+
+|字段|说明|
+|---------|---------|
+|storagePath|`String`；本地持久化目录；可为 NULL；非空时长度须合法（实现侧上限约 256）。|
+|logLevel|logLevel；日志级别。|
+|region|`String`；接入地域。国内版：`""` 或 `null`（等价）；海外版：`"us-east"`、`"europe"`、`"ap-bangkok"`。非法取值时 `initSDK` 返回 `INVALID_ARGUMENT`。|
+
+#### TXIoTDeviceEngine.DeviceInfo
+
+设备信息（三元组）。在 `login` 接口中使用，用于设备身份验证登录。
+
+|字段|说明|
+|---------|---------|
+|productId|`String`；产品 ID。|
+|deviceId|`String`；设备名称。|
+|deviceSecret|`String`；设备密钥。|
+
+#### TXIoTDeviceEngine.DynamicRegisterParams
+
+动态注册参数。在 `dynamicRegister` 接口中使用，用于使用产品级密钥为设备申请 deviceSecret。
+
+|字段|说明|
+|---------|---------|
+|productId|`String`；产品 ID。|
+|deviceId|`String`；设备名称。|
+|productSecret|`String`；产品级密钥。|
+
+#### TXIoTDeviceEngine.LogLevel
+
+日志级别枚举。在 ​Config 中使用，用于控制 SDK 日志输出的详细程度。
+
+|枚举值|说明|
+|---------|---------|
+|NONE|不输出日志。|
+|ERROR|仅输出错误日志。|
+|WARN|输出警告及以上级别日志。|
+|INFO|输出信息及以上级别日志。|
+|DEBUG|输出全部调试日志。|
+
+#### TXIoTDeviceEngine.DeviceState
+
+设备连接状态枚举。在 `Listener.onDeviceStateChanged` 回调中使用，用于表示设备与云端的连接状态。
+
+|枚举值|说明|
+|---------|---------|
+|OFFLINE|离线。|
+|ONLINE|在线。|
+|RECONNECTING|重连中。|
+
+## 物模型
+
+### getInstance
+
+**获取 TXIoTDataModelSession 单例。**
+
+### addListener
+
+**添加物模型事件监听器。**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTDataModelSession.Listener；监听器实例。|
+
+### removeListener
+
+**移除物模型事件监听器。**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTDataModelSession.Listener；监听器实例。|
+
+### reportProperty
+
+**批量上报设备属性（异步）。**
+
+|参数|描述|
+|---------|---------|
+|propertyList|List<​Data>；待上报属性列表。|
+|callback|TXIoTValueCallback<List<​ResultItem>>；异步回调，通过 onSuccess / onError 通知结果。|
+
+### reportEvent
+
+**上报设备事件（异步）。**
+
+|参数|描述|
+|---------|---------|
+|event|TXIoTDataModelSession.Event；待上报事件。|
+|callback|TXIoTCallback；异步回调，通过 onSuccess / onError 通知结果。|
+
+### 事件回调
+
+`TXIoTDataModelSession.Listener` 是接口类型，所有回调方法均提供默认空实现，调用方可按需覆写。回调均在主线程（UI 线程）触发。
+
+|回调方法|说明|
+|---------|---------|
+|onReceivePropertyChanged(TXIoTDataModelSession.Data property)|收到云端下发的属性变更，property 为变更后的属性数据，设备需据此执行相应控制。|
+|onReceiveNewAction(TXIoTDataModelSession.Action action)|收到云端下发的行为（​Action）调用，action 含输入参数；返回值为执行结果码，0 表示成功。|
+
+### 数据结构
+
+以下类型定义于 `TXIoTDataModelSession` 接口中，作为物模型相关接口的共用数据类型。
+
+#### TXIoTDataModelSession.DataValue
+
+物模型数据值，根据 ​DataType 使用对应类型的字段承载数据。
+
+|字段|说明|
+|---------|---------|
+|valueBool|`boolean`；布尔值（DataType 为 BOOL 时有效）。|
+|valueInt|`int`；整型值（DataType 为 INT 时有效）。|
+|valueFloat|`double`；浮点值（DataType 为 FLOAT 时有效）。|
+|valueString|`String`；字符串值（DataType 为 STRING 时有效）。|
+|valueEnum|`long`；枚举值（DataType 为 ENUM 时有效）。|
+|valueTime|`long`；时间值（DataType 为 TIME 时有效，Unix 毫秒时间戳）。|
+
+#### TXIoTDataModelSession.Data
+
+物模型属性数据项，在 `reportProperty` 上报及属性变更回调中使用。
+
+|字段|说明|
+|---------|---------|
+|id|`String`；属性标识符。|
+|dataType|DataType；数据类型。|
+|dataValue|DataValue；数据值。|
+
+#### TXIoTDataModelSession.Event
+
+物模型事件，在 `reportEvent` 上报事件时使用。
+
+|字段|说明|
+|---------|---------|
+|id|`String`；事件标识符。|
+|eventType|EventType；事件类型。|
+|eventDataList|List<Data>；事件携带的数据列表。|
+
+#### TXIoTDataModelSession.Action
+
+物模型行为，在 `Listener.onReceiveNewAction` 回调中使用，表示云端下发的一次行为调用。
+
+|字段|说明|
+|---------|---------|
+|id|`String`；行为标识符。|
+|token|`String`；本次行为调用的令牌。|
+|timestamp|`long`；行为触发时间戳（Unix 毫秒）。|
+|actionInputDataList|List<Data>；行为输入参数列表。|
+|actionOutputDataList|List<Data>；行为输出参数列表。|
+
+#### TXIoTDataModelSession.ResultItem
+
+单项处理结果，在 `reportProperty` 的回调中返回，表示每个属性的上报结果。
+
+|字段|说明|
+|---------|---------|
+|id|`String`；对应属性标识符。|
+|errorCode|`int`；错误码，0 表示成功。|
+|errorMessage|`String`；错误描述。|
+
+#### TXIoTDataModelSession.DataType
+
+物模型数据类型枚举，在 ​Data 中使用，用于标识 ​DataValue 中生效的字段。
+
+|枚举值|说明|
+|---------|---------|
+|BOOL|布尔类型。|
+|INT|整型。|
+|FLOAT|浮点型。|
+|STRING|字符串类型。|
+|ENUM|枚举类型。|
+|TIME|时间类型。|
+
+#### TXIoTDataModelSession.EventType
+
+物模型事件类型枚举，在 ​Event 中使用，用于标识事件的等级。
+
+|枚举值|说明|
+|---------|---------|
+|INFO|信息类事件。|
+|ALERT|告警类事件。|
+|FAULT|故障类事件。|
+
+## IPC 监控
+
+### getInstance
+
+**获取 TXIoTMonitorSession 单例。**
+
+### addListener
+
+**添加监控事件监听器。**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTMonitorSession.Listener；监听器实例。|
+
+### removeListener
+
+**移除监控事件监听器。**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTMonitorSession.Listener；监听器实例。|
+
+### openCamera
+
+**打开监控相机并按指定清晰度推流。**
+
+|参数|描述|
+|---------|---------|
+|option|TXIoTMonitorSession.Option；监控选项（视频清晰度）。|
+|view|TXCloudVideoView；本地预览渲染视图。|
+
+### closeCamera
+
+**关闭监控相机。**
+
+### openMicrophone
+
+**打开麦克风。**
+
+### closeMicrophone
+
+**关闭麦克风。**
+
+### switchVideoQuality
+
+**切换监控视频清晰度。**
+
+|参数|描述|
+|---------|---------|
+|quality|TXIoTMonitorSession.VideoQuality；目标清晰度。|
+
+### 事件回调
+
+`TXIoTMonitorSession.Listener` 是接口类型，所有回调方法均提供默认空实现，调用方可按需覆写。回调均在主线程（UI 线程）触发。
+
+|回调方法|说明|
+|---------|---------|
+|onMonitorBegin(Option option, String customData)|收到 APP 端发起的监控请求，option 为请求的视频清晰度等参数，customData 为透传的自定义数据。收到后需调用 `openCamera` 开启采集并推流。|
+|onMonitorEnd()|监控结束（APP 端停止观看），需调用 `closeCamera` / `closeMicrophone` 停止采集。|
+|onMonitorSwitch(VideoQuality quality)|APP 端请求切换视频清晰度，quality 为目标清晰度，可调用 `switchVideoQuality` 响应。|
+|onPTZCommandReceived(TXIoTMonitorSession.PTZCommand command, int speed)|收到云台（PTZ）控制指令，command 为控制方向或缩放指令，speed 为控制速度。|
+
+### 数据结构
+
+以下类型定义于 `TXIoTMonitorSession` 接口中，作为 IPC 监控相关接口的共用数据类型。
+
+#### TXIoTMonitorSession.Option
+
+监控选项，在 `openCamera` 接口中使用，用于指定监控推流的视频清晰度。
+
+|字段|说明|
+|---------|---------|
+|videoQuality|VideoQuality；视频清晰度。|
+
+#### TXIoTMonitorSession.VideoQuality
+
+视频清晰度枚举，在 ​Option、`openCamera`、`switchVideoQuality` 中使用。
+
+|枚举值|说明|
+|---------|---------|
+|UNKNOWN|未知清晰度。|
+|LD|流畅。|
+|SD|标清。|
+|HD|高清。|
+|FHD|超清。|
+
+#### TXIoTMonitorSession.PTZCommand
+
+云台控制指令枚举，在 `Listener.onPTZCommandReceived` 回调中使用，表示云端下发的云台控制指令。
+
+|枚举值|说明|
+|---------|---------|
+|UP|向上。|
+|DOWN|向下。|
+|LEFT|向左。|
+|RIGHT|向右。|
+|ZOOM_IN|放大。|
+|ZOOM_OUT|缩小。|
+|STOP|停止。|
+
+## 音视频通话
+
+### getInstance
+
+**获取 TXIoTCallSession 单例。**
+
+### addListener
+
+**添加通话事件监听器。**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTCallSession.Listener；监听器实例。|
+
+### removeListener
+
+**移除通话事件监听器。**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTCallSession.Listener；监听器实例。|
+
+### getContacts
+
+**分页拉取联系人列表（异步）。**
+
+|参数|描述|
+|---------|---------|
+|cursor|分页游标，示例"0"。|
+|limit|单页数量。|
+|callback|TXIoTValueCallback<​ContactsResult>；异步回调，通过 onSuccess / onError 通知结果，成功会返回联系人列表及下一页游标。|
+
+### call
+
+**向指定用户发起呼叫（异步）。**
+
+|参数|描述|
+|---------|---------|
+|userId|被叫用户 ID。|
+|option|TXIoTCallSession.Option；呼叫选项（媒体类型、自定义数据）。|
+|callback|TXIoTCallback；异步回调，通过 onSuccess / onError 通知结果。|
+
+### accept
+
+**接听来自指定用户的呼叫（异步）。**
+
+|参数|描述|
+|---------|---------|
+|userId|主叫用户 ID。|
+|callback|TXIoTCallback；异步回调，通过 onSuccess / onError 通知结果。|
+
+### reject
+
+**拒接来自指定用户的呼叫（异步）。**
+
+|参数|描述|
+|---------|---------|
+|userId|主叫用户 ID。|
+|callback|TXIoTCallback；异步回调，通过 onSuccess / onError 通知结果。|
+
+### hangup
+
+**挂断与指定用户的通话（异步）。**
+
+|参数|描述|
+|---------|---------|
+|userId|对端用户 ID。|
+|callback|TXIoTCallback；异步回调，通过 onSuccess / onError 通知结果。|
+
+### openCamera
+
+**打开本地相机并在指定视图上预览。**
+
+|参数|描述|
+|---------|---------|
+|frontCamera|true 前置摄像头，false 后置摄像头。|
+|view|TXCloudVideoView；本地预览渲染视图。|
+
+### switchCamera
+
+**切换前/后摄像头。**
+
+|参数|描述|
+|---------|---------|
+|frontCamera|true 前置摄像头，false 后置摄像头。|
+
+### closeCamera
+
+**关闭本地相机。**
+
+### openMicrophone
+
+**打开麦克风。**
+
+### closeMicrophone
+
+**关闭麦克风。**
+
+### startRemoteView
+
+**渲染指定远端用户的视频画面。**
+
+|参数|描述|
+|---------|---------|
+|userId|远端用户 ID。|
+|view|TXCloudVideoView；远端画面渲染视图。|
+
+### stopRemoteView
+
+**停止渲染指定远端用户的视频画面。**
+
+|参数|描述|
+|---------|---------|
+|userId|远端用户 ID。|
+
+### muteRemoteAudio
+
+**静音/取消静音指定远端用户的音频。**
+
+|参数|描述|
+|---------|---------|
+|userId|远端用户 ID。|
+|mute|true 静音，false 取消静音。|
+
+### 事件回调
+
+`TXIoTCallSession.Listener` 是接口类型，所有回调方法均提供默认空实现，调用方可按需覆写。回调均在主线程（UI 线程）触发。
+
+|回调方法|说明|
+|---------|---------|
+|onCallRequested(Contact contact, Option option)|收到来自对端的通话请求，contact 为主叫联系人，option 为通话选项（媒体类型等）。|
+|onCallAccepted(Contact contact)|对端已接听，contact 为接听方联系人。|
+|onCallRejected(Contact contact)|对端已拒接，contact 为拒接方联系人。|
+|onCallTimeout(Contact contact)|通话超时未接听，contact 为超时未响应的联系人。|
+|onCallHangup(Contact contact)|对端已挂断，contact 为挂断方联系人。|
+
+### 数据结构
+
+以下类型定义于 `TXIoTCallSession` 接口中，作为音视频通话相关接口的共用数据类型。
+
+#### TXIoTCallSession.Contact
+
+联系人，在联系人列表及通话事件回调中使用，用于标识通话的对端用户。
+
+|字段|说明|
+|---------|---------|
+|userId|`String`；用户 ID。|
+|userName|`String`；用户昵称。|
+|avatarUrl|`String`；用户头像 URL。|
+
+#### TXIoTCallSession.ContactsResult
+
+联系人分页结果，在 `getContacts` 的回调中返回，包含本页联系人列表及下一页游标。
+
+|字段|说明|
+|---------|---------|
+|contacts|List<Contact>；本页联系人列表。|
+|nextCursor|`String`；下一页游标，用于继续分页拉取。|
+
+#### TXIoTCallSession.Option
+
+呼叫选项，在 `call` 接口中使用，用于指定媒体类型与自定义数据。
+
+|字段|说明|
+|---------|---------|
+|mediaContent|MediaContent；媒体类型。|
+|customData|`String`；自定义透传数据。|
+
+#### TXIoTCallSession.MediaContent
+
+媒体类型枚举，在 ​Option 中使用，用于指定通话的媒体形式。
+
+|枚举值|说明|
+|---------|---------|
+|UNKNOWN|未知类型。|
+|AUDIO|纯音频通话。|
+|VIDEO|纯视频通话。|
+|AUDIO_VIDEO|音视频通话。|
+
+## AI 对话
+
+### getInstance
+
+**获取 TXIoTAITalkSession 单例。**
+
+### addListener
+
+**添加 AI 对话事件监听器。**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTAITalkSession.Listener；监听器实例。|
+
+### removeListener
+
+**移除 AI 对话事件监听器。**
+
+|参数|描述|
+|---------|---------|
+|listener|TXIoTAITalkSession.Listener；监听器实例。|
+
+### startSpeak
+
+**发起语音对话（异步）。**
+
+|参数|描述|
+|---------|---------|
+|params|TXIoTAITalkSession.Params；对话参数。|
+|contacts|List<​Contact>；参与对话的联系人列表。|
+|callback|TXIoTCallback；异步回调，通过 onSuccess / onError 通知结果。|
+
+### stopSpeak
+
+**停止语音对话。**
+
+### sendText
+
+**向 Bot 发送文本消息。**
+
+|参数|描述|
+|---------|---------|
+|text|文本内容。|
+
+### interrupt
+
+**打断当前 Bot 发言。**
+
+### 事件回调
+
+`TXIoTAITalkSession.Listener` 是接口类型，所有回调方法均提供默认空实现，调用方可按需覆写，回调均在主线程（UI 线程）触发。
+
+|回调方法|说明|
+|---------|---------|
+|onReceiveBotText(String text)|收到机器人回复的文本内容。|
+|onReceiveAsrText(String text)|收到语音识别（ASR）结果文本。|
+|onBotStateChanged(TXIoTAITalkSession.BotState oldState, TXIoTAITalkSession.BotState newState)|机器人状态变更，oldState 为变更前状态，newState 为变更后状态。|
+|onLaunchCall(Contact contact)|机器人发起呼叫，contact 为被呼叫的联系人。|
+|onError(int errorCode, String errorMsg)|发生错误，errorCode 为错误码，errorMsg 为错误描述。|
+
+### 数据结构
+
+以下类型定义于 `TXIoTAITalkSession` 接口中，作为 AI 对话相关接口的共用数据类型。
+
+#### TXIoTAITalkSession.Params
+
+AI 对话参数，在 `startSpeak` 接口中使用，用于指定对话所使用的 Bot 及提示词变量。
+
+|字段|说明|
+|---------|---------|
+|botId|`String`；对话机器人（Bot）ID。|
+|promptVariablesJson|`String`；提示词变量（JSON 字符串）。|
+
+#### TXIoTAITalkSession.Contact
+
+参与对话的联系人，在 `startSpeak` 及 `Listener.onLaunchCall` 回调中使用。
+
+|字段|说明|
+|---------|---------|
+|userId|`String`；用户 ID。|
+|userName|`String`；用户昵称。|
+|avatarUrl|`String`；用户头像 URL。|
+
+#### TXIoTAITalkSession.BotState
+
+Bot 状态枚举，在 `Listener.onBotStateChanged` 回调中使用，用于表示对话机器人的当前状态。
+
+|枚举值|说明|
+|---------|---------|
+|UNKNOWN|未知状态。|
+|LISTENING|聆听中。|
+|THINKING|思考中。|
+|SPEAKING|发言中。|
+|INTERRUPTED|已被打断。|
+|FINISHED|已结束。|
+
+## 错误码 — TXIoTError
+
+错误码常量定义在 `TXIoTError` 类中，均为 `int` 类型，通过回调的 `onError(int code, String desc)` 返回。
+
+|错误码|值|说明|
+|---------|---------|---------|
+|SUCCESS|0|成功。|
+|FAILURE|-1|通用失败。|
+|OUT_OF_MEMORY|-2|内存不足。|
+|INVALID_ARGUMENT|-3|参数非法。|
+|NOT_INITIALIZED|-4|未初始化。|
+|ALREADY_INITIALIZED|-5|已初始化。|
+|NOT_CONNECTED|-6|未连接。|
+|ALREADY_CONNECTED|-7|已连接。|
+|CONNECT_FAILED|-8|连接失败。|
+|POST_TASK_FAILED|-9|任务提交失败。|
+|NOT_LOGGED_IN|-15|未登录。|
+|AV_ON_IDLE|-10|音视频处于空闲状态。|
+|AV_ON_OUTGOING|-11|音视频处于呼出状态。|
+|AV_ON_RINGING|-12|音视频处于振铃状态。|
+|AV_ON_CALLING|-13|音视频处于通话中状态。|
+|AV_ON_IPC_MONITOR|-14|处于 IPC 监控状态。|
+|DYNAMIC_REGISTER_BUSY|-20|动态注册忙碌。|
+|DYNAMIC_REGISTER_REQUEST_FAILED|-21|动态注册请求失败。|
+|DYNAMIC_REGISTER_RESPONSE_INVALID|-22|动态注册响应无效。|
+|NTP_TIME_NOT_READY|-30|NTP 时间未就绪。|
+|CLOUD_STORAGE_CHANNEL_NOT_FOUND|-100|云存储通道未找到。|
+|CLOUD_STORAGE_PLANS_QUERY_FAILED|-101|云存储套餐查询失败。|
+|CLOUD_STORAGE_NO_PLAN|-102|无云存储套餐。|
+|CLOUD_STORAGE_EVENT_NOT_FOUND|-103|云存储事件未找到。|
+|CLOUD_STORAGE_REPORT_FAILED|-104|云存储上报失败。|
+|CLOUD_STORAGE_PIC_UPLOAD_FAILED|-105|云存储图片上传失败。|
+|CLOUD_STORAGE_EVENT_CANCELLED|-106|云存储事件已取消。|
+|AITALK_NOT_SUPPORT|-200|AI 对话不支持。|
+|AITALK_BOT_LEAVED|-201|AI 对话机器人已离开。|
+|AITALK_INVALID_PARAM|-202|AI 对话参数非法。|
+|AITALK_INTERNAL_ERROR|-203|AI 对话内部错误。|
+|AITALK_NOT_ACTIVATED|-204|AI 对话未激活。|
+|AITALK_SERVICE_EXPIRED|-205|AI 对话服务已过期。|
+|AITALK_ASR_ERROR|-206|AI 对话 ASR（语音识别）错误。|
+|AITALK_TTS_ERROR|-207|AI 对话 TTS（语音合成）错误。|
+|AITALK_LLM_ERROR|-208|AI 对话 LLM（大模型）错误。|
+|CONNECT_UNACCEPTABLE_PROTOCOL_VERSION|-301|连接协议版本不可接受。|
+|CONNECT_IDENTIFIER_REJECTED|-302|连接标识符被拒绝。|
+|CONNECT_SERVER_UNAVAILABLE|-303|连接服务器不可用。|
+|CONNECT_BAD_USERNAME_OR_PASSWORD|-304|连接用户名或密码错误。|
+|CONNECT_NOT_AUTHORIZED|-305|连接未授权。|
+
+## 通用回调
+
+### TXIoTCallback
+
+无返回值的异步回调，`onSuccess()` 表示操作成功；`onError(int code, String desc)` 携带错误码（见 `TXIoTError`）与描述信息。
+``` java
+public interface TXIoTCallback {
+    void onSuccess();
+
+    void onError(int code, String desc);
+}
+```
+
+### TXIoTValueCallback
+
+有返回值的异步回调，`T` 为回调成功时返回的结果类型：`onSuccess(T value)` 携带结果数据；`onError(int code, String desc)` 携带错误码（见 `TXIoTError`）与描述信息。
+``` java
+public interface TXIoTValueCallback<T> {
+    void onSuccess(T value);
+
+    void onError(int code, String desc);
+}
+```