1# @ohos.distributedsched.proxyChannelManager (Proxy Channel Management) 2 3DSoftBus provides stable and reliable underlying channels for cross-device communication. This module is developed based on DSoftBus. It supports efficient data exchange between phones and wearables, providing users with a seamless device interconnection experience. During collaboration between the phone application and watch application, if the phone application is not running in the foreground, its downlink messages are forwarded to the notification server and then sent to the watch through the proxy module. The core functions of this module include proxy channel management, data route management, application state awareness and wakeup, and link state monitoring. 4 5- Proxy channel management: Manages bidirectional data channels established between phones and wearables via the Bluetooth Basic Rate (BR) protocol. 6 7- Data route management: Accurately forwards data of wearables based on the specified service UUID. 8 9- Application state awareness and wakeup: After a proxy channel is enabled, dynamically analyzes and wakes up the corresponding application process on the phone after receiving data sent by the wearable. 10 11- Link state monitoring: Monitors the channel connection state in real time through callback. 12 13> **NOTE** 14> 15> The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version. 16 17## Modules to Import 18 19```js 20import { proxyChannelManager } from '@kit.DistributedServiceKit'; 21``` 22 23## How to Use 24 25Before calling the APIs of this module, complete the following configurations: 26 271. Apply for the **ohos.permission.ACCESS_BLUETOOTH** permission. For details about how to configure and apply for permissions, see [Declaring Permissions](../../security/AccessToken/declare-permissions.md) and [Requesting User Authorization](../../security/AccessToken/request-user-authorization.md). 28 292. For application processes that need to be started by proxy, set the **action** field to **action.ohos.pull.listener** in the **module.json5** file. 30 31## proxyChannelManager.openProxyChannel 32 33openProxyChannel(channelInfo: ChannelInfo): Promise<number> 34 35Opens a proxy channel. This API uses a promise to return the result. 36 37**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 38 39**System capability**: SystemCapability.DistributedSched.AppCollaboration 40 41**Parameters** 42 43| Name | Type | Mandatory | Description | 44| --------- | ---------------------------------------- | ---- | -------- | 45| channelInfo | [ChannelInfo](#channelinfo) | Yes | Channel information, including the MAC address and service UUID of the peer device. | 46 47**Return value** 48 49| Type | Description | 50| ------------------- | ---------------- | 51| Promise<number> | Channel ID of the proxy channel. The value range is [1, 2147483647]. The lifecycle of **channelId** is the same as that of the proxy channel. If the proxy is not closed, the returned **channelId** is the same as that passed in the API.| 52 53**Error codes** 54 55For details about the following error codes, see [Proxy Channel Management Error Codes](errorcode_proxyChannelManager.md) and [Universal Error Codes](../errorcode-universal.md). 56 57| ID| Error Message| 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**Example** 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 ('Test') 78 .onClick(() => { 79 let channelInfo: proxyChannelManager.ChannelInfo = { 80 linkType: proxyChannelManager.LinkType.LINK_BR, 81 peerDevAddr: "xx:xx:xx:xx:xx:xx", // Bluetooth MAC address of the wearable 82 peerUuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Service UUID of the peer device 83 }; 84 // The following sample code uses try/catch as an example. 85 try { 86 proxyChannelManager.openProxyChannel(channelInfo) 87 .then((channelId: number) => { 88 // Obtain the channel 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 // If code:undefined message:"Cannot read property openProxyChannel of undefined" is displayed, this API is not supported in the current image. 97 } 98 }) 99 } 100 .height('100%') 101 .width('100%') 102 } 103} 104``` 105 106## proxyChannelManager.closeProxyChannel 107 108closeProxyChannel(channelId: number): void 109 110Closes a proxy channel that has been opened. 111 112**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 113 114**System capability**: SystemCapability.DistributedSched.AppCollaboration 115 116**Parameters** 117 118| Name | Type | Mandatory | Description | 119| --------- | ---------------------------------------- | ---- | -------- | 120| channelId | number | Yes | Channel ID obtained when the proxy channel is opened.| 121 122**Error codes** 123 124For details about the following error codes, see [Proxy Channel Management Error Codes](errorcode_proxyChannelManager.md) and [Universal Error Codes](../errorcode-universal.md). 125 126| ID| Error Message| 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**Example** 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 ('Test') 145 .onClick(() => { 146 // The following sample code uses try/catch as an example. 147 try { 148 proxyChannelManager.closeProxyChannel(1); // Assume that the channel ID is 1. 149 } catch (err) { 150 let error = err as BusinessError; 151 console.error(`getErr: ${error.code} ${error.message}`); 152 // If code:undefined message:"Cannot read property closeProxyChannel of undefined" is displayed, this API is not supported in the current image. 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 166Sends data to the peer end. This API uses a promise to return the result. 167 168**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 169 170**System capability**: SystemCapability.DistributedSched.AppCollaboration 171 172**Parameters** 173 174| Name | Type | Mandatory | Description | 175| --------- | ---------------------------------------- | ---- | -------- | 176| channelId | number | Yes | Channel ID obtained when the proxy channel is opened.| 177| data | ArrayBuffer | Yes| Byte message sent to the peer end. The maximum length is 4096 bytes.| 178 179**Return value** 180 181| Type | Description | 182| ------------------- | ---------------- | 183| Promise<void> | Promise that returns no value.| 184 185**Error codes** 186 187For details about the following error codes, see [Proxy Channel Management Error Codes](errorcode_proxyChannelManager.md) and [Universal Error Codes](../errorcode-universal.md). 188 189| ID| Error Message| 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**Example** 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 ('Test') 210 .onClick(() => { 211 const data = new ArrayBuffer(10); // Create an ArrayBuffer with a length of 10. 212 try { 213 proxyChannelManager.sendData(1, data) // Assume that the channel ID is 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 235Subscribes to data receiving events. This API returns the result asynchronously through a callback. 236 237**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 238 239**System capability**: SystemCapability.DistributedSched.AppCollaboration 240 241**Parameters** 242 243| Name | Type | Mandatory | Description | 244| --------- | ---------------------------------------- | ---- | -------- | 245| type | string | Yes| Event type. The value **receiveData** indicates the data receiving event.| 246| channelId | number | Yes | Channel ID obtained when the proxy channel is opened.| 247| callback | Callback<[DataInfo](#datainfo)> | Yes| Callback used to return the received data. If the callback function is registered multiple times, only the last registered one takes effect.| 248 249**Error codes** 250 251For details about the following error codes, see [Proxy Channel Management Error Codes](errorcode_proxyChannelManager.md) and [Universal Error Codes](../errorcode-universal.md). 252 253| ID| Error Message| 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**Example** 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 ('Test') 272 .onClick(() => { 273 const receiveDataCallback = (dataInfo: proxyChannelManager.DataInfo) => { 274 }; 275 try{ 276 proxyChannelManager.on('receiveData', 1, receiveDataCallback); // Assume that the channel ID is 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 293Unsubscribes from data receiving events. 294 295**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 296 297**System capability**: SystemCapability.DistributedSched.AppCollaboration 298 299**Parameters** 300 301| Name | Type | Mandatory | Description | 302| --------- | ---------------------------------------- | ---- | -------- | 303| type | string | Yes| Event type. The value **receiveData** indicates the data receiving event.| 304| channelId | number | Yes | Channel ID obtained when the proxy channel is opened.| 305| callback | Callback<[DataInfo](#datainfo)> | No| Registered callback. If the value is empty, **undefined**, or **null**, all callbacks of data receiving events are unregistered. If the value is not empty, the last registered callback is used.| 306 307**Error codes** 308 309For details about the following error codes, see [Proxy Channel Management Error Codes](errorcode_proxyChannelManager.md) and [Universal Error Codes](../errorcode-universal.md). 310 311| ID| Error Message| 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**Example** 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 ('Test') 330 .onClick(() => { 331 try{ 332 proxyChannelManager.off('receiveData', 1); // Assume that the channel ID is 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 349Subscribes to channel state change events. This API returns the result asynchronously through a callback. 350 351**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 352 353**System capability**: SystemCapability.DistributedSched.AppCollaboration 354 355**Parameters** 356 357| Name | Type | Mandatory | Description | 358| --------- | ---------------------------------------- | ---- | -------- | 359| type | string | Yes| Event type. The value **channelStateChange** indicates the channel state change event.| 360| channelId | number | Yes | Channel ID obtained when the proxy channel is opened.| 361| callback | Callback<[ChannelStateInfo](#channelstateinfo)> | Yes| Callback used to return the received channel state. If the callback function is registered multiple times, only the last registered one takes effect.| 362 363**Error codes** 364 365For details about the following error codes, see [Proxy Channel Management Error Codes](errorcode_proxyChannelManager.md) and [Universal Error Codes](../errorcode-universal.md). 366 367| ID| Error Message| 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**Example** 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 ('Test') 386 .onClick(() => { 387 const receiveStatusCallback = (channelStateInfo: proxyChannelManager.ChannelStateInfo) => { 388 }; 389 try{ 390 proxyChannelManager.on ('channelStateChange', 1, receiveStatusCallback); // Assume that the channel ID is 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 407Unsubscribes from channel state change events. 408 409**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 410 411**System capability**: SystemCapability.DistributedSched.AppCollaboration 412 413**Parameters** 414 415| Name | Type | Mandatory | Description | 416| --------- | ---------------------------------------- | ---- | -------- | 417| type | string | Yes| Event type. The value **channelStateChange** indicates the channel state change event.| 418| channelId | number | Yes | Channel ID obtained when the proxy channel is opened.| 419| callback | Callback<[ChannelStateInfo](#channelstateinfo)> | No| Registered callback. If the value is empty, **undefined**, or **null**, all callbacks of data receiving events are unregistered. If the value is not empty, the last registered callback is used.| 420 421**Error codes** 422 423For details about the following error codes, see [Proxy Channel Management Error Codes](errorcode_proxyChannelManager.md) and [Universal Error Codes](../errorcode-universal.md). 424 425| ID| Error Message| 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**Example** 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 ('Test') 444 .onClick(() => { 445 try{ 446 proxyChannelManager.off('channelStateChange', 1); // Assume that the channel ID is 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 461Represents the received data, including the channel ID and data. 462 463**System capability**: SystemCapability.DistributedSched.AppCollaboration 464 465| Name | Type | Read-Only | Optional | Description | 466| --------- | ---------------------------------------- | ---- | ---- | -------- | 467| channelId | number | No| No | Channel ID of the proxy channel.| 468| data | ArrayBuffer | No| No| Received byte array.| 469 470## ChannelInfo 471 472Represents the proxy channel information, including the MAC address and service UUID of the peer device. 473 474| Name | Type | Read-Only | Optional | Description | 475| --------- | ---------------------------------------- | ---- | ---- | -------- | 476| linkType | [LinkType](#linktype) | No| No | Link type of the proxy channel.| 477| peerDevAddr | string | No| No| MAC address of the peer device.| 478| peerUuid | string | No| No| Service UUID of the peer device.| 479 480## ChannelStateInfo 481 482Represents the connection state information of the proxy channel. 483 484**System capability**: SystemCapability.DistributedSched.AppCollaboration 485 486| Name | Type | Read-Only | Optional | Description | 487| --------- | ---------------------------------------- | ---- | ---- | -------- | 488| channelId | number | No| No | Channel ID of the proxy channel.| 489| state | [ChannelState](#channelstate) | No| No| Connection state of the proxy channel.| 490 491## ChannelState 492 493Enumerates the connection states of the proxy channel. 494 495**System capability**: SystemCapability.DistributedSched.AppCollaboration 496 497| Name | Value | Description | 498| --------- | ---------------------------------------- | -------- | 499| CHANNEL_WAIT_RESUME | 0 | The connection is disconnected, and the channel is unavailable.| 500| CHANNEL_RESUME | 1 | The connection is restored, and the channel is available.| 501| CHANNEL_EXCEPTION_SOFTWARE_FAILED | 2 | The channel is unavailable due to other software errors.| 502| CHANNEL_BR_NO_PAIRED | 3 | The Bluetooth pairing relationship is deleted, and the channel is unavailable.| 503 504## LinkType 505 506Enumerates the link types. 507 508**System capability**: SystemCapability.DistributedSched.AppCollaboration 509 510| Name | Value | Description | 511| --------- | ---------------------------------------- | -------- | 512| LINK_BR | 0 | Bluetooth.| 513