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

package/resource/knowledge/iot/client-api/app/harmonyos/txiotengine.md

@@ -0,0 +1,186 @@
+---
+product: iot
+framework:
+  - harmonyos
+types:
+  - api
+retrievable_scope: always
+feature_domain: client_api
+---
+
+## 概述
+
+`TXIoTEngine` 是整个 SDK 的入口，通过全局函数 `getIoTEngineInstance()` 获取单例，使用前须先调用 `login` 完成身份验证。
+
+> **说明：**
+> 线程模型：SDK 接口可在任意线程调用；回调均在主线程（UI 线程）触发，调用方可在回调中直接操作 UI。
+>
+
+SDK 模块总览：
+
+|模块|说明|
+|---------|---------|
+|TXIoTEngine 引擎管理|登录、获取各个业务对象。|
+|TXIoTFamilyManager 家庭与房间管理|家庭、房间、成员管理。|
+|TXIoTDeviceManager 设备管理|设备绑定/解绑、分享、指令下发、属性查询。|
+|TXIoTCallSession 音视频通话|音视频通话。|
+|TXIoTMonitorSession 监控直播|监控直播（拉流/对讲/云台/截图/录像）。|
+|TXIoTCloudStorage 云存|设备云端录像的日期与事件查询。|
+|TXIoTEngineDef 公共类型与枚举|错误码、通用枚举、公共数据结构、回调接口。|
+
+## 方法列表
+
+|方法签名|描述|
+|---------|---------|
+|`getIoTEngineInstance`|获取 TXIoTEngine 单例（全局函数）。|
+|`addListener`|添加引擎事件监听器。|
+|`removeListener`|移除引擎事件监听器。|
+|`login`|登录 SDK（异步）。|
+|`logout`|登出 SDK。|
+|`getLoginUserInfo`|获取当前登录用户信息。|
+|`getFamilyManager`|获取家庭管理器，未登录时返回 null。|
+|`getDeviceManager`|获取设备管理器，未登录时返回 null。|
+|`getCallSession`|获取音视频通话会话，未登录时返回 null。|
+|`getMonitorSession`|获取实时监控会话，未登录时返回 null。|
+|`getCloudStorage`|获取指定设备的云存功能模块。|
+
+### getIoTEngineInstance
+
+**获取 TXIoTEngine 单例（全局函数）**
+
+|参数|描述|
+|---------|---------|
+|context|`Context`；Ability 上下文，可选。传入后 SDK 内部初始化时使用。|
+
+|返回值|描述|
+|---------|---------|
+|TXIoTEngine|返回 TXIoTEngine 单例实例。|
+
+### addListener
+
+**添加引擎事件监听器**
+
+|参数|描述|
+|---------|---------|
+|listener|`TXIoTEngineListener`；监听器实例。|
+
+### removeListener
+
+**移除引擎事件监听器**
+
+|参数|描述|
+|---------|---------|
+|listener|`TXIoTEngineListener`；监听器实例。|
+
+### login
+
+**登录 SDK（异步）**
+
+|参数|描述|
+|---------|---------|
+|appKey|`string`；应用 Key。|
+|userId|`string`；用户 ID。|
+|userSignature|`TXIoTUserSignature`；用户身份签名（含 requestId / timestamp / nonce / signature）。|
+
+### logout
+
+**登出 SDK**
+
+### getLoginUserInfo
+
+**获取当前登录用户信息**
+
+|返回值|描述|
+|---------|---------|
+|TXIoTUserInfo \| null|返回 TXIoTUserInfo 对象；未登录时返回 `null`。|
+
+### getFamilyManager
+
+**获取家庭管理器（登录后可用）**
+
+|返回值|描述|
+|---------|---------|
+|TXIoTFamilyManager \| null|返回 TXIoTFamilyManager 实例；未登录时返回 `null`。|
+
+### getDeviceManager
+
+**获取设备管理器（登录后可用）**
+
+|返回值|描述|
+|---------|---------|
+|TXIoTDeviceManager \| null|返回 TXIoTDeviceManager 实例；未登录时返回 `null`。|
+
+### getCallSession
+
+**获取音视频通话会话（登录后可用）**
+
+|返回值|描述|
+|---------|---------|
+|TXIoTCallSession \| null|返回 TXIoTCallSession 实例；未登录时返回 `null`。|
+
+### getMonitorSession
+
+**获取实时监控会话（登录后可用）**
+
+|返回值|描述|
+|---------|---------|
+|TXIoTMonitorSession \| null|返回 TXIoTMonitorSession 实例；未登录时返回 `null`。|
+
+### getCloudStorage
+
+**获取指定设备的云存功能模块**
+
+|参数|描述|
+|---------|---------|
+|deviceId|TXIoTDeviceId；设备标识（含 productId / deviceName）。|
+
+|返回值|描述|
+|---------|---------|
+|TXIoTCloudStorage \| null|返回该设备的 TXIoTCloudStorage 实例；`deviceId` 非法（productId 或 deviceName 为空）时返回 `null`。|
+
+## 引擎事件回调
+
+`TXIoTEngineListener` 为 ArkTS 接口，所有回调方法均为可选，调用方可按需实现。
+
+|回调方法|说明|
+|---------|---------|
+|`onLoginSuccess()`|登录成功。登录成功后各业务模块 getter 生效。|
+|`onLoginFailure(errCode: TXIoTErrorCode, errMsg: string)`|登录失败。errCode 为错误码，errMsg 为错误描述。|
+|`onLogout()`|登出完成。各业务模块 getter 失效。|
+|`onUserSignatureExpired()`|用户签名已过期，需重新获取签名后调用 `login`。|
+|`onReceivePushMessage(pushMessage: TXIoTPushMessage)`|收到服务器推送消息，包含设备上下线等状态变更通知。|
+
+## 引擎相关数据结构与枚举
+
+### TXIoTPushMessage
+
+**设备推送消息，包含消息时间、类型和关联设备**
+
+|字段|说明|
+|---------|---------|
+|messageTime|消息时间戳。|
+|type|消息类型，见 `TXIoTPushMessageType`。|
+|subType|消息子类型，见 `TXIoTPushMessageSubType`。|
+|deviceId|关联的设备 ID。|
+
+### TXIoTPushMessageType
+
+|枚举|说明|
+|---------|---------|
+|STATUS_CHANGE|设备状态变更。|
+
+### TXIoTPushMessageSubType
+
+|枚举|说明|
+|---------|---------|
+|ONLINE|设备上线。|
+|OFFLINE|设备离线。|
+
+### TXIoTUserSignature
+
+|字段|说明|
+|---------|---------|
+|requestId|请求 ID，由服务端签发。|
+|timestamp|签名的 Unix 秒级时间戳。|
+|nonce|签名随机数。|
+|signature|签名字符串，由服务端签发。|

