• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.distributedsched.proxyChannelManager (代理通道管理)
2
3软总线具备常驻运行能力，可为跨设备通信提供稳定可靠的底层通道。本模块基于软总线进程开发，支持手机与穿戴设备间高效的数据互通，可为用户提供无缝的设备互联体验。使用场景：手机侧APP与手表侧APP协同时，当手机APP不在前台被使用，手机应用的下行消息经由通知服务器，通过代理模块发送给手表侧。模块核心功能包括：代理通道管理、数据路由管理、 应用状态感知和唤醒、链路状态监听。
4
5- 代理通道管理：通过蓝牙 BR 协议建立手机与穿戴设备的双向数据通道，支持的数据通道 ID 范围是[1，2147483647] 。
6
7- 数据路由管理：基于 UUID 服务识别机制，精准转发穿戴设备数据。
8
9- 应用状态感知和唤醒：代理通道使能后，收到穿戴设备发送的数据后，动态分析和唤醒手机端对应应用进程。
10
11- 全链路状态监控：通过回调实时感知通道连接状态。
12
13> **说明：**
14>
15> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
16
17## 导入模块
18
19```js
20import { proxyChannelManager } from '@kit.DistributedServiceKit';
21```
22
23## 使用说明
24
25调用模块接口前，需要完成如下配置。
26
271. 需要申请ohos.permission.ACCESS_BLUETOOTH权限。如何配置和申请权限，具体操作请参考[声明权限](../../security/AccessToken/declare-permissions.md)和[向用户申请授权](../../security/AccessToken/request-user-authorization.md)。
28
292. 对于需要代理拉起的应用进程，需要在module.json5文件中配置action字段: "action.ohos.pull.listener"。
30
31## proxyChannelManager.openProxyChannel
32
33openProxyChannel(channelInfo: ChannelInfo): Promise<number>
34
35打开代理通道，使用Promise异步回调返回结果。
36
37**需要权限**：ohos.permission.ACCESS_BLUETOOTH
38
39**系统能力**：SystemCapability.DistributedSched.AppCollaboration
40
41**参数：**
42
43| 参数名       | 类型                                       | 必填   | 说明       |
44| --------- | ---------------------------------------- | ---- | -------- |
45| channelInfo | [ChannelInfo](#channelinfo) | 是    | 对端设备及服务的MAC和UUID信息。  |
46
47**返回值：**
48
49| 类型                  | 说明               |
50| ------------------- | ---------------- |
51|  Promise<number> | 返回代理通道的channelId，取值范围为1~2147483647。channelId的生命周期和代理通道生命周期相同，不关闭代理时，传入相同入参将返回相同channelId。 |
52
53**错误码：**
54
55以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。
56
57| 错误码ID | 错误信息 |
58| ------- | -------------------------------- |
59| 201      | Permission denied.|
60| 32390001      | BR is disabled.|
61| 32390002 | Device not paired.  |
62| 32390006 | Parameter error.|
63| 32390100 | Internal error.|
64| 32390101 | Call is restricted.|
65| 32390102 | Operation failed or Connection timed out.|
66
67**示例：**
68
69```ts
70import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager';
71import { BusinessError } from '@ohos.base';
72@Entry
73@Component
74struct Index {
75  build() {
76    RelativeContainer() {
77      Button("测试")
78        .onClick(() => {
79          let channelInfo: proxyChannelManager.ChannelInfo = {
80            linkType: proxyChannelManager.LinkType.LINK_BR,
81            peerDevAddr: "xx:xx:xx:xx:xx:xx", //穿戴设备蓝牙mac
82            peerUuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", //穿戴侧监听的uuid
83          };
84          // 以下为使用 try/catch 判断
85          try {
86            proxyChannelManager.openProxyChannel(channelInfo)
87              .then((channelId: number) => {
88                // 获得通道id
89              })
90              .catch((error: BusinessError) => {
91                console.error(`getErr: ${error.code} ${error.message}`);
92              });
93          } catch (err) {
94            let error = err as BusinessError;
95            console.error(`getErr: ${error.code} ${error.message}`);
96            // 如果 code:undefined message:"Cannot read property openProxyChannel of undefined"， 则这个 API 在当前镜像不支持
97          }
98        })
99    }
100    .height('100%')
101    .width('100%')
102  }
103}
104```
105
106## proxyChannelManager.closeProxyChannel
107
108closeProxyChannel(channelId: number): void
109
110关闭已打开的代理通道。
111
112**需要权限**：ohos.permission.ACCESS_BLUETOOTH
113
114**系统能力**：SystemCapability.DistributedSched.AppCollaboration
115
116**参数：**
117
118| 参数名       | 类型                                       | 必填   | 说明       |
119| --------- | ---------------------------------------- | ---- | -------- |
120| channelId | number | 是    | 打开代理通道时获取的channelId。 |
121
122**错误码：**
123
124以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。
125
126| 错误码ID | 错误信息 |
127| ------- | -------------------------------- |
128| 201      | Permission denied.|
129| 32390004 | ChannelId is invalid or unavailable.|
130| 32390006 | Parameter error.|
131| 32390100 | Internal error.|
132| 32390101 | Call is restricted.|
133
134**示例：**
135
136```ts
137import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager';
138import { BusinessError } from '@ohos.base';
139@Entry
140@Component
141struct Index {
142  build() {
143    RelativeContainer() {
144      Button("测试")
145        .onClick(() => {
146          // 以下为使用 try/catch 判断
147          try {
148            proxyChannelManager.closeProxyChannel(1);  // 假设通道id为1
149          } catch (err) {
150            let error = err as BusinessError;
151            console.error(`getErr: ${error.code} ${error.message}`);
152            // 如果 code:undefined message:"Cannot read property closeProxyChannel of undefined"， 则这个 API 在当前镜像不支持
153          }
154        })
155    }
156    .height('100%')
157    .width('100%')
158  }
159}
160```
161
162## proxyChannelManager.sendData
163
164sendData(channelId:number, data:ArrayBuffer):Promise<void>
165
166向对端发送数据，使用Promise异步回调。
167
168**需要权限**：ohos.permission.ACCESS_BLUETOOTH
169
170**系统能力**：SystemCapability.DistributedSched.AppCollaboration
171
172**参数：**
173
174| 参数名       | 类型                                       | 必填   | 说明       |
175| --------- | ---------------------------------------- | ---- | -------- |
176| channelId | number | 是    | 打开代理通道时获取的channelId。 |
177| data      | ArrayBuffer | 是 | 向对端发送的字节消息，长度最大为4096个字节。 |
178
179**返回值：**
180
181| 类型                  | 说明               |
182| ------------------- | ---------------- |
183|  Promise<void> | 无返回值的Promise的对象。 |
184
185**错误码：**
186
187以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。
188
189| 错误码ID | 错误信息 |
190| ------- | -------------------------------- |
191| 201      | Permission denied.|
192| 32390004 | ChannelId is invalid or unavailable.|
193| 32390006 | Parameter error.|
194| 32390100 | Internal error.|
195| 32390101 | Call is restricted.|
196| 32390103 | Data too long.|
197| 32390104 | Send failed.|
198
199**示例：**
200
201```ts
202import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager';
203import { BusinessError } from '@ohos.base';
204@Entry
205@Component
206struct Index {
207  build() {
208    RelativeContainer() {
209      Button("测试")
210        .onClick(() => {
211          const data = new ArrayBuffer(10); // 创建一个长度为 10 的 ArrayBuffer
212          try {
213            proxyChannelManager.sendData(1, data)  // 假设通道id为1
214              .then(() => {
215              })
216              .catch((error: BusinessError) => {
217                console.error(`getErr: ${error.code} ${error.message}`);
218              });
219          }catch (err) {
220            let error = err as BusinessError;
221            console.error(`getErr: ${error.code} ${error.message}`);
222          }
223        })
224    }
225    .height('100%')
226    .width('100%')
227  }
228}
229```
230
231## proxyChannelManager.on('receiveData')
232
233on(type: 'receiveData', channelId: number, callback: Callback<DataInfo>): void
234
235订阅数据接收事件，使用异步回调。
236
237**需要权限**：ohos.permission.ACCESS_BLUETOOTH
238
239**系统能力**：SystemCapability.DistributedSched.AppCollaboration
240
241**参数：**
242
243| 参数名       | 类型                                       | 必填   | 说明       |
244| --------- | ---------------------------------------- | ---- | -------- |
245| type      | string | 是 | 设置订阅类型，固定取值为'receiveData'。|
246| channelId | number | 是    | 打开代理通道时获取的channelId。 |
247| callback  | Callback<[DataInfo](#datainfo)> | 是 | 回调函数，返回接收到的数据。多次注册回调函数，最后一次注册的回调函数生效。 |
248
249**错误码：**
250
251以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。
252
253| 错误码ID | 错误信息 |
254| ------- | -------------------------------- |
255| 201      | Permission denied.|
256| 32390004 | ChannelId is invalid or unavailable.|
257| 32390006 | Parameter error.|
258| 32390100 | Internal error.|
259| 32390101 | Call is restricted.|
260
261**示例：**
262
263```ts
264import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager';
265import { BusinessError } from '@ohos.base';
266@Entry
267@Component
268struct Index {
269  build() {
270    RelativeContainer() {
271      Button("测试")
272        .onClick(() => {
273          const receiveDataCallback = (dataInfo: proxyChannelManager.DataInfo) => {
274          };
275          try{
276            proxyChannelManager.on('receiveData', 1, receiveDataCallback);  // 假设通道id为1
277          } catch(err) {
278            let error = err as BusinessError;
279            console.error(`register receiveData error: ${error.code} ${error.message}`);
280          }
281        })
282    }
283    .height('100%')
284    .width('100%')
285  }
286}
287```
288
289## proxyChannelManager.off('receiveData')
290
291off(type: 'receiveData', channelId: number, callback?: Callback<DataInfo>): void
292
293取消订阅数据接收事件，停止接收数据。
294
295**需要权限**：ohos.permission.ACCESS_BLUETOOTH
296
297**系统能力**：SystemCapability.DistributedSched.AppCollaboration
298
299**参数：**
300
301| 参数名       | 类型                                       | 必填   | 说明       |
302| --------- | ---------------------------------------- | ---- | -------- |
303| type      | string | 是 | 设置订阅类型，固定取值为'receiveData'。|
304| channelId | number | 是    | 打开代理通道时获取的channelId。 |
305| callback  | Callback<[DataInfo](#datainfo)> | 否 | 注册的回调函数。如果为空、undefined、null，则取消订阅所有的数据接收事件。如果不为空，传入最后一次注册的回调函数。 |
306
307**错误码：**
308
309以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。
310
311| 错误码ID | 错误信息 |
312| ------- | -------------------------------- |
313| 201      | Permission denied.|
314| 32390004 | ChannelId is invalid or unavailable.|
315| 32390006 | Parameter error.|
316| 32390100 | Internal error.|
317| 32390101 | Call is restricted.|
318
319**示例：**
320
321```ts
322import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager';
323import { BusinessError } from '@ohos.base';
324@Entry
325@Component
326struct Index {
327  build() {
328    RelativeContainer() {
329      Button("测试")
330        .onClick(() => {
331          try{
332            proxyChannelManager.off('receiveData', 1);  // 假设通道id为1
333          } catch(err) {
334            let error = err as BusinessError;
335            console.error(`getErr: ${error.code} ${error.message}`);
336          }
337        })
338    }
339    .height('100%')
340    .width('100%')
341  }
342}
343```
344
345## proxyChannelManager.on('channelStateChange')
346
347on(type: 'channelStateChange', channelId: number, callback: Callback<ChannelStateInfo>): void
348
349订阅通道状态事件，使用callback进行异步回调。
350
351**需要权限**：ohos.permission.ACCESS_BLUETOOTH
352
353**系统能力**：SystemCapability.DistributedSched.AppCollaboration
354
355**参数：**
356
357| 参数名       | 类型                                       | 必填   | 说明       |
358| --------- | ---------------------------------------- | ---- | -------- |
359| type      | string | 是 | 设置订阅类型，固定取值为'channelStateChange'。|
360| channelId | number | 是    | 打开代理通道时获取的channelId。 |
361| callback  | Callback<[ChannelStateInfo](#channelstateinfo)> | 是 | 回调函数，返回接收到的通道状态。多次注册callback，最后一次注册的callback生效 |
362
363**错误码：**
364
365以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。
366
367| 错误码ID | 错误信息 |
368| ------- | -------------------------------- |
369| 201      | Permission denied.|
370| 32390004 | ChannelId is invalid or unavailable.|
371| 32390006 | Parameter error.|
372| 32390100 | Internal error.|
373| 32390101 | Call is restricted.|
374
375**示例：**
376
377```ts
378import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager';
379import { BusinessError } from '@ohos.base';
380@Entry
381@Component
382struct Index {
383  build() {
384    RelativeContainer() {
385      Button("测试")
386        .onClick(() => {
387          const receiveStatusCallback = (channelStateInfo: proxyChannelManager.ChannelStateInfo) => {
388          };
389          try{
390            proxyChannelManager.on('channelStateChange', 1, receiveStatusCallback);  // 假设打开的通道id为1
391          } catch(err) {
392            let error = err as BusinessError;
393            console.error(`getErr: ${error.code} ${error.message}`);
394          }
395        })
396    }
397    .height('100%')
398    .width('100%')
399  }
400}
401```
402
403## proxyChannelManager.off('channelStateChange')
404
405off(type: 'channelStateChange', channelId: number, callback?: Callback<ChannelStateInfo>): void
406
407取消订阅通道状态事件。
408
409**需要权限**：ohos.permission.ACCESS_BLUETOOTH
410
411**系统能力**：SystemCapability.DistributedSched.AppCollaboration
412
413**参数：**
414
415| 参数名       | 类型                                       | 必填   | 说明       |
416| --------- | ---------------------------------------- | ---- | -------- |
417| type      | string | 是 | 设置订阅类型为'channelStateChange'。|
418| channelId | number | 是    | 打开代理通道时获取的channelId。 |
419| callback  | Callback<[ChannelStateInfo](#channelstateinfo)> | 否 | 注册的回调函数。如果为空、undefined、null，则取消订阅所有的数据接收事件。如果不为空，传入最后一次注册的回调函数。 |
420
421**错误码：**
422
423以下错误码的详细介绍请参考[代理通道管理错误码](errorcode_proxyChannelManager.md)和[通用错误码](../errorcode-universal.md)。
424
425| 错误码ID | 错误信息 |
426| ------- | -------------------------------- |
427| 201      | Permission denied.|
428| 32390004 | ChannelId is invalid or unavailable.|
429| 32390006 | Parameter error.|
430| 32390100 | Internal error.|
431| 32390101 | Call is restricted.|
432
433**示例：**
434
435```ts
436import proxyChannelManager from '@ohos.distributedsched.proxyChannelManager';
437import { BusinessError } from '@ohos.base';
438@Entry
439@Component
440struct Index {
441  build() {
442    RelativeContainer() {
443      Button("测试")
444        .onClick(() => {
445          try{
446            proxyChannelManager.off('channelStateChange', 1);  // 假设打开的通道id为1
447          } catch(err) {
448            let error = err as BusinessError;
449            console.error(`getErr: ${error.code} ${error.message}`);
450          }
451        })
452    }
453    .height('100%')
454    .width('100%')
455  }
456}
457```
458
459## DataInfo
460
461存放接收的数据信息，包括通道Id和数据。
462
463**系统能力**：SystemCapability.DistributedSched.AppCollaboration
464
465| 名称       | 类型                                       | 只读   | 可选   | 说明       |
466| --------- | ---------------------------------------- | ---- | ---- | -------- |
467| channelId | number | 否 | 否    | 代理通道的channelId。 |
468| data | ArrayBuffer | 否 | 否 | 接收到的字节数据。 |
469
470## ChannelInfo
471
472打开代理通道函数的入参，包括对端设备的MAC地址和监听服务的UUID。
473
474| 名称       | 类型                                       | 只读   | 可选   | 说明       |
475| --------- | ---------------------------------------- | ---- | ---- | -------- |
476| linkType | [LinkType](#linktype) | 否 | 否    | 代理通道的链路类型。 |
477| peerDevAddr | string | 否 | 否 | 对端设备的MAC地址。 |
478| peerUuid | string | 否 | 否 | 对端监听的服务的UUID。 |
479
480## ChannelStateInfo
481
482当代理通道状态变化时，用于表示代理通道的连接状态。
483
484**系统能力**：SystemCapability.DistributedSched.AppCollaboration
485
486| 名称       | 类型                                       | 只读   | 可选   | 说明       |
487| --------- | ---------------------------------------- | ---- | ---- | -------- |
488| channelId | number | 否 | 否    | 代理通道的channelId。 |
489| state | [ChannelState](#channelstate) | 否 | 否 | 通道的连接状态。 |
490
491## ChannelState
492
493通道状态发生变化时，代理通道上报的通道连接状态。
494
495**系统能力**：SystemCapability.DistributedSched.AppCollaboration
496
497| 名称       | 值                                       | 说明       |
498| --------- | ---------------------------------------- |  -------- |
499| CHANNEL_WAIT_RESUME | 0 | 连接已断开，通道不可用。 |
500| CHANNEL_RESUME | 1 | 连接已恢复，通道可用。 |
501| CHANNEL_EXCEPTION_SOFTWARE_FAILED | 2 | 其他软件错误导致通道不可用。 |
502| CHANNEL_BR_NO_PAIRED | 3 | 蓝牙配对关系被删除，通道不可用。 |
503
504## LinkType
505
506链路类型。
507
508**系统能力**：SystemCapability.DistributedSched.AppCollaboration
509
510| 名称       | 值                                       | 说明       |
511| --------- | ---------------------------------------- |  -------- |
512| LINK_BR | 0 | 蓝牙。 |