1# @ohos.abilityConnectionManager (Cross-Device Connection Management) (System API) 2 3The **abilityConnectionManager** module provides APIs for cross-device connection management. After successful networking between devices (login with the same account and enabling of Bluetooth on the devices), a system application and third-party application can start a [UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md) of the same application across the devices. After a connection is successfully established, data can be transmitted across the devices, including strings, [ArrayBuffer](../../arkts-utils/arraybuffer-object.md) byte streams, images, and transport streams. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 18. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> The APIs provided by this module are system APIs. 10 11## Modules to Import 12 13```js 14import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 15``` 16 17## abilityConnectionManager.on 18 19on(type: 'collaborateEvent' | 'receiveImage', sessionId: number, callback: Callback<EventCallbackInfo>): void 20 21Registers a callback listener for the **collaborateEvent** and **receiveImage** events. 22 23**System capability**: SystemCapability.DistributedSched.AppCollaboration 24 25**System API**: This is a system API. 26 27**Parameters** 28 29| Name | Type | Mandatory | Description | 30| --------- | ------------------------------------- | ---- | ----- | 31| type | string | Yes | Event type, which can be:<br>\- `collaborateEvent`: event triggered when `collaborateEvent()` is called.<br>\- `receiveImage`: event triggered when `sendImage()` is called. | 32| sessionId | number | Yes | ID of the collaborative session. | 33| callback | Callback<[EventCallbackInfo](js-apis-distributed-abilityConnectionManager.md#eventcallbackinfo)> | Yes | Registered callback function. | 34 35**Error codes** 36 37For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 38 39| ID| Error Message| 40| ------- | -------------------------------- | 41| 201 | Permission verification failed. The application does not have the permission required to call the API.| 42| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 43 44**Example** 45 46 ```ts 47 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 48 import { hilog } from '@kit.PerformanceAnalysisKit'; 49 50 abilityConnectionManager.on("collaborateEvent", this.sessionId,(callbackInfo) => { 51 hilog.info(0x0000, 'testTag', 'session collaborateEvent, sessionId is', callbackInfo.sessionId); 52 }); 53 54 abilityConnectionManager.on("receiveImage", this.sessionId,(callbackInfo) => { 55 hilog.info(0x0000, 'testTag', 'session receiveImage, sessionId is', callbackInfo.sessionId); 56 }); 57 58 ``` 59 60## abilityConnectionManager.off 61 62off(type: 'collaborateEvent' | 'receiveImage', sessionId: number, callback?: Callback<EventCallbackInfo>): void 63 64Unregisters the callback listener for the **collaborateEvent** and **receiveImage** events. 65 66**System capability**: SystemCapability.DistributedSched.AppCollaboration 67 68**System API**: This is a system API. 69 70**Parameters** 71 72| Name | Type | Mandatory | Description | 73| --------- | ------------------------------------- | ---- | ----- | 74| type | string | Yes | Event type, which can be:<br>\- `collaborateEvent`: event triggered when `collaborateEvent()` is called.<br>\- `receiveImage`: event triggered when `sendImage()` is called. | 75| sessionId | number | Yes | ID of the collaborative session. | 76| callback | Callback<[EventCallbackInfo](js-apis-distributed-abilityConnectionManager.md#eventcallbackinfo)> | No | Registered callback function. | 77 78**Error codes** 79 80For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 81 82| ID| Error Message| 83| ------- | -------------------------------- | 84| 201 | Permission verification failed. The application does not have the permission required to call the API.| 85| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 86 87**Example** 88 89 ```ts 90 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 91 import { hilog } from '@kit.PerformanceAnalysisKit'; 92 93 abilityConnectionManager.off("collaborateEvent", this.sessionId); 94 abilityConnectionManager.off("receiveImage", this.sessionId); 95 ``` 96 97## abilityConnectionManager.sendImage 98 99sendImage(sessionId: number, image: image.PixelMap, quality?: number): Promise<void> 100 101Sends images from one device to another after a connection is successfully established. 102 103**System capability**: SystemCapability.DistributedSched.AppCollaboration 104 105**System API**: This is a system API. 106 107**Parameters** 108 109| Name | Type | Mandatory | Description | 110| --------- | --------------------------------------- | ---- | ----- | 111| sessionId | number | Yes | ID of the collaborative session.| 112| image | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Image information.| 113| quality | number | No | Image compression quality. The value range is [0, 100]. The default value is **30**.| 114 115**Return value** 116 117| Type | Description | 118| ------------------- | ---------------- | 119| Promise<void> | Promise that returns no value.| 120 121**Error codes** 122 123For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 124 125| ID| Error Message| 126| ------- | -------------------------------- | 127| 201 | Permission verification failed. The application does not have the permission required to call the API.| 128| 202 | Permission verification failed. A non-system application calls a system API.| 129| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 130 131**Example** 132 133 ```ts 134 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 135 import { hilog } from '@kit.PerformanceAnalysisKit'; 136 import CameraService from '../model/CameraService'; 137 import { photoAccessHelper } from '@kit.MediaLibraryKit'; 138 import { image } from '@kit.ImageKit'; 139 import { fileIo as fs } from '@kit.CoreFileKit'; 140 141 try { 142 let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions(); 143 photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE; 144 photoSelectOptions.maxSelectNumber = 5; 145 let photoPicker = new photoAccessHelper.PhotoViewPicker(); 146 photoPicker.select(photoSelectOptions).then((photoSelectResult) => { 147 if (!photoSelectResult) { 148 hilog.error(0x0000, 'testTag', 'photoSelectResult = null'); 149 return; 150 } 151 152 let file = fs.openSync(photoSelectResult.photoUris[0], fs.OpenMode.READ_ONLY); 153 hilog.info(0x0000, 'testTag', 'file.fd:' + file.fd); 154 155 let imageSourceApi: image.ImageSource = image.createImageSource(file.fd); 156 if (imageSourceApi) { 157 imageSourceApi.createPixelMap().then((pixelMap) => { 158 abilityConnectionManager.sendImage(this.sessionId, pixelMap) 159 }); 160 } else { 161 hilog.info(0x0000, 'testTag', 'imageSourceApi is undefined'); 162 } 163 }) 164 } catch (error) { 165 hilog.error(0x0000, 'testTag', 'photoPicker failed with error: ' + JSON.stringify(error)); 166 } 167 ``` 168 169## abilityConnectionManager.createStream 170 171createStream(sessionId: number, param: StreamParam): Promise<number> 172 173Creates transport streams to send images and videos from one device to another after a connection is successfully established. 174 175**System capability**: SystemCapability.DistributedSched.AppCollaboration 176 177**System API**: This is a system API. 178 179**Parameters** 180 181| Name | Type | Mandatory | Description | 182| --------- | --------------------------------------- | ---- | ----- | 183| sessionId | number | Yes | ID of the collaborative session.| 184| param | [StreamParam](#streamparam) | Yes | Transport stream information.| 185 186**Return value** 187 188| Type | Description | 189| ------------------- | ---------------- | 190| Promise<number> | Promise used to return the result. The number in the promise indicates the creation result.| 191 192**Error codes** 193 194For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](./errorcode-device-manager.md). 195 196| ID| Error Message| 197| ------- | -------------------------------- | 198| 201 | Permission verification failed. The application does not have the permission required to call the API.| 199| 202 | Permission verification failed. A non-system application calls a system API.| 200| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 201| 32300001 | Only one stream can be created for the current session.| 202| 32300003 | Bitrate not supported.| 203| 32300004 | Color space not supported.| 204 205**Example** 206 207 ```ts 208 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 209 import { hilog } from '@kit.PerformanceAnalysisKit'; 210 211 hilog.info(0x0000, 'testTag', 'startStream'); 212 abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => { 213 let surfaceParam: abilityConnectionManager.SurfaceParam = { 214 width: 640, 215 height: 480, 216 format: 1 217 } 218 let surfaceId = abilityConnectionManager.getSurfaceId(streamId, surfaceParam); 219 hilog.info(0x0000, 'testTag', 'surfaceId is'+surfaceId); 220 AppStorage.setOrCreate<string>('surfaceId', surfaceId); 221 await CameraService.initCamera(surfaceId, 0); 222 abilityConnectionManager.startStream(streamId); 223 }) 224 ``` 225 226## abilityConnectionManager.setSurfaceId 227 228setSurfaceId(sessionId: number, surfaceId: string, param: SurfaceParam): void 229 230Sets the binding relationship between transport streams and surfaces. 231 232**System capability**: SystemCapability.DistributedSched.AppCollaboration 233 234**System API**: This is a system API. 235 236**Parameters** 237 238| Name | Type | Mandatory | Description | 239| --------- | --------------------------------------- | ---- | ----- | 240| sessionId | number | Yes | ID of the collaborative session.| 241| surfaceId | string | Yes | Unique ID of the surface.| 242| param | [SurfaceParam](#surfaceparam) | Yes | Surface configuration parameters.| 243 244**Error codes** 245 246For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 247 248| ID| Error Message| 249| ------- | -------------------------------- | 250| 202 | Permission verification failed. A non-system application calls a system API.| 251| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 252 253**Example** 254 255 ```ts 256 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 257 import { hilog } from '@kit.PerformanceAnalysisKit'; 258 259 hilog.info(0x0000, 'testTag', 'setSurfaceId'); 260 abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => { 261 let surfaceParam: abilityConnectionManager.SurfaceParam = { 262 width: 640, 263 height: 480, 264 format: 1 265 } 266 let surfaceId = abilityConnectionManager.getSurfaceId(streamId, surfaceParam); 267 abilityConnectionManager.setSurfaceId(streamId, surfaceId, surfaceParam); 268 }) 269 ``` 270 271## abilityConnectionManager.getSurfaceId 272 273getSurfaceId(sessionId: number, param: SurfaceParam): string 274 275Obtains the unique ID of the surface bound to the specified transport streams. 276 277**System capability**: SystemCapability.DistributedSched.AppCollaboration 278 279**System API**: This is a system API. 280 281**Parameters** 282 283| Name | Type | Mandatory | Description | 284| --------- | --------------------------------------- | ---- | ----- | 285| sessionId | number | Yes | ID of the collaborative session.| 286| param | [SurfaceParam](#surfaceparam) | Yes | Surface configuration parameters.| 287 288**Return value** 289 290| Type | Description | 291| ------------------- | ---------------- | 292| string | Unique ID of the surface.| 293 294**Error codes** 295 296For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 297 298| ID| Error Message| 299| ------- | -------------------------------- | 300| 202 | Permission verification failed. A non-system application calls a system API.| 301| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 302 303**Example** 304 305 ```ts 306 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 307 import { hilog } from '@kit.PerformanceAnalysisKit'; 308 309 hilog.info(0x0000, 'testTag', 'getSurfaceId'); 310 abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => { 311 let surfaceParam: abilityConnectionManager.SurfaceParam = { 312 width: 640, 313 height: 480, 314 format: 1 315 } 316 let surfaceId = abilityConnectionManager.getSurfaceId(streamId, surfaceParam); 317 }) 318 ``` 319 320## abilityConnectionManager.updateSurfaceParam 321 322updateSurfaceParam(sessionId: number, param: SurfaceParam): void 323 324Updates the configuration of the surface bound to the specified transport streams. 325 326**System capability**: SystemCapability.DistributedSched.AppCollaboration 327 328**System API**: This is a system API. 329 330**Parameters** 331 332| Name | Type | Mandatory | Description | 333| --------- | --------------------------------------- | ---- | ----- | 334| sessionId | number | Yes | ID of the collaborative session.| 335| param | [SurfaceParam](#surfaceparam) | Yes | Surface configuration parameters.| 336 337**Error codes** 338 339For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 340 341| ID| Error Message| 342| ------- | -------------------------------- | 343| 202 | Permission verification failed. A non-system application calls a system API.| 344| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 345 346**Example** 347 348 ```ts 349 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 350 import { hilog } from '@kit.PerformanceAnalysisKit'; 351 352 hilog.info(0x0000, 'testTag', 'updateSurfaceParam'); 353 abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => { 354 let surfaceParam: abilityConnectionManager.SurfaceParam = { 355 width: 640, 356 height: 480, 357 format: 1 358 } 359 abilityConnectionManager.updateSurfaceParam(streamId, surfaceParam); 360 }) 361 ``` 362 363## abilityConnectionManager.destroyStream 364 365destroyStream(sessionId: number): void 366 367Destroys the transport streams after the sending of images and videos is complete. 368 369**System capability**: SystemCapability.DistributedSched.AppCollaboration 370 371**System API**: This is a system API. 372 373**Parameters** 374 375| Name | Type | Mandatory | Description | 376| --------- | --------------------------------------- | ---- | ----- | 377| sessionId | number | Yes | ID of the collaborative session.| 378 379**Error codes** 380 381For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 382 383| ID| Error Message| 384| ------- | -------------------------------- | 385| 201 | Permission verification failed. The application does not have the permission required to call the API.| 386| 202 | Permission verification failed. A non-system application calls a system API.| 387| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 388 389**Example** 390 391 ```ts 392 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 393 import { hilog } from '@kit.PerformanceAnalysisKit'; 394 395 hilog.info(0x0000, 'testTag', 'destroyStream called'); 396 abilityConnectionManager.destroyStream(sessionId) 397 ``` 398 399## abilityConnectionManager.startStream 400 401startStream(sessionId: number): void 402 403Starts transmission of the specified transport streams. 404 405**System capability**: SystemCapability.DistributedSched.AppCollaboration 406 407**System API**: This is a system API. 408 409**Parameters** 410 411| Name | Type | Mandatory | Description | 412| --------- | --------------------------------------- | ---- | ----- | 413| sessionId | number | Yes | ID of the collaborative session.| 414 415**Error codes** 416 417For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](./errorcode-device-manager.md). 418 419| ID| Error Message| 420| ------- | -------------------------------- | 421| 202 | Permission verification failed. A non-system application calls a system API.| 422| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 423| 32300002 | The stream at the receive end is not started. | 424 425**Example** 426 427 ```ts 428 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 429 import { hilog } from '@kit.PerformanceAnalysisKit'; 430 431 hilog.info(0x0000, 'testTag', 'startStream called'); 432 abilityConnectionManager.startStream(sessionId) 433 ``` 434 435## abilityConnectionManager.stopStream 436 437stopStream(sessionId: number): void 438 439Stops transmission of the specified transport streams. 440 441**System capability**: SystemCapability.DistributedSched.AppCollaboration 442 443**System API**: This is a system API. 444 445**Parameters** 446 447| Name | Type | Mandatory | Description | 448| --------- | --------------------------------------- | ---- | ----- | 449| sessionId | number | Yes | ID of the collaborative session.| 450 451**Error codes** 452 453For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 454 455| ID| Error Message| 456| ------- | -------------------------------- | 457| 202 | Permission verification failed. A non-system application calls a system API.| 458| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 459 460**Example** 461 462 ```ts 463 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 464 import { hilog } from '@kit.PerformanceAnalysisKit'; 465 466 hilog.info(0x0000, 'testTag', 'stopStream called'); 467 abilityConnectionManager.stopStream(sessionId) 468 ``` 469 470## CollaborateEventInfo 471 472Defines the collaboration event information. 473 474**System capability**: SystemCapability.DistributedSched.AppCollaboration 475 476| Name | Type | Readable | Writable | Mandatory | Description | 477| -------- | ------ | ---- | ---- | ---- | ------- | 478| eventType | [CollaborateEventType](#collaborateeventtype) | Yes | No | Yes | Collaboration event type.| 479| eventMsg | string | Yes | No | No | Collaboration event message.| 480 481## StreamParam 482 483Defines stream transmission configuration parameters. 484 485**System capability**: SystemCapability.DistributedSched.AppCollaboration 486 487| Name | Type | Readable | Writable | Mandatory | Description | 488| -------- | ------ | ---- | ---- | ---- | ----------- | 489| name | string | Yes | No | Yes | Name of the transport stream. The name must be the same on the TX end and RX end.| 490| role | [StreamRole](#streamrole) | Yes | No | Yes | Stream transmission mode (TX stream or RX stream).| 491| bitrate | number | Yes | No | No | Video bit rate (valid only at the TX end).| 492| colorSpaceConversionTarget | [colorSpaceManager.ColorSpace](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspace) | Yes | No | No | Target color space for conversion.| 493 494## SurfaceParam 495 496Defines surface configuration parameters. 497 498**System capability**: SystemCapability.DistributedSched.AppCollaboration 499 500| Name | Type | Readable | Writable | Mandatory | Description | 501| -------- | ------ | ---- | ---- | ---- | ------- | 502| width | number | Yes | No | Yes | Encoding width. Set this parameter prior to stream transmission. Once stream transmission starts, the setting cannot be updated until the stream transmission ends. If you need to update the setting, stop stream transmission first.| 503| height | number | Yes | No | Yes | Encoding length. Set this parameter prior to stream transmission. Once stream transmission starts, the setting cannot be updated until the stream transmission ends. If you need to update the setting, stop stream transmission first.| 504| format | [VideoPixelFormat](#videopixelformat) | Yes | No | No | Video pixel format (valid only at the TX end).| 505| rotation | number | Yes | No | No | Video rotation angle.| 506| flip | [FlipOptions](#flipoptions) | Yes | No | No | Video flip option.| 507 508## CollaborateEventType 509 510Enumerates collaboration event types. 511 512**System capability**: SystemCapability.DistributedSched.AppCollaboration 513 514| Value| Description| 515| -------- | -------- | 516| SEND_FAILURE | Task sending failure.| 517| COLOR_SPACE_CONVERSION_FAILURE | Color space conversion failure.| 518 519## FlipOptions 520 521Enumerates video flip options. 522 523**System capability**: SystemCapability.DistributedSched.AppCollaboration 524 525| Value| Description| 526| -------- | -------- | 527| HORIZONTAL | Horizontal flip.| 528| VERTICAL | Vertical flip.| 529 530## StreamRole 531 532Enumerates stream transmission modes. 533 534**System capability**: SystemCapability.DistributedSched.AppCollaboration 535 536| Value| Description| 537| -------- | -------- | 538| SOURCE | TX stream.| 539| SINK | RX stream.| 540 541## VideoPixelFormat 542 543Enumerates video pixel formats. 544 545**System capability**: SystemCapability.DistributedSched.AppCollaboration 546 547| Value| Description| 548| -------- | -------- | 549| UNKNOWN | Unknown pixel format.| 550| NV12 | NV12, YUV420 semi-planar format.| 551| NV21 | NV21, YUV420 semi-planar format.| 552