From a547f4b89fbf82871a5de9bc31ddd1474e21c2f0 Mon Sep 17 00:00:00 2001 From: huangkai71 Date: Wed, 2 Jul 2025 20:30:25 +0800 Subject: [PATCH] add proxyChannelManager Signed-off-by: huangkai71 --- .../errorcode_proxyChannelManager.md | 174 ++++++ .../js-api-proxyChannelManager.md | 514 ++++++++++++++++++ 2 files changed, 688 insertions(+) create mode 100644 zh-cn/application-dev/reference/apis-distributedservice-kit/errorcode_proxyChannelManager.md create mode 100644 zh-cn/application-dev/reference/apis-distributedservice-kit/js-api-proxyChannelManager.md diff --git a/zh-cn/application-dev/reference/apis-distributedservice-kit/errorcode_proxyChannelManager.md b/zh-cn/application-dev/reference/apis-distributedservice-kit/errorcode_proxyChannelManager.md new file mode 100644 index 00000000000..d5bff45fb6f --- /dev/null +++ b/zh-cn/application-dev/reference/apis-distributedservice-kit/errorcode_proxyChannelManager.md @@ -0,0 +1,174 @@ +# 代理通道管理错误码 + +> **说明：** +> +> 以下仅介绍本模块特有错误码，通用错误码请参考[通用错误码说明文档](../errorcode-universal.md)。 + +## 32390001 蓝牙已关闭 + +**错误信息** + +BR is disabled. + +**错误描述** + +本端设备已关闭蓝牙。 + +**可能原因** + +本端设备蓝牙已关闭。 + +**处理步骤** + +打开本端设备蓝牙，重新尝试操作。 + +## 32390002 蓝牙未配对 + +**错误信息** + +Device not paired. + +**错误描述** + +本端设备蓝牙未配对成功。 + +**可能原因** + +1. 本端设备未与目标设备完成蓝牙配对。 +2. 对端设备的服务未起监听。 + +**处理步骤** + +1. 使用运动健康APP完成设备添加及配对。 +2. 检查目标设备服务监听情况。 + +## 32390004 通道ID非法或者不可用 + +**错误信息** + +ChannelId is invalid or unavailable. + +**错误描述** + +通道ID非法或者不可用。 + +**可能原因** + +1. 传入了非法的channelId，即该channelId不是openProxyChannel返回的channelId。 +2. 相关通道已关闭。 + +**处理步骤** + +1. 检查代码逻辑，确认传入的channelId是否为openProxyChannel返回的channelId。 +2. 检查代码逻辑，确认该channelId是否已经关闭然后继续使用。 + +## 32390006 参数错误 + +**错误信息** + +Parameter error. + +**错误描述** + +参数校验异常。 + +**可能原因** + +1. 传入的mac或者uuid格式异常。 +2. 函数入参类型错误。 + +**处理步骤** + +检查代码逻辑，确认mac和uuid的格式正确，以及入参类型正确。 + +## 32390100 内部异常 + +**错误信息** + +Internal error. + +**错误描述** + +内部异常。 + +**可能原因** + +系统错误，如空指针、内存不足、分布式服务异常重启、IPC异常、JS引擎异常等。 + +**处理步骤** + +尝试重试操作，如果依然无法解决，可以重启应用、升级应用或升级设备版本等。 + +## 32390101 调用受限 + +**错误信息** + +Call is restricted. + +**错误描述** + +非法调用，调用受限。 + +**可能原因** + +未授权进程进行了访问。 + +**处理步骤** + +申请对应权限。 + +## 32390102 操作失败或者连接超时 + +**错误信息** + +Operation failed or Connection timed out. + +**错误描述** + +操作失败或者连接超时。 + +**可能原因** + +底层蓝牙故障导致连接失败或者连接超时。 + +**处理步骤** + +1. 重新开关本端设备和目标设备的蓝牙。 +2. 重启本端设备和目标设备后，再打开设备的蓝牙。 + +## 32390103 发送数据超长 + +**错误信息** + +Data too long. + +**错误描述** + +发送数据超长。 + +**可能原因** + +发送的数据长度超过了4096个字节。 + +**处理步骤** + +检查发送的数据长度。 + +## 32390104 发送数据失败 + +**错误信息** + +Send failed. + +**错误描述** + +发送数据失败。 + +**可能原因** + +蓝牙故障。 + +**处理步骤** + +1. 尝试重启本端设备蓝牙和目标设备蓝牙。 +2. 尝试重启本端设备和目标设备。 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis-distributedservice-kit/js-api-proxyChannelManager.md b/zh-cn/application-dev/reference/apis-distributedservice-kit/js-api-proxyChannelManager.md new file mode 100644 index 00000000000..3d2a4dfb0ab --- /dev/null +++ b/zh-cn/application-dev/reference/apis-distributedservice-kit/js-api-proxyChannelManager.md @@ -0,0 +1,514 @@ +# @ohos.distributedsched.proxyChannelManager (代理通道管理) + +软总线具备常驻运行能力，可为跨设备通信提供稳定可靠的底层通道。本模块基于软总线进程开发，支持手机与穿戴设备间高效的数据互通，可为用户提供无缝的设备互联体验。模块核心功能包括：代理通道管理、数据路由管理、 应用状态感知和唤醒、链路状态监听。 + +- 代理通道管理：通过蓝牙 BR 协议建立手机与穿戴设备的双向数据通道，支持的数据通道 ID 范围是[1，2147483647] 。 + +- 数据路由管理：基于 UUID 服务识别机制，精准转发穿戴设备数据。 + +- 应用状态感知和唤醒：代理通道使能后，收到穿戴设备发送的数据后，动态分析和唤醒手机端对应应用进程。 + +- 全链路状态监控：通过回调实时感知通道连接状态。 + +> **说明：** +> +> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> +> 该套接口目前为Beta阶段，暂未开放申请。 + +## 导入模块 + +```js +import { proxyChannelManager } from '@kit.DistributedServiceKit'; +``` + +## 使用说明 + +调用模块接口前，需要完成如下配置。 + +1. 需要申请ohos.permission.ACCESS_BLUETOOTH权限。如何配置和申请权限，具体操作请参考[声明权限](../../security/AccessToken/declare-permissions.md)和[向用户申请授权](../../security/AccessToken/request-user-authorization.md)。 + +2. 对于需要代理拉起的应用进程，需要在module.json5文件中配置action字段: "action.ohos.pull.listener"。 + +## proxyChannelManager.openProxyChannel + +openProxyChannel(channelInfo: ChannelInfo): Promise<number> + +打开代理通道，使用Promise异步回调返回结果。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------------- | ---- | -------- | +| channelInfo | [ChannelInfo](#channelinfo) | 是 | 对端设备及服务的MAC和UUID信息。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ---------------- | +|  Promise<number> | 返回代理通道的channelId，取值范围为1~2147483647。channelId的生命周期和代理通道生命周期相同，不关闭代理时，传入相同入参将返回相同channelId。 | + +**错误码：** + +以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------------------------------- | +| 201 | Permission denied.| +| 32390001 | BR is disabled.| +| 32390002 | Device not paired. | +| 32390006 | Parameter error.| +| 32390100 | Internal error.| +| 32390101 | Call is restricted.| +| 32390102 | Operation failed or Connection timed out.| + +**示例：** + +```ts +import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager'; +import { BusinessError } from '@ohos.base'; +@Entry +@Component +struct Index { + build() { + RelativeContainer() { + Button("测试") + .onClick(() => { + let channelInfo: proxyChannelManager.ChannelInfo = { + linkType: proxyChannelManager.LinkType.LINK_BR, + peerDevAddr: "xx:xx:xx:xx:xx:xx", //穿戴设备蓝牙mac + peerUuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", //穿戴侧监听的uuid + }; + // 以下为使用 try/catch 判断 + try { + proxyChannelManager.openProxyChannel(channelInfo) + .then((channelId: number) => { + // 获得通道id + }) + .catch((error: BusinessError) => { + console.error(`getErr: ${error.code} ${error.message}`); + }); + } catch (err) { + let error = err as BusinessError; + console.error(`getErr: ${error.code} ${error.message}`); + // 如果 code:undefined message:"Cannot read property openProxyChannel of undefined"， 则这个 API 在当前镜像不支持 + } + }) + } + .height('100%') + .width('100%') + } +} +``` + +## proxyChannelManager.closeProxyChannel + +closeProxyChannel(channelId: number): void + +关闭已打开的代理通道。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------------- | ---- | -------- | +| channelId | number | 是 | 打开代理通道时获取的channelId。 | + +**错误码：** + +以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------------------------------- | +| 201 | Permission denied.| +| 32390004 | ChannelId is invalid or unavailable.| +| 32390006 | Parameter error.| +| 32390100 | Internal error.| +| 32390101 | Call is restricted.| + +**示例：** + +```ts +import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager'; +import { BusinessError } from '@ohos.base'; +@Entry +@Component +struct Index { + build() { + RelativeContainer() { + Button("测试") + .onClick(() => { + // 以下为使用 try/catch 判断 + try { + proxyChannelManager.closeProxyChannel(1); // 假设通道id为1 + } catch (err) { + let error = err as BusinessError; + console.error(`getErr: ${error.code} ${error.message}`); + // 如果 code:undefined message:"Cannot read property closeProxyChannel of undefined"， 则这个 API 在当前镜像不支持 + } + }) + } + .height('100%') + .width('100%') + } +} +``` + +## proxyChannelManager.sendData + +sendData(channelId:number, data:ArrayBuffer):Promise<void> + +向对端发送数据，使用Promise异步回调。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------------- | ---- | -------- | +| channelId | number | 是 | 打开代理通道时获取的channelId。 | +| data | ArrayBuffer | 是 | 向对端发送的字节消息，长度最大为4096个字节。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ---------------- | +|  Promise<void> | 无返回值的Promise的对象。 | + +**错误码：** + +以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------------------------------- | +| 201 | Permission denied.| +| 32390004 | ChannelId is invalid or unavailable.| +| 32390006 | Parameter error.| +| 32390100 | Internal error.| +| 32390101 | Call is restricted.| +| 32390103 | Data too long.| +| 32390104 | Send failed.| + +**示例：** + +```ts +import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager'; +import { BusinessError } from '@ohos.base'; +@Entry +@Component +struct Index { + build() { + RelativeContainer() { + Button("测试") + .onClick(() => { + const data = new ArrayBuffer(10); // 创建一个长度为 10 的 ArrayBuffer + try { + proxyChannelManager.sendData(1, data) // 假设通道id为1 + .then(() => { + }) + .catch((error: BusinessError) => { + console.error(`getErr: ${error.code} ${error.message}`); + }); + }catch (err) { + let error = err as BusinessError; + console.error(`getErr: ${error.code} ${error.message}`); + } + }) + } + .height('100%') + .width('100%') + } +} +``` + +## proxyChannelManager.on('receiveData') + +on(type: 'receiveData', channelId: number, callback: Callback<DataInfo>): void + +订阅数据接收事件，使用异步回调。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------------- | ---- | -------- | +| type | string | 是 | 设置订阅类型，固定取值为'receiveData'。| +| channelId | number | 是 | 打开代理通道时获取的channelId。 | +| callback | Callback<[DataInfo](#datainfo)> | 是 | 回调函数，返回接收到的数据。多次注册回调函数，最后一次注册的回调函数生效。 | + +**错误码：** + +以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------------------------------- | +| 201 | Permission denied.| +| 32390004 | ChannelId is invalid or unavailable.| +| 32390006 | Parameter error.| +| 32390100 | Internal error.| +| 32390101 | Call is restricted.| + +**示例：** + +```ts +import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager'; +import { BusinessError } from '@ohos.base'; +@Entry +@Component +struct Index { + build() { + RelativeContainer() { + Button("测试") + .onClick(() => { + const receiveDataCallback = (dataInfo: proxyChannelManager.DataInfo) => { + }; + try{ + proxyChannelManager.on('receiveData', 1, receiveDataCallback); // 假设通道id为1 + } catch(err) { + let error = err as BusinessError; + console.error(`register receiveData error: ${error.code} ${error.message}`); + } + }) + } + .height('100%') + .width('100%') + } +} +``` + +## proxyChannelManager.off('receiveData') + +off(type: 'receiveData', channelId: number, callback?: Callback<DataInfo>): void + +取消订阅数据接收事件，停止接收数据。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------------- | ---- | -------- | +| type | string | 是 | 设置订阅类型，固定取值为'receiveData'。| +| channelId | number | 是 | 打开代理通道时获取的channelId。 | +| callback | Callback<[DataInfo](#datainfo)> | 否 | 注册的回调函数。 | + +**错误码：** + +以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------------------------------- | +| 201 | Permission denied.| +| 32390004 | ChannelId is invalid or unavailable.| +| 32390006 | Parameter error.| +| 32390100 | Internal error.| +| 32390101 | Call is restricted.| + +**示例：** + +```ts +import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager'; +import { BusinessError } from '@ohos.base'; +@Entry +@Component +struct Index { + build() { + RelativeContainer() { + Button("测试") + .onClick(() => { + try{ + proxyChannelManager.off('receiveData', 1); // 假设通道id为1 + } catch(err) { + let error = err as BusinessError; + console.error(`getErr: ${error.code} ${error.message}`); + } + }) + } + .height('100%') + .width('100%') + } +} +``` + +## proxyChannelManager.on('channelStateChange') + +on(type: 'channelStateChange', channelId: number, callback: Callback<ChannelStateInfo>): void + +订阅通道状态事件，使用callback进行异步回调。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------------- | ---- | -------- | +| type | string | 是 | 设置订阅类型，固定取值为'channelStateChange'。| +| channelId | number | 是 | 打开代理通道时获取的channelId。 | +| callback | Callback<[ChannelStateInfo](#channelstateinfo)> | 是 | 回调函数，返回接收到的通道状态。多次注册callback，最后一次注册的callback生效 | + +**错误码：** + +以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------------------------------- | +| 201 | Permission denied.| +| 32390004 | ChannelId is invalid or unavailable.| +| 32390006 | Parameter error.| +| 32390100 | Internal error.| +| 32390101 | Call is restricted.| + +**示例：** + +```ts +import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager'; +import { BusinessError } from '@ohos.base'; +@Entry +@Component +struct Index { + build() { + RelativeContainer() { + Button("测试") + .onClick(() => { + const receiveStatusCallback = (channelStateInfo: proxyChannelManager.ChannelStateInfo) => { + }; + try{ + proxyChannelManager.on('channelStateChange', 1, receiveStatusCallback); // 假设打开的通道id为1 + } catch(err) { + let error = err as BusinessError; + console.error(`getErr: ${error.code} ${error.message}`); + } + }) + } + .height('100%') + .width('100%') + } +} +``` + +## proxyChannelManager.off('channelStateChange') + +off(type: 'channelStateChange', channelId: number, callback?: Callback<ChannelStateInfo>): void + +取消订阅通道状态事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------------- | ---- | -------- | +| type | string | 是 | 设置订阅类型为'channelStateChange'。| +| channelId | number | 是 | 打开代理通道时获取的channelId。 | +| callback | Callback<[ChannelStateInfo](#channelstateinfo)> | 否 | 注册的回调函数。 | + +**错误码：** + +以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------------------------------- | +| 201 | Permission denied.| +| 32390004 | ChannelId is invalid or unavailable.| +| 32390006 | Parameter error.| +| 32390100 | Internal error.| +| 32390101 | Call is restricted.| + +**示例：** + +```ts +import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager'; +import { BusinessError } from '@ohos.base'; +@Entry +@Component +struct Index { + build() { + RelativeContainer() { + Button("测试") + .onClick(() => { + try{ + proxyChannelManager.off('channelStateChange', 1); // 假设打开的通道id为1 + } catch(err) { + let error = err as BusinessError; + console.error(`getErr: ${error.code} ${error.message}`); + } + }) + } + .height('100%') + .width('100%') + } +} +``` + +## DataInfo + +存放接收的数据信息，包括通道Id和数据。 + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| --------- | ---------------------------------------- | ---- | ---- | -------- | +| channelId | number | 否 | 否 | 代理通道的channelId。 | +| data | ArrayBuffer | 否 | 否 | 接收到的字节数据。 | + +## ChannelInfo + +打开代理通道函数的入参，包括对端设备的MAC地址和监听服务的UUID。 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| --------- | ---------------------------------------- | ---- | ---- | -------- | +| linkType | [LinkType](#linktype) | 否 | 否 | 代理通道的链路类型。 | +| peerDevAddr | string | 否 | 否 | 对端设备的MAC地址。 | +| peerUuid | string | 否 | 否 | 对端监听的服务的UUID。 | + +## ChannelStateInfo + +当代理通道状态变化时，用于表示代理通道的连接状态。 + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| --------- | ---------------------------------------- | ---- | ---- | -------- | +| channelId | number | 否 | 否 | 代理通道的channelId。 | +| state | [ChannelState](#channelstate) | 否 | 否 | 通道的连接状态。 | + +## ChannelState + +通道状态发生变化时，代理通道上报的通道连接状态。 + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +| 名称 | 值 | 说明 | +| --------- | ---------------------------------------- | -------- | +| CHANNEL_WAIT_RESUME | 0 | 连接已断开，通道不可用。 | +| CHANNEL_RESUME | 1 | 连接已恢复，通道可用。 | +| CHANNEL_EXCEPTION_SOFTWARE_FAILED | 2 | 其他软件错误导致通道不可用。 | +| CHANNEL_BR_NO_PAIRED | 3 | 蓝牙配对关系被删除，通道不可用。 | + +## LinkType + +链路类型。 + +**系统能力**：SystemCapability.DistributedSched.AppCollaboration + +| 名称 | 值 | 说明 | +| --------- | ---------------------------------------- | -------- | +| LINK_BR | 0 | 蓝牙。 | \ No newline at end of file -- Gitee