package/resource/knowledge/iot/client-api/app/harmonyos/txiotenginedef.md

@@ -0,0 +1,164 @@
+---
+product: iot
+framework:
+  - harmonyos
+types:
+  - api
+retrievable_scope: always
+feature_domain: client_api
+---
+
+## 概述
+
+本文档描述 IoT App SDK 在鸿蒙端的公共类型与枚举定义，包含错误码、通用枚举、公共数据结构与通用回调等，定义于 `TXIoTEngineDef` 模块中。
+
+> **说明：**
+> `TXIoTEngineDef` 是各模块共用的基础类型定义模块，其他模块均从 SDK 的公共导出中引入。各模块文档见：
+>
+> - TXIoTEngine：引擎管理。
+> - TXIoTFamilyManager：家庭与房间管理。
+> - TXIoTDeviceManager：设备管理。
+> - TXIoTCallSession：音视频通话。
+> - TXIoTMonitorSession：实时监控。
+> - TXIoTCloudStorage：云存。
+
+## 错误码 — TXIoTErrorCode
+
+|错误码|说明|
+|---------|---------|
+|ERR_SUCCESS|成功。|
+|ERR_FAILED|通用失败。|
+|ERR_INVALID_PARAMETER|参数非法。|
+|ERR_INVALID_ACCESS_TOKEN|Access Token 无效。|
+|ERR_RATE_LIMITED|请求频率超限。|
+|ERR_UNAUTHORIZED_OPERATION|未授权操作。|
+|ERR_DEVICE_BOUND|设备已绑定。|
+|ERR_BIND_TOKEN_NOT_EXIST|绑定令牌不存在。|
+|ERR_BIND_TOKEN_IS_EXPIRED|绑定令牌已过期。|
+|ERR_BIND_TOKEN_NO_PAIR_WITH_DEVICE|绑定令牌与设备不匹配。|
+|ERR_INVALID_MESSAGE_ID|消息 ID 无效。|
+|ERR_FAMILY_DEVICE_LIMIT_EXCEEDED|家庭设备数量超限。|
+|ERR_CAN_NOT_BIND_SAME_FAMILY|不能绑定到同一家庭。|
+|ERR_FAMILY_NOT_EXIST|家庭不存在。|
+|ERR_PRODUCT_NOT_EXIST|产品不存在。|
+|ERR_DEVICE_NOT_EXIST|设备不存在。|
+|ERR_DEVICE_OFFLINE|设备离线。|
+|ERR_CAMERA_START_FAIL|摄像头启动失败。|
+|ERR_CAMERA_NOT_AUTHORIZED|摄像头权限未授权。|
+|ERR_CAMERA_OCCUPY|摄像头被占用。|
+|ERR_MIC_START_FAIL|麦克风启动失败。|
+|ERR_MIC_NOT_AUTHORIZED|麦克风权限未授权。|
+|ERR_MIC_OCCUPY|麦克风被占用。|
+|ERR_SPEAKER_START_FAIL|扬声器启动失败。|
+|ERR_RECORD_DURATION_TOO_SHORT|录制时长过短。|
+|ERR_FILE_PATH_UNWRITABLE|文件路径不可写。|
+|ERR_FILE_PATH_ALREADY_EXIST|文件路径已存在。|
+|ERR_DEVICE_SWITCH_TO_VOIP|设备切换到 VOIP 模式。|
+
+## 通用枚举
+
+### TXIoTFamilyRole
+
+家庭角色枚举。在 TXIoTFamilyManager 的成员管理接口中使用。
+
+|枚举|说明|
+|---------|---------|
+|UNKNOWN|未知。|
+|MEMBER|普通成员。|
+|ADMIN|管理员。|
+
+## 公共数据结构
+
+以下类型定义于 `TXIoTEngineDef` 模块中，作为 SDK 内部共用数据类型。
+
+### TXIoTDeviceId
+
+设备 ID，用于唯一标识一个设备。在 TXIoTDeviceManager 的绑定、查询接口中使用。
+
+|字段|说明|
+|---------|---------|
+|productId|产品 ID。|
+|deviceName|设备名称。|
+
+### TXIoTDeviceStatus
+
+设备在线状态。包含当前在线情况、累计在线时长和上线时间戳。在 TXIoTDeviceManager 的设备信息中包含此字段。
+
+|字段|说明|
+|---------|---------|
+|isOnline|是否在线。|
+|onlineDuration|累计在线时长（单位：秒）。|
+|bringOnlineTime|上线时间戳（Unix 秒级时间戳）。|
+
+### TXIoTDeviceInfo
+
+设备信息。在 TXIoTDeviceManager 的绑定、设备列表、被分享设备列表等查询接口中返回。
+
+|字段|说明|
+|---------|---------|
+|deviceId|设备 ID。|
+|aliasName|设备别名。|
+|familyId|所属家庭 ID。|
+|roomId|所属房间 ID。|
+|iconUrl|设备图标 URL。|
+|createTime|创建时间（Unix 秒级时间戳）。|
+|updateTime|更新时间（Unix 秒级时间戳）。|
+|status|设备在线状态，见 `TXIoTDeviceStatus`。|
+
+### TXIoTFamilyInfo
+
+家庭信息。在 TXIoTFamilyManager 的创建、查询接口中使用。
+
+|字段|说明|
+|---------|---------|
+|familyId|家庭 ID。|
+|name|家庭名称。|
+|createTime|创建时间（Unix 秒级时间戳）。|
+|updateTime|更新时间（Unix 秒级时间戳）。|
+|role|当前用户在该家庭中的角色，见 `TXIoTFamilyRole`。|
+
+### TXIoTRoomInfo
+
+房间信息。房间是家庭下的二级分组，在 TXIoTFamilyManager 的房间管理接口中使用。
+
+|字段|说明|
+|---------|---------|
+|roomId|房间 ID。|
+|name|房间名称。|
+|familyId|所属家庭 ID。|
+|deviceCount|房间内设备数量。|
+|createTime|创建时间（Unix 秒级时间戳）。|
+|updateTime|更新时间（Unix 秒级时间戳）。|
+
+### TXIoTUserInfo
+
+用户信息。在 TXIoTFamilyManager 的成员管理和 TXIoTDeviceManager 的设备分享接口中使用。
+
+|字段|说明|
+|---------|---------|
+|userId|用户 ID。|
+|nickName|用户昵称。|
+|avatarUrl|用户头像 URL。|
+|role|用户角色，见 `TXIoTFamilyRole`。|
+|deviceBindTime|设备绑定时间（Unix 秒级时间戳）。|
+
+### TXIoTPageResult
+
+分页查询结果。`T` 为数据列表元素类型。在 TXIoTDeviceManager 的设备列表分页查询中使用：首次查询时 `nextPageToken` 传空，结果中返回的 `nextPageToken` 用于获取下一页。
+
+|字段|说明|
+|---------|---------|
+|nextPageToken|下一页游标；首次查询传空字符串，取结果中返回值用于获取下一页；为空字符串表示已到最后一页。|
+|dataList|当前页数据列表。|
+
+## 通用回调
+
+### TXIoTCallback
+
+有返回值的异步回调。在所有业务模块（TXIoTDeviceManager、TXIoTFamilyManager 等）中广泛使用。`T` 为回调成功时返回的结果类型：`onSuccess` 携带结果数据；`onError` 携带错误码与描述信息。无返回值的接口使用 `TXIoTCallback<void>`。
+``` typescript
+interface TXIoTCallback<T> {
+  onSuccess(result: T): void;
+  onError(errorCode: TXIoTErrorCode, errorMessage: string): void;
+}
+```

