1# @ohos.abilityConnectionManager (应用多端协同管理) 2 3abilityConnectionManager模块提供了应用协同接口管理能力。设备组网成功（需登录同账号、双端打开蓝牙）后，系统应用和三方应用可以跨设备拉起同应用的一个[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)，拉起并连接成功后可实现跨设备数据传输（文本信息）。 4 5> **说明：** 6> 7> 本模块首批接口从API version 18开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```js 12import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 13``` 14 15## abilityConnectionManager.createAbilityConnectionSession 16 17createAbilityConnectionSession(serviceName: string, context: Context, peerInfo: PeerInfo , connectOptions: ConnectOptions): number 18 19创建应用间的协同会话。 20 21**需要权限**：ohos.permission.INTERNET、ohos.permission.GET_NETWORK_INFO、ohos.permission.SET_NETWORK_INFO和ohos.permission.DISTRIBUTED_DATASYNC 22 23**系统能力**：SystemCapability.DistributedSched.AppCollaboration 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| --------- | --------------------------------------- | ---- | --------- | 29| serviceName | string | 是 | 应用设置的服务名称（两端必须一致），最大长度为256字符。 | 30| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 表示应用上下文。 | 31| peerInfo | [PeerInfo](#peerinfo) | 是 | 对端的协同信息。 | 32| connectOptions | [ConnectOptions](#connectoptions) | 是 | 应用设置的连接选项。 | 33 34**返回值：** 35 36| 类型 | 说明 | 37| ------------------- | ---------------- | 38| number | 成功创建的协同会话ID。 | 39 40**错误码：** 41 42以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 43 44| 错误码ID | 错误信息 | 45| ------- | -------------------------------- | 46| 201 | Permission denied.| 47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 48 49**示例：** 50 511. 在设备A上，应用需要主动调用createAbilityConnectionSession()接口创建协同会话并返回sessionId。 52 53 ```ts 54 import { abilityConnectionManager, distributedDeviceManager } from '@kit.DistributedServiceKit'; 55 import { common } from '@kit.AbilityKit'; 56 import { hilog } from '@kit.PerformanceAnalysisKit'; 57 58 let dmClass: distributedDeviceManager.DeviceManager; 59 60 function initDmClass(): void { 61 try { 62 dmClass = distributedDeviceManager.createDeviceManager('com.example.remotephotodemo'); 63 } catch (err) { 64 hilog.error(0x0000, 'testTag', 'createDeviceManager err: ' + JSON.stringify(err)); 65 } 66 } 67 68 function getRemoteDeviceId(): string | undefined { 69 initDmClass(); 70 if (typeof dmClass === 'object' && dmClass !== null) { 71 hilog.info(0x0000, 'testTag', 'getRemoteDeviceId begin'); 72 let list = dmClass.getAvailableDeviceListSync(); 73 if (typeof (list) === 'undefined' || typeof (list.length) === 'undefined') { 74 hilog.info(0x0000, 'testTag', 'getRemoteDeviceId err: list is null'); 75 return; 76 } 77 if (list.length === 0) { 78 hilog.info(0x0000, 'testTag', 'getRemoteDeviceId err: list is empty'); 79 return; 80 } 81 return list[0].networkId; 82 } else { 83 hilog.info(0x0000, 'testTag', 'getRemoteDeviceId err: dmClass is null'); 84 return; 85 } 86 } 87 88 const peerInfo: abilityConnectionManager.PeerInfo = { 89 deviceId: "sinkDeviceId", 90 bundleName: 'com.example.remotephotodemo', 91 moduleName: 'entry', 92 abilityName: 'EntryAbility', 93 serviceName: 'collabTest' 94 }; 95 const myRecord: Record<string, string> = { 96 "newKey1": "value1", 97 }; 98 99 const connectOptions: abilityConnectionManager.ConnectOptions = { 100 needSendData: true, 101 startOptions: abilityConnectionManager.StartOptionParams.START_IN_FOREGROUND, 102 parameters: myRecord 103 }; 104 let context = this.getUIContext().getHostContext(); 105 try { 106 let sessionId = abilityConnectionManager.createAbilityConnectionSession("collabTest", context, peerInfo, connectOptions); 107 hilog.info(0x0000, 'testTag', 'createSession sessionId is', sessionId); 108 } catch (error) { 109 hilog.error(0x0000, 'testTag', error); 110 } 111 ``` 112 1132. 在设备B上，对于createAbilityConnectionSession接口的调用，可在应用被拉起后触发协同生命周期函数onCollaborate时，在onCollaborate内进行。 114 115 ```ts 116 import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 117 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 118 import { hilog } from '@kit.PerformanceAnalysisKit'; 119 120 export default class EntryAbility extends UIAbility { 121 onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult { 122 hilog.info(0x0000, 'testTag', '%{public}s', 'on collaborate'); 123 let param = wantParam["ohos.extra.param.key.supportCollaborateIndex"] as Record<string, Object> 124 this.onCollab(param); 125 return 0; 126 } 127 128 onCollab(collabParam: Record<string, Object>) { 129 const sessionId = this.createSessionFromWant(collabParam); 130 if (sessionId == -1) { 131 hilog.info(0x0000, 'testTag', 'Invalid session ID.'); 132 return; 133 } 134 } 135 136 createSessionFromWant(collabParam: Record<string, Object>): number { 137 let sessionId = -1; 138 const peerInfo = collabParam["PeerInfo"] as abilityConnectionManager.PeerInfo; 139 if (peerInfo == undefined) { 140 return sessionId; 141 } 142 143 const options = collabParam["ConnectOptions"] as abilityConnectionManager.ConnectOptions; 144 try { 145 sessionId = abilityConnectionManager.createAbilityConnectionSession("collabTest", this.context, peerInfo, options); 146 AppStorage.setOrCreate('sessionId', sessionId); 147 hilog.info(0x0000, 'testTag', 'createSession sessionId is' + sessionId); 148 } catch (error) { 149 hilog.error(0x0000, 'testTag', error); 150 } 151 return sessionId; 152 } 153 } 154 ``` 155 156## abilityConnectionManager.destroyAbilityConnectionSession 157 158destroyAbilityConnectionSession(sessionId: number): void 159 160销毁应用间的协同会话。 161 162**系统能力**：SystemCapability.DistributedSched.AppCollaboration 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| --------- | ---------------------------------------- | ---- | -------- | 168| sessionId | number | 是 | 待销毁的协同会话ID。 | 169 170**示例：** 171 172 ```ts 173 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 174 import { hilog } from '@kit.PerformanceAnalysisKit'; 175 176 hilog.info(0x0000, 'testTag', 'destroyAbilityConnectionSession called'); 177 let sessionId = 100; 178 abilityConnectionManager.destroyAbilityConnectionSession(sessionId); 179 ``` 180 181## abilityConnectionManager.getPeerInfoById 182 183getPeerInfoById(sessionId: number): PeerInfo | undefined 184 185获取指定会话中对端应用信息。 186 187**系统能力**：SystemCapability.DistributedSched.AppCollaboration 188 189**参数：** 190 191| 参数名 | 类型 | 必填 | 说明 | 192| --------- | ---------------------------------------- | ---- | -------- | 193| sessionId | number | 是 | 协同会话ID。 | 194 195**返回值：** 196 197| 类型 | 说明 | 198| ------------------- | ---------------- | 199| PeerInfo | 接收端的协作应用信息。 | 200| undefined | 未知情况。 | 201 202**错误码：** 203 204以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 205 206| 错误码ID | 错误信息 | 207| ------- | -------------------------------- | 208| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 209 210**示例：** 211 212 ```ts 213 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 214 import { hilog } from '@kit.PerformanceAnalysisKit'; 215 216 hilog.info(0x0000, 'testTag', 'getPeerInfoById called'); 217 let sessionId = 100; 218 const peerInfo = abilityConnectionManager.getPeerInfoById(sessionId); 219 ``` 220 221## abilityConnectionManager.connect 222 223connect(sessionId: number): Promise<ConnectResult> 224 225创建协同会话成功并获得会话ID后，设备A上可进行UIAbility的连接。 226 227**系统能力**：SystemCapability.DistributedSched.AppCollaboration 228 229**参数：** 230 231| 参数名 | 类型 | 必填 | 说明 | 232| --------- | --------------------------------------- | ---- | --------- | 233| sessionId | number | 是 | 已创建的协同会话ID。 | 234 235**返回值：** 236 237| 类型 | 说明 | 238| ------------------- | ---------------- | 239| Promise<ConnectResult> | 以Promise形式返回[连接结果](#connectresult)。 | 240 241**错误码：** 242 243以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 244 245| 错误码ID | 错误信息 | 246| ------- | -------------------------------- | 247| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 248 249**示例：** 250 251设备A上的应用在创建协同会话成功并获得会话ID后，调用connect()方法启动UIAbility连接，并拉起设备B应用。 252 253 ```ts 254 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 255 import { hilog } from '@kit.PerformanceAnalysisKit'; 256 257 let sessionId = 100; 258 abilityConnectionManager.connect(sessionId).then((ConnectResult) => { 259 if (!ConnectResult.isConnected) { 260 hilog.info(0x0000, 'testTag', 'connect failed'); 261 return; 262 } 263 }).catch(() => { 264 hilog.error(0x0000, 'testTag', "connect failed"); 265 }) 266 ``` 267 268## abilityConnectionManager.acceptConnect 269 270acceptConnect(sessionId: number, token: string): Promise<void> 271 272设备B上的应用，在创建协同会话成功并获得会话ID后，调用acceptConnect()方法接受连接。 273 274**系统能力**：SystemCapability.DistributedSched.AppCollaboration 275 276**参数：** 277 278| 参数名 | 类型 | 必填 | 说明 | 279| --------- | --------------------------------------- | ---- | ----- | 280| sessionId | number | 是 | 已创建的协同会话ID。 | 281| token | string | 是 | 设备A应用传入的token值。 | 282 283**返回值：** 284 285| 类型 | 说明 | 286| ------------------- | ---------------- | 287| Promise<void> |无返回结果的Promise对象。 | 288 289**错误码：** 290 291以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 292 293| 错误码ID | 错误信息 | 294| ------- | -------------------------------- | 295| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 296 297**示例：** 298 299设备B上的应用，在createAbilityConnectionSession接口调用并获取sessionId成功后，可调用acceptConnect接口来选择接受连接。 300 301 ```ts 302 import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 303 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 304 import { hilog } from '@kit.PerformanceAnalysisKit'; 305 306 export default class EntryAbility extends UIAbility { 307 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 308 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 309 } 310 311 onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult { 312 hilog.info(0x0000, 'testTag', '%{public}s', 'on collaborate'); 313 let param = wantParam["ohos.extra.param.key.supportCollaborateIndex"] as Record<string, Object> 314 this.onCollab(param); 315 return 0; 316 } 317 318 onCollab(collabParam: Record<string, Object>) { 319 const sessionId = this.createSessionFromWant(collabParam); 320 if (sessionId == -1) { 321 hilog.info(0x0000, 'testTag', 'Invalid session ID.'); 322 return; 323 } 324 const collabToken = collabParam["ohos.dms.collabToken"] as string; 325 abilityConnectionManager.acceptConnect(sessionId, collabToken).then(() => { 326 hilog.info(0x0000, 'testTag', 'acceptConnect success'); 327 }).catch(() => { 328 hilog.error("failed"); 329 }) 330 } 331 332 createSessionFromWant(collabParam: Record<string, Object>): number { 333 let sessionId = -1; 334 const peerInfo = collabParam["PeerInfo"] as abilityConnectionManager.PeerInfo; 335 if (peerInfo == undefined) { 336 return sessionId; 337 } 338 339 const options = collabParam["ConnectOptions"] as abilityConnectionManager.ConnectOptions; 340 try { 341 sessionId = abilityConnectionManager.createAbilityConnectionSession("collabTest", this.context, peerInfo, options); 342 AppStorage.setOrCreate('sessionId', sessionId); 343 hilog.info(0x0000, 'testTag', 'createSession sessionId is' + sessionId); 344 } catch (error) { 345 hilog.error(0x0000, 'testTag', error); 346 } 347 return sessionId; 348 } 349 } 350 ``` 351 352## abilityConnectionManager.disconnect 353 354disconnect(sessionId: number): void 355 356当协同业务执行完毕后，协同双端的任意一台设备，应断开UIAbility的连接，结束协同状态。 357 358**系统能力**：SystemCapability.DistributedSched.AppCollaboration 359 360**参数：** 361 362| 参数名 | 类型 | 必填 | 说明 | 363| --------- | ------------------------------------- | ---- | --------- | 364| sessionId | number | 是 | 协同会话ID | 365 366**示例：** 367 368 ```ts 369 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 370 import { hilog } from '@kit.PerformanceAnalysisKit'; 371 372 hilog.info(0x0000, 'testTag', 'disconnectRemoteAbility begin'); 373 let sessionId = 100; 374 abilityConnectionManager.disconnect(sessionId); 375 ``` 376 377## abilityConnectionManager.reject 378 379reject(token: string, reason: string): void; 380 381在跨端应用协同过程中，在拒绝对端的连接请求后，向对端发送拒绝原因。 382 383**系统能力**：SystemCapability.DistributedSched.AppCollaboration 384 385**参数：** 386 387| 参数名 | 类型 | 必填 | 说明 | 388| --------- | --------------------------------------- | ---- | ----- | 389| token | string | 是 | 用于协作服务管理的令牌。 | 390| reason | string | 是 | 连接被拒绝的原因。 | 391 392**错误码：** 393 394以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 395 396| 错误码ID | 错误信息 | 397| ------- | -------------------------------- | 398| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 399 400**示例：** 401 402 ```ts 403 import { AbilityConstant, UIAbility, Want} from '@kit.AbilityKit'; 404 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 405 import { hilog } from '@kit.PerformanceAnalysisKit'; 406 407 export default class EntryAbility extends UIAbility { 408 onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult { 409 hilog.info(0x0000, 'testTag', '%{public}s', 'on collaborate'); 410 let collabParam = wantParam["ohos.extra.param.key.supportCollaborateIndex"] as Record<string, Object>; 411 const collabToken = collabParam["ohos.dms.collabToken"] as string; 412 const reason = "test"; 413 hilog.info(0x0000, 'testTag', 'reject begin'); 414 abilityConnectionManager.reject(collabToken, reason); 415 return AbilityConstant.CollaborateResult.REJECT; 416 } 417 } 418 419 ``` 420 421## abilityConnectionManager.on('connect') 422 423on(type: 'connect', sessionId: number, callback: Callback<EventCallbackInfo>): void 424 425注册connect事件的回调监听。 426 427**系统能力**：SystemCapability.DistributedSched.AppCollaboration 428 429**参数：** 430 431| 参数名 | 类型 | 必填 | 说明 | 432| --------- | ------------------------------------- | ---- | ----- | 433| type | string | 是 | 事件回调类型，支持的事件为'connect'，完成[abilityConnectionManager.connect()](#abilityconnectionmanagerconnect)调用，触发该事件。 | 434| sessionId | number | 是 | 创建的协同会话ID。 | 435| callback | Callback<[EventCallbackInfo](#eventcallbackinfo)> | 是 | 注册的回调函数。 | 436 437**错误码：** 438 439以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 440 441| 错误码ID | 错误信息 | 442| ------- | -------------------------------- | 443| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 444 445**示例：** 446 447 ```ts 448 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 449 import { hilog } from '@kit.PerformanceAnalysisKit'; 450 451 let sessionId = 100; 452 abilityConnectionManager.on("connect", sessionId,(callbackInfo) => { 453 hilog.info(0x0000, 'testTag', 'session connect, sessionId is', callbackInfo.sessionId); 454 }); 455 456 ``` 457 458## abilityConnectionManager.off('connect') 459 460off(type: 'connect', sessionId: number, callback?: Callback<EventCallbackInfo>): void 461 462取消connect事件的回调监听。 463 464**系统能力**：SystemCapability.DistributedSched.AppCollaboration 465 466**参数：** 467 468| 参数名 | 类型 | 必填 | 说明 | 469| --------- | ------------------------------------- | ---- | ----- | 470| type | string | 是 | 事件回调类型，支持的事件为'connect'。 | 471| sessionId | number | 是 | 创建的协同会话ID。 | 472| callback | Callback<[EventCallbackInfo](#eventcallbackinfo)> | 否 | 注册的回调函数。 | 473 474**错误码：** 475 476以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 477 478| 错误码ID | 错误信息 | 479| ------- | -------------------------------- | 480| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 481 482**示例：** 483 484 ```ts 485 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 486 import { hilog } from '@kit.PerformanceAnalysisKit'; 487 488 let sessionId = 100; 489 abilityConnectionManager.off("connect", sessionId); 490 491 ``` 492 493## abilityConnectionManager.on('disconnect') 494 495on(type: 'disconnect', sessionId: number, callback: Callback<EventCallbackInfo>): void 496 497注册disconnect事件的回调监听。 498 499**系统能力**：SystemCapability.DistributedSched.AppCollaboration 500 501**参数：** 502 503| 参数名 | 类型 | 必填 | 说明 | 504| --------- | ------------------------------------- | ---- | ----- | 505| type | string | 是 | 事件回调类型，支持的事件为'disconnect'，完成[abilityConnectionManager.disconnect()](#abilityconnectionmanagerdisconnect)调用，触发该事件。 | 506| sessionId | number | 是 | 创建的协同会话ID。 | 507| callback | Callback<[EventCallbackInfo](#eventcallbackinfo)> | 是 | 注册的回调函数。 | 508 509**错误码：** 510 511以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 512 513| 错误码ID | 错误信息 | 514| ------- | -------------------------------- | 515| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 516 517**示例：** 518 519 ```ts 520 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 521 import { hilog } from '@kit.PerformanceAnalysisKit'; 522 523 let sessionId = 100; 524 abilityConnectionManager.on("disconnect", sessionId,(callbackInfo) => { 525 hilog.info(0x0000, 'testTag', 'session disconnect, sessionId is', callbackInfo.sessionId); 526 }); 527 528 ``` 529 530## abilityConnectionManager.off('disconnect') 531 532off(type: 'disconnect', sessionId: number, callback?: Callback<EventCallbackInfo>): void 533 534取消disconnect事件的回调监听。 535 536**系统能力**：SystemCapability.DistributedSched.AppCollaboration 537 538**参数：** 539 540| 参数名 | 类型 | 必填 | 说明 | 541| --------- | ------------------------------------- | ---- | ----- | 542| type | string | 是 | 事件回调类型，支持的事件为'disconnect'。 | 543| sessionId | number | 是 | 创建的协同会话ID。 | 544| callback | Callback<[EventCallbackInfo](#eventcallbackinfo)> | 否 | 注册的回调函数。 | 545 546**错误码：** 547 548以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 549 550| 错误码ID | 错误信息 | 551| ------- | -------------------------------- | 552| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 553 554**示例：** 555 556 ```ts 557 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 558 import { hilog } from '@kit.PerformanceAnalysisKit'; 559 560 let sessionId = 100; 561 abilityConnectionManager.off("disconnect", sessionId); 562 563 ``` 564 565## abilityConnectionManager.on('receiveMessage') 566 567on(type: 'receiveMessage', sessionId: number, callback: Callback<EventCallbackInfo>): void 568 569注册receiveMessage事件的回调监听。 570 571**系统能力**：SystemCapability.DistributedSched.AppCollaboration 572 573**参数：** 574 575| 参数名 | 类型 | 必填 | 说明 | 576| --------- | ------------------------------------- | ---- | ----- | 577| type | string | 是 | 事件回调类型，支持的事件为'receiveMessage'，完成[abilityConnectionManager.sendMessage()](#abilityconnectionmanagersendmessage)调用，触发该事件。 | 578| sessionId | number | 是 | 创建的协同会话ID。 | 579| callback | Callback<[EventCallbackInfo](#eventcallbackinfo)> | 是 | 注册的回调函数。 | 580 581**错误码：** 582 583以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 584 585| 错误码ID | 错误信息 | 586| ------- | -------------------------------- | 587| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 588 589**示例：** 590 591 ```ts 592 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 593 import { hilog } from '@kit.PerformanceAnalysisKit'; 594 595 let sessionId = 100; 596 abilityConnectionManager.on("receiveMessage", sessionId,(callbackInfo) => { 597 hilog.info(0x0000, 'testTag', 'receiveMessage, sessionId is', callbackInfo.sessionId); 598 }); 599 600 ``` 601 602## abilityConnectionManager.off('receiveMessage') 603 604off(type: 'receiveMessage', sessionId: number, callback?: Callback<EventCallbackInfo>): void 605 606取消receiveMessage事件的回调监听。 607 608**系统能力**：SystemCapability.DistributedSched.AppCollaboration 609 610**参数：** 611 612| 参数名 | 类型 | 必填 | 说明 | 613| --------- | ------------------------------------- | ---- | ----- | 614| type | string | 是 | 事件回调类型，支持的事件为'receiveMessage'。 | 615| sessionId | number | 是 | 创建的协同会话ID。 | 616| callback | Callback<[EventCallbackInfo](#eventcallbackinfo)> | 否 | 注册的回调函数。 | 617 618**错误码：** 619 620以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 621 622| 错误码ID | 错误信息 | 623| ------- | -------------------------------- | 624| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 625 626**示例：** 627 628 ```ts 629 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 630 import { hilog } from '@kit.PerformanceAnalysisKit'; 631 632 let sessionId = 100; 633 abilityConnectionManager.off("receiveMessage", sessionId); 634 635 ``` 636 637## abilityConnectionManager.on('receiveData') 638 639on(type: 'receiveData', sessionId: number, callback: Callback<EventCallbackInfo>): void 640 641注册receiveData事件的回调监听。 642 643**系统能力**：SystemCapability.DistributedSched.AppCollaboration 644 645**参数：** 646 647| 参数名 | 类型 | 必填 | 说明 | 648| --------- | ------------------------------------- | ---- | ----- | 649| type | string | 是 | 事件回调类型，支持的事件为'receiveData'，完成[abilityConnectionManager.sendData()](#abilityconnectionmanagersenddata)调用，触发该事件。 | 650| sessionId | number | 是 | 创建的协同会话ID。 | 651| callback | Callback<[EventCallbackInfo](#eventcallbackinfo)> | 是 | 注册的回调函数。 | 652 653**错误码：** 654 655以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 656 657| 错误码ID | 错误信息 | 658| ------- | -------------------------------- | 659| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 660 661**示例：** 662 663 ```ts 664 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 665 import { hilog } from '@kit.PerformanceAnalysisKit'; 666 667 let sessionId = 100; 668 abilityConnectionManager.on("receiveData", sessionId,(callbackInfo) => { 669 hilog.info(0x0000, 'testTag', 'receiveData, sessionId is', callbackInfo.sessionId); 670 }); 671 672 ``` 673 674## abilityConnectionManager.off('receiveData') 675 676off(type: 'receiveData', sessionId: number, callback?: Callback<EventCallbackInfo>): void 677 678取消receiveData事件的回调监听。 679 680**系统能力**：SystemCapability.DistributedSched.AppCollaboration 681 682**参数：** 683 684| 参数名 | 类型 | 必填 | 说明 | 685| --------- | ------------------------------------- | ---- | ----- | 686| type | string | 是 | 事件回调类型，支持的事件为'receiveData'，完成。 | 687| sessionId | number | 是 | 创建的协同会话ID。 | 688| callback | Callback<[EventCallbackInfo](#eventcallbackinfo)> | 否 | 注册的回调函数。 | 689 690**错误码：** 691 692以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 693 694| 错误码ID | 错误信息 | 695| ------- | -------------------------------- | 696| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 697 698**示例：** 699 700 ```ts 701 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 702 import { hilog } from '@kit.PerformanceAnalysisKit'; 703 704 let sessionId = 100; 705 abilityConnectionManager.off("receiveData", sessionId); 706 707 ``` 708 709## abilityConnectionManager.sendMessage 710 711sendMessage(sessionId: number, msg: string): Promise<void> 712 713应用连接成功后，设备A或设备B可向对端设备发送文本信息。 714 715**系统能力**：SystemCapability.DistributedSched.AppCollaboration 716 717**参数：** 718 719| 参数名 | 类型 | 必填 | 说明 | 720| --------- | --------------------------------------- | ---- | ----- | 721| sessionId | number | 是 | 协同会话ID。 | 722| msg | string | 是 | 文本信息内容（内容最大限制为1KB）。 | 723 724**返回值：** 725 726| 类型 | 说明 | 727| ------------------- | ---------------- | 728| Promise<void> | 无返回结果的promise对象。 | 729 730**错误码：** 731 732以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 733 734| 错误码ID | 错误信息 | 735| ------- | -------------------------------- | 736| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 737 738**示例：** 739 740 ```ts 741 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 742 import { hilog } from '@kit.PerformanceAnalysisKit'; 743 744 let sessionId = 100; 745 abilityConnectionManager.sendMessage(sessionId, "message send success").then(() => { 746 hilog.info(0x0000, 'testTag', "sendMessage success"); 747 }).catch(() => { 748 hilog.error(0x0000, 'testTag', "connect failed"); 749 }) 750 ``` 751 752## abilityConnectionManager.sendData 753 754sendData(sessionId: number, data: ArrayBuffer): Promise<void> 755 756应用连接成功后，设备A或设备B可向对端设备发送[ArrayBuffer](../../arkts-utils/arraybuffer-object.md)字节流。 757 758**系统能力**：SystemCapability.DistributedSched.AppCollaboration 759 760**参数：** 761 762| 参数名 | 类型 | 必填 | 说明 | 763| --------- | --------------------------------------- | ---- | ----- | 764| sessionId | number | 是 | 协同会话ID。 | 765| data | [ArrayBuffer](../../arkts-utils/arraybuffer-object.md) | 是 | 字节流信息。 | 766 767**返回值：** 768 769| 类型 | 说明 | 770| ------------------- | ---------------- | 771| Promise<void> | 无返回结果的promise对象。 | 772 773**错误码：** 774 775以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 776 777| 错误码ID | 错误信息 | 778| ------- | -------------------------------- | 779| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 780 781**示例：** 782 783 ```ts 784 import { abilityConnectionManager } from '@kit.DistributedServiceKit'; 785 import { hilog } from '@kit.PerformanceAnalysisKit'; 786 import { util } from '@kit.ArkTS'; 787 788 let textEncoder = util.TextEncoder.create("utf-8"); 789 const arrayBuffer = textEncoder.encodeInto("data send success"); 790 791 let sessionId = 100; 792 abilityConnectionManager.sendData(sessionId, arrayBuffer.buffer).then(() => { 793 hilog.info(0x0000, 'testTag', "sendMessage success"); 794 }).catch(() => { 795 hilog.info(0x0000, 'testTag', "sendMessage failed"); 796 }) 797 ``` 798 799## PeerInfo 800 801应用协同信息。 802 803**系统能力**：SystemCapability.DistributedSched.AppCollaboration 804 805| 名称 | 类型 |只读 | 可选 | 说明 | 806| ----------------- | ------ | ---- | ---- | ------------------ | 807| deviceId | string | 是 |是 | 对端设备ID。 | 808| bundleName | string | 是 |是 | 对端应用的包名。 | 809| moduleName | string | 是 |是 | 对端应用的模块名。 | 810| abilityName | string | 是 |是 | 对端应用的组件名。 | 811| serviceName | string | 是 |否 | 应用设置的服务名称。 | 812 813## ConnectOptions 814 815应用连接时所需的连接选项。 816 817**系统能力**：SystemCapability.DistributedSched.AppCollaboration 818 819| 名称 | 类型 | 只读 | 可选 | 说明 | 820| ----------- | ------- | ---- | ---- | ----------- | 821| needSendData | boolean | 否 | 否 | true代表需要传输数据，false代表不需要传输数据。 | 822| startOptions | [StartOptionParams](#startoptionparams) | 否 | 否 | 配置应用启动选项。 | 823| parameters | Record<string, string> | 否 | 否 | 配置连接所需的额外信息。 | 824 825## ConnectResult 826 827连接的结果。 828 829**系统能力**：SystemCapability.DistributedSched.AppCollaboration 830 831| 名称 | 类型 | 只读 | 可选 | 说明 | 832| -------- | ------ | ---- | ---- | ------- | 833| isConnected | boolean | 是 | 是 | true表示连接成功，false表示连接失败。 | 834| errorCode | [ConnectErrorCode](#connecterrorcode) | 是 | 否 | 表示连接错误码。 | 835| reason | string | 是 | 否 | 表示拒绝连接的原因。 | 836 837## EventCallbackInfo 838 839回调方法的接收信息。 840 841**系统能力**：SystemCapability.DistributedSched.AppCollaboration 842 843| 名称 | 类型 | 可读 | 可写 | 说明 | 844| -------- | ------ | ---- | ---- | ----------- | 845| sessionId | number | 是 | 是 | 表示当前事件对应的协同会话ID。 | 846| reason | [DisconnectReason](#disconnectreason) | 是 | 否 | 表示断连原因。 | 847| msg | string | 是 | 否 | 表示接收的消息。 | 848| data | ArrayBuffer | 是 | 否 | 表示接收的字节流。 | 849 850## CollaborateEventInfo 851 852协同事件信息。 853 854**系统能力**：SystemCapability.DistributedSched.AppCollaboration 855 856| 名称 | 类型 | 只读 | 可选 | 说明 | 857| -------- | ------ | ---- | ---- | ------- | 858| eventType | [CollaborateEventType](#collaborateeventtype) | 是 | 是 | 表示协同事件的类型。 | 859| eventMsg | string | 是 | 否 | 表示协同事件的消息内容。 | 860 861## ConnectErrorCode 862 863连接的错误码。 864 865**系统能力**：SystemCapability.DistributedSched.AppCollaboration 866 867| 名称| 值 | 说明 | 868|-------|-------|-------| 869| CONNECTED_SESSION_EXISTS | 0 |表示应用之间存在已连接的会话。| 870| PEER_APP_REJECTED | 1 |表示对端应用拒绝了协作请求。| 871| LOCAL_WIFI_NOT_OPEN | 2 |表示本端WiFi未开启。| 872| PEER_WIFI_NOT_OPEN | 3 |表示对端WiFi未开启。| 873| PEER_ABILITY_NO_ONCOLLABORATE | 4 |表示未实现onCollaborate方法。| 874| SYSTEM_INTERNAL_ERROR | 5 |表示系统内部错误。| 875 876## StartOptionParams 877 878启动选项参数的枚举。 879 880**系统能力**：SystemCapability.DistributedSched.AppCollaboration 881 882| 名称| 值 | 说明 | 883|-------|-------|-------| 884| START_IN_FOREGROUND | 0 |表示将对端应用启动至前台。| 885 886## CollaborateEventType 887 888协同事件类型的枚举。 889 890**系统能力**：SystemCapability.DistributedSched.AppCollaboration 891 892| 名称| 值 | 说明 | 893|-------|-------|-------| 894| SEND_FAILURE | 0 |表示任务发送失败。| 895| COLOR_SPACE_CONVERSION_FAILURE | 1 |表示色彩空间转换失败。| 896 897## DisconnectReason 898 899当前断连原因的枚举。 900 901**系统能力**：SystemCapability.DistributedSched.AppCollaboration 902 903| 名称| 值 | 说明 | 904|-------|-------|-------| 905| PEER_APP_CLOSE_COLLABORATION | 0 |表示对端应用主动关闭了协作。| 906| PEER_APP_EXIT | 1 |表示对端应用退出。| 907| NETWORK_DISCONNECTED | 2 |表示网络断开。| 908 909## CollaborationKeys 910 911应用协作键值的枚举。 912 913**系统能力**：SystemCapability.DistributedSched.AppCollaboration 914 915| 名称 | 值 | 说明 | 916| -------------------| ------------------------------- | ---------------------- | 917| PEER_INFO | ohos.collaboration.key.peerInfo | 表示对端设备信息的键值。 | 918| CONNECT_OPTIONS | ohos.collaboration.key.connectOptions | 表示连接选项的键值。 | 919| COLLABORATE_TYPE | ohos.collaboration.key.abilityCollaborateType | 表示协作类型的键值。 | 920 921## CollaborationValues 922 923应用协作相关值的枚举。 924 925**系统能力**：SystemCapability.DistributedSched.AppCollaboration 926 927| 名称 | 值 | 说明 | 928| ----------------------------------------- | -------- | ---------------------- | 929| ABILITY_COLLABORATION_TYPE_DEFAULT | ohos.collaboration.value.abilityCollab | 表示默认的协作类型。 | 930| ABILITY_COLLABORATION_TYPE_CONNECT_PROXY | ohos.collaboration.value.connectProxy | 表示连接代理的协作类型。 | 931