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