package/resource/knowledge/iot/client-api/app/harmonyos/txiotfamilymanager.md

@@ -0,0 +1,150 @@
+---
+product: iot
+framework:
+  - harmonyos
+types:
+  - api
+retrievable_scope: always
+feature_domain: client_api
+---
+
+## 概述
+
+TXIoTFamilyManager 负责家庭的创建/删除/更新、房间的创建/删除/重命名，以及家庭成员的邀请与管理。TXIoTFamilyManager 通过 TXIoTEngine.getFamilyManager 获取实例，需在登录成功后调用。
+
+> **说明：**
+> 家庭是设备的顶层组织单元，房间是家庭下的二级分组。用户创建家庭后自动成为 ADMIN，可通过 `createFamilyInviteToken` 生成邀请令牌，其他用户通过 `joinFamilyAsMember` 加入。
+>
+
+## 方法列表
+
+|方法签名|描述|
+|---------|---------|
+|`createFamily`|创建家庭。|
+|`deleteFamily`|删除家庭。|
+|`getFamilyList`|获取当前用户的家庭列表。|
+|`updateFamilyInfo`|更新家庭信息（如名称）。|
+|`createRoom`|在指定家庭下创建房间。|
+|`deleteRoom`|删除指定房间。|
+|`setRoomName`|设置/修改房间名称。|
+|`getRoomList`|获取指定家庭的房间列表。|
+|`createFamilyInviteToken`|创建家庭邀请令牌。|
+|`joinFamilyAsMember`|通过令牌加入家庭。|
+|`removeMemberFromFamily`|从家庭中移除成员。|
+|`getMemberList`|获取家庭成员列表。|
+
+### createFamily
+
+**创建家庭**
+
+|参数|描述|
+|---------|---------|
+|name|`string`；家庭名称。|
+|callback|`TXIoTCallback<TXIoTFamilyInfo>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### deleteFamily
+
+**删除家庭**
+
+|参数|描述|
+|---------|---------|
+|familyId|`string`；家庭 ID。|
+|callback|`TXIoTCallback<void>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### getFamilyList
+
+**获取当前用户的家庭列表**
+
+|参数|描述|
+|---------|---------|
+|callback|`TXIoTCallback<TXIoTFamilyInfo[]>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### updateFamilyInfo
+
+**更新家庭信息（如名称）**
+
+|参数|描述|
+|---------|---------|
+|newFamilyInfo|TXIoTFamilyInfo；家庭信息对象，familyId 必填。|
+|callback|`TXIoTCallback<void>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### createRoom
+
+**在指定家庭下创建房间**
+
+|参数|描述|
+|---------|---------|
+|familyId|`string`；家庭 ID。|
+|name|`string`；房间名称。|
+|callback|`TXIoTCallback<TXIoTRoomInfo>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### deleteRoom
+
+**删除指定房间**
+
+|参数|描述|
+|---------|---------|
+|familyId|`string`；家庭 ID。|
+|roomId|`string`；房间 ID。|
+|callback|`TXIoTCallback<void>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### setRoomName
+
+**设置/修改房间名称**
+
+|参数|描述|
+|---------|---------|
+|familyId|`string`；家庭 ID。|
+|roomId|`string`；房间 ID。|
+|name|`string`；房间名称。|
+|callback|`TXIoTCallback<void>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### getRoomList
+
+**获取指定家庭的房间列表**
+
+|参数|描述|
+|---------|---------|
+|familyId|`string`；家庭 ID。|
+|callback|`TXIoTCallback<TXIoTRoomInfo[]>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### createFamilyInviteToken
+
+**创建家庭邀请令牌**
+
+|参数|描述|
+|---------|---------|
+|familyId|`string`；家庭 ID。|
+|callback|`TXIoTCallback<string>`；异步回调，onSuccess 返回邀请令牌字符串。|
+
+### joinFamilyAsMember
+
+**通过令牌加入家庭**
+
+|参数|描述|
+|---------|---------|
+|inviteToken|`string`；邀请令牌。|
+|callback|`TXIoTCallback<void>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### removeMemberFromFamily
+
+**从家庭中移除成员**
+
+|参数|描述|
+|---------|---------|
+|familyId|`string`；家庭 ID。|
+|userId|`string`；用户 ID，取 `getMemberList` 返回的 `TXIoTUserInfo.userId` 原值。|
+|callback|`TXIoTCallback<void>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+### getMemberList
+
+**获取家庭成员列表**
+
+|参数|描述|
+|---------|---------|
+|familyId|`string`；家庭 ID。|
+|callback|`TXIoTCallback<TXIoTUserInfo[]>`；异步回调，通过 onSuccess / onError 通知结果。|
+
+> **注意：**
+> 该接口不支持分页，单次最多返回 50 条成员记录。
+>