1# @ohos.abilityConnectionManager (应用多端协同管理)(系统接口) 2 3abilityConnectionManager模块提供了应用协同接口管理能力。设备组网成功（需登录同账号、双端打开蓝牙）后，系统应用和三方应用可以跨设备拉起同应用的一个[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)，拉起并连接成功后可实现跨设备数据传输，包括字符串、[ArrayBuffer](../../arkts-utils/arraybuffer-object.md)字节流、图片、传输流。 4 5> **说明：** 6> 7> 本模块首批接口从API version 18开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 本模块为系统接口。 10 11## 导入模块 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 21注册collaborateEvent、receiveImage事件的回调监听。 22 23**系统能力**：SystemCapability.DistributedSched.AppCollaboration 24 25**系统API**：此接口为系统接口。 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| --------- | ------------------------------------- | ---- | ----- | 31| type | string | 是 | 事件回调类型，支持的事件包括：<br/>\- `'collaborateEvent'`：完成`collaborateEvent()`调用，触发该事件。<br/>\- `'receiveImage'`：完成`sendImage()`调用，触发该事件。 | 32| sessionId | number | 是 | 创建的协同会话ID。 | 33| callback | Callback<[EventCallbackInfo](js-apis-distributed-abilityConnectionManager.md#eventcallbackinfo)> | 是 | 注册的回调函数。 | 34 35**错误码：** 36 37以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 38 39| 错误码ID | 错误信息 | 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**示例：** 45 46 ```ts 47 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 48 import { hilog } from '@kit.PerformanceAnalysisKit'; 49 50 let sessionId = 100; 51 abilityConnectionManager.on("collaborateEvent", sessionId,(callbackInfo) => { 52 hilog.info(0x0000, 'testTag', 'session collaborateEvent, sessionId is', callbackInfo.sessionId); 53 }); 54 55 abilityConnectionManager.on("receiveImage", sessionId,(callbackInfo) => { 56 hilog.info(0x0000, 'testTag', 'session receiveImage, sessionId is', callbackInfo.sessionId); 57 }); 58 59 ``` 60 61## abilityConnectionManager.off 62 63off(type: 'collaborateEvent' | 'receiveImage', sessionId: number, callback?: Callback<EventCallbackInfo>): void 64 65取消collaborateEvent、receiveImage事件的回调监听。 66 67**系统能力**：SystemCapability.DistributedSched.AppCollaboration 68 69**系统API**：此接口为系统接口。 70 71**参数：** 72 73| 参数名 | 类型 | 必填 | 说明 | 74| --------- | ------------------------------------- | ---- | ----- | 75| type | string | 是 | 事件回调类型，支持的事件包括：<br/>\- `'collaborateEvent'`：完成`collaborateEvent()`调用，触发该事件。<br/>\- `'receiveImage'`：完成`sendImage()`调用，触发该事件。 | 76| sessionId | number | 是 | 创建的协同会话ID。 | 77| callback | Callback<[EventCallbackInfo](js-apis-distributed-abilityConnectionManager.md#eventcallbackinfo)> | 否 | 注册的回调函数。 | 78 79**错误码：** 80 81以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 82 83| 错误码ID | 错误信息 | 84| ------- | -------------------------------- | 85| 201 | Permission verification failed. The application does not have the permission required to call the API.| 86| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 87 88**示例：** 89 90 ```ts 91 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 92 import { hilog } from '@kit.PerformanceAnalysisKit'; 93 94 let sessionId = 100; 95 abilityConnectionManager.off("collaborateEvent", sessionId); 96 abilityConnectionManager.off("receiveImage", sessionId); 97 ``` 98 99## abilityConnectionManager.sendImage 100 101sendImage(sessionId: number, image: image.PixelMap, quality?: number): Promise<void> 102 103应用连接成功并创建传输流后，设备A或设备B可向对端设备发送图片。 104 105**系统能力**：SystemCapability.DistributedSched.AppCollaboration 106 107**系统API**：此接口为系统接口。 108 109**参数：** 110 111| 参数名 | 类型 | 必填 | 说明 | 112| --------- | --------------------------------------- | ---- | ----- | 113| sessionId | number | 是 | 协同会话ID。 | 114| image | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | 是 | 图片信息。 | 115| quality | number | 否 | 图像压缩质量（范围0到100，默认30）。 | 116 117**返回值：** 118 119| 类型 | 说明 | 120| ------------------- | ---------------- | 121| Promise<void> | 无返回结果的promise对象。 | 122 123**错误码：** 124 125以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 126 127| 错误码ID | 错误信息 | 128| ------- | -------------------------------- | 129| 201 | Permission verification failed. The application does not have the permission required to call the API.| 130| 202 | Permission verification failed. A non-system application calls a system API.| 131| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 132 133**示例：** 134 135 ```ts 136 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 137 import { hilog } from '@kit.PerformanceAnalysisKit'; 138 import CameraService from '../model/CameraService'; 139 import { photoAccessHelper } from '@kit.MediaLibraryKit'; 140 import { image } from '@kit.ImageKit'; 141 import { fileIo as fs } from '@kit.CoreFileKit'; 142 143 try { 144 let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions(); 145 photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE; 146 photoSelectOptions.maxSelectNumber = 5; 147 let photoPicker = new photoAccessHelper.PhotoViewPicker(); 148 photoPicker.select(photoSelectOptions).then((photoSelectResult) => { 149 if (!photoSelectResult) { 150 hilog.error(0x0000, 'testTag', 'photoSelectResult = null'); 151 return; 152 } 153 154 let file = fs.openSync(photoSelectResult.photoUris[0], fs.OpenMode.READ_ONLY); 155 hilog.info(0x0000, 'testTag', 'file.fd:' + file.fd); 156 157 let sessionId = 100; 158 let imageSourceApi: image.ImageSource = image.createImageSource(file.fd); 159 if (imageSourceApi) { 160 imageSourceApi.createPixelMap().then((pixelMap) => { 161 abilityConnectionManager.sendImage(sessionId, pixelMap) 162 }); 163 } else { 164 hilog.info(0x0000, 'testTag', 'imageSourceApi is undefined'); 165 } 166 }) 167 } catch (error) { 168 hilog.error(0x0000, 'testTag', 'photoPicker failed with error: ' + JSON.stringify(error)); 169 } 170 ``` 171 172## abilityConnectionManager.createStream 173 174createStream(sessionId: number, param: StreamParam): Promise<number> 175 176应用连接成功后，设备A或设备B可创建传输流，发送图片和视频流。 177 178**系统能力**：SystemCapability.DistributedSched.AppCollaboration 179 180**系统API**：此接口为系统接口。 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| --------- | --------------------------------------- | ---- | ----- | 186| sessionId | number | 是 | 协同会话ID。 | 187| param | [StreamParam](#streamparam) | 是 | 传输流的配置信息。 | 188 189**返回值：** 190 191| 类型 | 说明 | 192| ------------------- | ---------------- | 193| Promise<number> | 返回number结果的promise对象。number为创建结果。 | 194 195**错误码：** 196 197以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[分布式设备管理错误码](./errorcode-device-manager.md)。 198 199| 错误码ID | 错误信息 | 200| ------- | -------------------------------- | 201| 201 | Permission verification failed. The application does not have the permission required to call the API.| 202| 202 | Permission verification failed. A non-system application calls a system API.| 203| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 204| 32300001 | Only one stream can be created for the current session.| 205| 32300003 | Bitrate not supported.| 206| 32300004 | Color space not supported.| 207 208**示例：** 209 210 ```ts 211 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 212 import { hilog } from '@kit.PerformanceAnalysisKit'; 213 214 hilog.info(0x0000, 'testTag', 'startStream'); 215 abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => { 216 let surfaceParam: abilityConnectionManager.SurfaceParam = { 217 width: 640, 218 height: 480, 219 format: 1 220 } 221 let surfaceId = abilityConnectionManager.getSurfaceId(streamId, surfaceParam); 222 hilog.info(0x0000, 'testTag', 'surfaceId is'+surfaceId); 223 AppStorage.setOrCreate<string>('surfaceId', surfaceId); 224 await CameraService.initCamera(surfaceId, 0); 225 abilityConnectionManager.startStream(streamId); 226 }) 227 ``` 228 229## abilityConnectionManager.setSurfaceId 230 231setSurfaceId(sessionId: number, surfaceId: string, param: SurfaceParam): void 232 233设置传输流与Surface的绑定关系。 234 235**系统能力**：SystemCapability.DistributedSched.AppCollaboration 236 237**系统API**：此接口为系统接口。 238 239**参数：** 240 241| 参数名 | 类型 | 必填 | 说明 | 242| --------- | --------------------------------------- | ---- | ----- | 243| sessionId | number | 是 | 协同会话ID。 | 244| surfaceId | string | 是 | Surface的唯一标识符。 | 245| param | [SurfaceParam](#surfaceparam) | 是 | Surface的配置参数。 | 246 247**错误码：** 248 249以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 250 251| 错误码ID | 错误信息 | 252| ------- | -------------------------------- | 253| 202 | Permission verification failed. A non-system application calls a system API.| 254| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 255 256**示例：** 257 258 ```ts 259 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 260 import { hilog } from '@kit.PerformanceAnalysisKit'; 261 262 hilog.info(0x0000, 'testTag', 'setSurfaceId'); 263 abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => { 264 let surfaceParam: abilityConnectionManager.SurfaceParam = { 265 width: 640, 266 height: 480, 267 format: 1 268 } 269 let surfaceId = abilityConnectionManager.getSurfaceId(streamId, surfaceParam); 270 abilityConnectionManager.setSurfaceId(streamId, surfaceId, surfaceParam); 271 }) 272 ``` 273 274## abilityConnectionManager.getSurfaceId 275 276getSurfaceId(sessionId: number, param: SurfaceParam): string 277 278获取指定传输流绑定的Surface的唯一标识符。 279 280**系统能力**：SystemCapability.DistributedSched.AppCollaboration 281 282**系统API**：此接口为系统接口。 283 284**参数：** 285 286| 参数名 | 类型 | 必填 | 说明 | 287| --------- | --------------------------------------- | ---- | ----- | 288| sessionId | number | 是 | 协同会话ID。 | 289| param | [SurfaceParam](#surfaceparam) | 是 | Surface的配置参数。 | 290 291**返回值：** 292 293| 类型 | 说明 | 294| ------------------- | ---------------- | 295| string | Surface的唯一标识符。 | 296 297**错误码：** 298 299以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 300 301| 错误码ID | 错误信息 | 302| ------- | -------------------------------- | 303| 202 | Permission verification failed. A non-system application calls a system API.| 304| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 305 306**示例：** 307 308 ```ts 309 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 310 import { hilog } from '@kit.PerformanceAnalysisKit'; 311 312 hilog.info(0x0000, 'testTag', 'getSurfaceId'); 313 abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => { 314 let surfaceParam: abilityConnectionManager.SurfaceParam = { 315 width: 640, 316 height: 480, 317 format: 1 318 } 319 let surfaceId = abilityConnectionManager.getSurfaceId(streamId, surfaceParam); 320 }) 321 ``` 322 323## abilityConnectionManager.updateSurfaceParam 324 325updateSurfaceParam(sessionId: number, param: SurfaceParam): void 326 327更新与传输流绑定的Surface的配置信息。 328 329**系统能力**：SystemCapability.DistributedSched.AppCollaboration 330 331**系统API**：此接口为系统接口。 332 333**参数：** 334 335| 参数名 | 类型 | 必填 | 说明 | 336| --------- | --------------------------------------- | ---- | ----- | 337| sessionId | number | 是 | 协同会话ID。 | 338| param | [SurfaceParam](#surfaceparam) | 是 | Surface的配置参数。 | 339 340**错误码：** 341 342以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 343 344| 错误码ID | 错误信息 | 345| ------- | -------------------------------- | 346| 202 | Permission verification failed. A non-system application calls a system API.| 347| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 348 349**示例：** 350 351 ```ts 352 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 353 import { hilog } from '@kit.PerformanceAnalysisKit'; 354 355 hilog.info(0x0000, 'testTag', 'updateSurfaceParam'); 356 abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => { 357 let surfaceParam: abilityConnectionManager.SurfaceParam = { 358 width: 640, 359 height: 480, 360 format: 1 361 } 362 abilityConnectionManager.updateSurfaceParam(streamId, surfaceParam); 363 }) 364 ``` 365 366## abilityConnectionManager.destroyStream 367 368destroyStream(sessionId: number): void 369 370发送图片和视频流等业务结束后，创建传输流的应用应及时销毁传输流，否则会增加系统功耗。 371 372**系统能力**：SystemCapability.DistributedSched.AppCollaboration 373 374**系统API**：此接口为系统接口。 375 376**参数：** 377 378| 参数名 | 类型 | 必填 | 说明 | 379| --------- | --------------------------------------- | ---- | ----- | 380| sessionId | number | 是 | 协同会话ID。 | 381 382**错误码：** 383 384以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 385 386| 错误码ID | 错误信息 | 387| ------- | -------------------------------- | 388| 201 | Permission verification failed. The application does not have the permission required to call the API.| 389| 202 | Permission verification failed. A non-system application calls a system API.| 390| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 391 392**示例：** 393 394 ```ts 395 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 396 import { hilog } from '@kit.PerformanceAnalysisKit'; 397 398 let sessionId = 100; 399 hilog.info(0x0000, 'testTag', 'destroyStream called'); 400 abilityConnectionManager.destroyStream(sessionId) 401 ``` 402 403## abilityConnectionManager.startStream 404 405startStream(sessionId: number): void 406 407启动指定传输流。 408 409**系统能力**：SystemCapability.DistributedSched.AppCollaboration 410 411**系统API**：此接口为系统接口。 412 413**参数：** 414 415| 参数名 | 类型 | 必填 | 说明 | 416| --------- | --------------------------------------- | ---- | ----- | 417| sessionId | number | 是 | 协同会话ID。 | 418 419**错误码：** 420 421以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[分布式设备管理错误码](./errorcode-device-manager.md)。 422 423| 错误码ID | 错误信息 | 424| ------- | -------------------------------- | 425| 202 | Permission verification failed. A non-system application calls a system API.| 426| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 427| 32300002 | The stream at the receive end is not started. | 428 429**示例：** 430 431 ```ts 432 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 433 import { hilog } from '@kit.PerformanceAnalysisKit'; 434 435 let sessionId = 100; 436 hilog.info(0x0000, 'testTag', 'startStream called'); 437 abilityConnectionManager.startStream(sessionId) 438 ``` 439 440## abilityConnectionManager.stopStream 441 442stopStream(sessionId: number): void 443 444停止指定传输流。 445 446**系统能力**：SystemCapability.DistributedSched.AppCollaboration 447 448**系统API**：此接口为系统接口。 449 450**参数：** 451 452| 参数名 | 类型 | 必填 | 说明 | 453| --------- | --------------------------------------- | ---- | ----- | 454| sessionId | number | 是 | 协同会话ID。 | 455 456**错误码：** 457 458以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 459 460| 错误码ID | 错误信息 | 461| ------- | -------------------------------- | 462| 202 | Permission verification failed. A non-system application calls a system API.| 463| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 464 465**示例：** 466 467 ```ts 468 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 469 import { hilog } from '@kit.PerformanceAnalysisKit'; 470 471 let sessionId = 100; 472 hilog.info(0x0000, 'testTag', 'stopStream called'); 473 abilityConnectionManager.stopStream(sessionId) 474 ``` 475 476## CollaborateEventInfo 477 478协作事件信息。 479 480**系统能力**：SystemCapability.DistributedSched.AppCollaboration 481 482| 名称 | 类型 | 可读 | 可写 | 必填 | 说明 | 483| -------- | ------ | ---- | ---- | ---- | ------- | 484| eventType | [CollaborateEventType](#collaborateeventtype) | 是 | 否 | 是 | 表示协作事件的类型。 | 485| eventMsg | string | 是 | 否 | 否 | 表示协作事件的协作消息。 | 486 487## StreamParam 488 489流传输配置的参数。 490 491**系统能力**：SystemCapability.DistributedSched.AppCollaboration 492 493| 名称 | 类型 | 可读 | 可写 | 必填 | 说明 | 494| -------- | ------ | ---- | ---- | ---- | ----------- | 495| name | string | 是 | 否 | 是 | 流传输的名称（接收端必须与发送端一致）。 | 496| role | [StreamRole](#streamrole) | 是 | 否 | 是 | 流传输的方式（可以是接收流或发送流）。 | 497| bitrate | number | 是 | 否 | 否 | 视频比特率（仅在发送端有效）。 | 498| colorSpaceConversionTarget | [colorSpaceManager.ColorSpace](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspace) | 是 | 否 | 否 | 转换的目标色彩空间。 | 499 500## SurfaceParam 501 502Surface配置参数。 503 504**系统能力**：SystemCapability.DistributedSched.AppCollaboration 505 506| 名称 | 类型 | 可读 | 可写 | 必填 | 说明 | 507| -------- | ------ | ---- | ---- | ---- | ------- | 508| width | number | 是 | 否 | 是 | 表示编码宽度。必须在流启动前设置，流启动后到停止前均无法更新。如需更新需要将流停止后重新配置。 | 509| height | number | 是 | 否 | 是 | 表示编码长度。必须在流启动前设置，流启动后到停止前均无法更新。如需更新需要将流停止后重新配置。 | 510| format | [VideoPixelFormat](#videopixelformat) | 是 | 否 | 否 | 表示视频像素格式，此选项必须在发送端配置。 | 511| rotation | number | 是 | 否 | 否 | 表示标识视频的旋转角度。 | 512| flip | [FlipOptions](#flipoptions) | 是 | 否 | 否 | 表示视频是否反转。 | 513 514## CollaborateEventType 515 516协作事件的类型的枚举。 517 518**系统能力**：SystemCapability.DistributedSched.AppCollaboration 519 520| 枚举值 | 描述 | 521| -------- | -------- | 522| SEND_FAILURE | 表示发送任务失败。 | 523| COLOR_SPACE_CONVERSION_FAILURE | 表示色彩空间转换失败。 | 524 525## FlipOptions 526 527翻转选项的枚举。 528 529**系统能力**：SystemCapability.DistributedSched.AppCollaboration 530 531| 枚举值 | 描述 | 532| -------- | -------- | 533| HORIZONTAL | 表示水平翻转。 | 534| VERTICAL | 表示垂直翻转。 | 535 536## StreamRole 537 538流传输的方式。 539 540**系统能力**：SystemCapability.DistributedSched.AppCollaboration 541 542| 枚举值 | 描述 | 543| -------- | -------- | 544| SOURCE | 表示流是发送流。 | 545| SINK | 表示流是接收流。 | 546 547## VideoPixelFormat 548 549视频像素格式的枚举。 550 551**系统能力**：SystemCapability.DistributedSched.AppCollaboration 552 553| 枚举值 | 描述 | 554| -------- | -------- | 555| UNKNOWN | 表示未知的像素格式。 | 556| NV12 | 表示NV12，YUV420半平面格式。 | 557| NV21 | 表示NV21，YUV420半平面格式。 | 558 559## ConnectOptions 560 561应用连接时所需的连接选项。 562 563**系统能力**：SystemCapability.DistributedSched.AppCollaboration 564 565| 名称 | 类型 | 只读 | 可选 | 说明 | 566| ----------- | ------- | ---- | ---- | ----------- | 567| needSendStream | boolean | 否 | 否 | true表示需要发送流，false表示不需要发送流。 | 568| needReceiveStream | boolean | 否 | 否 | true表示需要接收流，false表示不需要接收流。 | 569 570## EventCallbackInfo 571 572回调方法的接收信息。 573 574**系统能力**：SystemCapability.DistributedSched.AppCollaboration 575 576| 名称 | 类型 | 可读 | 可写 | 说明 | 577| -------- | ------ | ---- | ---- | ----------- | 578| image | image.PixelMap | 是 | 否 | 表示接收的图片。 | 579 580## StartOptionParams 581 582启动选项参数的枚举。 583 584**系统能力**：SystemCapability.DistributedSched.AppCollaboration 585 586| 名称| 值 | 说明 | 587|-------|-------|-------| 588| START_IN_BACKGROUND | 1 |表示将对端应用启动至后台。| 589