@ohos.distributedsched.abilityConnectionManager (应用多端协同管理)

abilityConnectionManager模块提供了应用协同接口管理能力。设备组网成功（需登录同账号、双端打开蓝牙）后，系统应用和三方应用可以跨设备拉起同应用的一个UIAbility，拉起并连接成功后可实现跨设备数据传输（文本信息）。

说明：

本模块首批接口从API version 18开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { abilityConnectionManager } from '@kit.DistributedServiceKit';

abilityConnectionManager.createAbilityConnectionSession

createAbilityConnectionSession(serviceName: string, context: Context, peerInfo: PeerInfo , connectOptions: ConnectOptions): number

创建应用间的协同会话。

需要权限：ohos.permission.INTERNET、ohos.permission.GET_NETWORK_INFO、ohos.permission.SET_NETWORK_INFO和ohos.permission.DISTRIBUTED_DATASYNC

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

1. 在设备A上，应用需要主动调用createAbilityConnectionSession()接口创建协同会话并返回sessionId。

   import { abilityConnectionManager, distributedDeviceManager } from '@kit.DistributedServiceKit';
   import { common } from '@kit.AbilityKit';
   import { hilog } from '@kit.PerformanceAnalysisKit';
 
   let dmClass: distributedDeviceManager.DeviceManager;
 
   function initDmClass(): void {
     try {
       dmClass = distributedDeviceManager.createDeviceManager('com.example.remotephotodemo');
     } catch (err) {
       hilog.error(0x0000, 'testTag', 'createDeviceManager err: ' + JSON.stringify(err));
     }
   }
 
   function getRemoteDeviceId(): string|undefined {
     initDmClass();
     if (typeof dmClass === 'object' && dmClass !== null) {
       hilog.info(0x0000, 'testTag', 'getRemoteDeviceId begin');
       let list = dmClass.getAvailableDeviceListSync();
       if (typeof (list) === 'undefined'||typeof (list.length) === 'undefined') {
         hilog.info(0x0000, 'testTag', 'getRemoteDeviceId err: list is null');
         return;
       }
       if (list.length === 0) {
         hilog.info(0x0000, 'testTag', 'getRemoteDeviceId err: list is empty');
         return;
       }
       return list[0].networkId;
     } else {
       hilog.info(0x0000, 'testTag', 'getRemoteDeviceId err: dmClass is null');
       return;
     }
   }
 
   @Entry
   @Component
   struct Index {
     createSession(): void {
       // 定义peer信息
       const peerInfo: abilityConnectionManager.PeerInfo = {
         deviceId: "sinkDeviceId",
         bundleName: 'com.example.remotephotodemo',
         moduleName: 'entry',
         abilityName: 'EntryAbility',
         serviceName: 'collabTest'
       };
       const myRecord: Record<string, string> = {
         "newKey1": "value1",
       };
 
       // 定义连接选项
       const connectOptions: abilityConnectionManager.ConnectOptions = {
         needSendData: true,
         startOptions: abilityConnectionManager.StartOptionParams.START_IN_FOREGROUND,
         parameters: myRecord
       };
       let context = this.getUIContext().getHostContext();
       try {
         let sessionId = abilityConnectionManager.createAbilityConnectionSession("collabTest", context, peerInfo, connectOptions);
         hilog.info(0x0000, 'testTag', 'createSession sessionId is', sessionId);
       } catch (error) {
         hilog.error(0x0000, 'testTag', error);
       }
     }
 
     build() {
     }
   }

1. 在设备B上，对于createAbilityConnectionSession接口的调用，可在应用被拉起后触发协同生命周期函数onCollaborate时，在onCollaborate内进行。

   import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
   import { abilityConnectionManager } from '@kit.DistributedServiceKit';
   import { hilog } from '@kit.PerformanceAnalysisKit';
    
   export default class EntryAbility extends UIAbility {
     onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult {
       hilog.info(0x0000, 'testTag', '%{public}s', 'on collaborate');
       let param = wantParam["ohos.extra.param.key.supportCollaborateIndex"] as Record<string, Object>
       this.onCollab(param);
       return 0;
     }
    
     onCollab(collabParam: Record<string, Object>) {
       const sessionId = this.createSessionFromWant(collabParam);
       if (sessionId == -1) {
         hilog.info(0x0000, 'testTag', 'Invalid session ID.');
         return;
       }
     }
    
     createSessionFromWant(collabParam: Record<string, Object>): number {
       let sessionId = -1;
       const peerInfo = collabParam["PeerInfo"] as abilityConnectionManager.PeerInfo;
       if (peerInfo == undefined) {
         return sessionId;
       }
    
       const options = collabParam["ConnectOptions"] as abilityConnectionManager.ConnectOptions;
       try {
         sessionId = abilityConnectionManager.createAbilityConnectionSession("collabTest", this.context, peerInfo, options);
         AppStorage.setOrCreate('sessionId', sessionId);
         hilog.info(0x0000, 'testTag', 'createSession sessionId is' + sessionId);
       } catch (error) {
         hilog.error(0x0000, 'testTag', error);
       }
       return sessionId;
     }
   }

abilityConnectionManager.destroyAbilityConnectionSession

destroyAbilityConnectionSession(sessionId: number): void

销毁应用间的协同会话。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  hilog.info(0x0000, 'testTag', 'destroyAbilityConnectionSession called');
  let sessionId = 100;
  abilityConnectionManager.destroyAbilityConnectionSession(sessionId);

abilityConnectionManager.getPeerInfoById

getPeerInfoById(sessionId: number): PeerInfo | undefined

获取指定会话中对端应用信息。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  hilog.info(0x0000, 'testTag', 'getPeerInfoById called');
  let sessionId = 100;
  const peerInfo = abilityConnectionManager.getPeerInfoById(sessionId);

abilityConnectionManager.connect

connect(sessionId: number): Promise<ConnectResult>

创建协同会话成功并获得会话ID后，设备A上可进行UIAbility的连接。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

设备A上的应用在创建协同会话成功并获得会话ID后，调用connect()方法启动UIAbility连接，并拉起设备B应用。

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.connect(sessionId).then((ConnectResult) => {
    if (!ConnectResult.isConnected) {
      hilog.info(0x0000, 'testTag', 'connect failed');
      return;
    }
  }).catch(() => {
    hilog.error(0x0000, 'testTag', "connect failed");
  })

abilityConnectionManager.acceptConnect

acceptConnect(sessionId: number, token: string): Promise<void>

设备B上的应用，在创建协同会话成功并获得会话ID后，调用acceptConnect()方法接受连接。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

设备B上的应用，在createAbilityConnectionSession接口调用并获取sessionId成功后，可调用acceptConnect接口来选择接受连接。

  import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
      hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
    }

    onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult {
      hilog.info(0x0000, 'testTag', '%{public}s', 'on collaborate');
      let param = wantParam["ohos.extra.param.key.supportCollaborateIndex"] as Record<string, Object>
      this.onCollab(param);
      return 0;
    }

    onCollab(collabParam: Record<string, Object>) {
      const sessionId = this.createSessionFromWant(collabParam);
      if (sessionId == -1) {
        hilog.info(0x0000, 'testTag', 'Invalid session ID.');
        return;
      }
      const collabToken = collabParam["ohos.dms.collabToken"] as string;
      abilityConnectionManager.acceptConnect(sessionId, collabToken).then(() => {
        hilog.info(0x0000, 'testTag', 'acceptConnect success');
      }).catch(() => {
        hilog.error(0x0000, 'testTag', 'failed'); 
      })
    }

    createSessionFromWant(collabParam: Record<string, Object>): number {
      let sessionId = -1;
      const peerInfo = collabParam["PeerInfo"] as abilityConnectionManager.PeerInfo;
      if (peerInfo == undefined) {
        return sessionId;
      }

      const options = collabParam["ConnectOptions"] as abilityConnectionManager.ConnectOptions;
      try {
        sessionId = abilityConnectionManager.createAbilityConnectionSession("collabTest", this.context, peerInfo, options);
        AppStorage.setOrCreate('sessionId', sessionId);
        hilog.info(0x0000, 'testTag', 'createSession sessionId is' + sessionId);
      } catch (error) {
        hilog.error(0x0000, 'testTag', error);
      }
      return sessionId;
    }
  }

abilityConnectionManager.disconnect

disconnect(sessionId: number): void

当协同业务执行完毕后，协同双端的任意一台设备，应断开UIAbility的连接，结束协同状态。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  hilog.info(0x0000, 'testTag', 'disconnectRemoteAbility begin');
  let sessionId = 100;
  abilityConnectionManager.disconnect(sessionId);

abilityConnectionManager.reject

reject(token: string, reason: string): void;

在跨端应用协同过程中，在拒绝对端的连接请求后，向对端发送拒绝原因。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { AbilityConstant, UIAbility, Want} from '@kit.AbilityKit';
  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  export default class EntryAbility extends UIAbility {
      onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult {
        hilog.info(0x0000, 'testTag', '%{public}s', 'on collaborate');
        let collabParam = wantParam["ohos.extra.param.key.supportCollaborateIndex"] as Record<string, Object>;
        const collabToken = collabParam["ohos.dms.collabToken"] as string;
        const reason = "test";
        hilog.info(0x0000, 'testTag', 'reject begin');
        abilityConnectionManager.reject(collabToken, reason);
        return AbilityConstant.CollaborateResult.REJECT;
      }
  }

abilityConnectionManager.on(‘connect’)

on(type: ‘connect’, sessionId: number, callback: Callback<EventCallbackInfo>): void

注册connect事件的回调监听。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.on("connect", sessionId,(callbackInfo) => {
    hilog.info(0x0000, 'testTag', 'session connect, sessionId is', callbackInfo.sessionId);
  });

abilityConnectionManager.off(‘connect’)

off(type: ‘connect’, sessionId: number, callback?: Callback<EventCallbackInfo>): void

取消connect事件的回调监听。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.off("connect", sessionId);

abilityConnectionManager.on(‘disconnect’)

on(type: ‘disconnect’, sessionId: number, callback: Callback<EventCallbackInfo>): void

注册disconnect事件的回调监听。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.on("disconnect", sessionId,(callbackInfo) => {
    hilog.info(0x0000, 'testTag', 'session disconnect, sessionId is', callbackInfo.sessionId);
  });

abilityConnectionManager.off(‘disconnect’)

off(type: ‘disconnect’, sessionId: number, callback?: Callback<EventCallbackInfo>): void

取消disconnect事件的回调监听。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.off("disconnect", sessionId);

abilityConnectionManager.on(‘receiveMessage’)

on(type: ‘receiveMessage’, sessionId: number, callback: Callback<EventCallbackInfo>): void

注册receiveMessage事件的回调监听。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.on("receiveMessage", sessionId,(callbackInfo) => {
    hilog.info(0x0000, 'testTag', 'receiveMessage, sessionId is', callbackInfo.sessionId);
  });

abilityConnectionManager.off(‘receiveMessage’)

off(type: ‘receiveMessage’, sessionId: number, callback?: Callback<EventCallbackInfo>): void

取消receiveMessage事件的回调监听。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.off("receiveMessage", sessionId);

abilityConnectionManager.on(‘receiveData’)

on(type: ‘receiveData’, sessionId: number, callback: Callback<EventCallbackInfo>): void

注册receiveData事件的回调监听。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.on("receiveData", sessionId,(callbackInfo) => {
    hilog.info(0x0000, 'testTag', 'receiveData, sessionId is', callbackInfo.sessionId);
  });

abilityConnectionManager.off(‘receiveData’)

off(type: ‘receiveData’, sessionId: number, callback?: Callback<EventCallbackInfo>): void

取消receiveData事件的回调监听。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.off("receiveData", sessionId);

abilityConnectionManager.sendMessage

sendMessage(sessionId: number, msg: string): Promise<void>

应用连接成功后，设备A或设备B可向对端设备发送文本信息。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  let sessionId = 100;
  abilityConnectionManager.sendMessage(sessionId, "message send success").then(() => {
    hilog.info(0x0000, 'testTag', "sendMessage success");
  }).catch(() => {
    hilog.error(0x0000, 'testTag', "connect failed");
  })

abilityConnectionManager.sendData

sendData(sessionId: number, data: ArrayBuffer): Promise<void>

应用连接成功后，设备A或设备B可向对端设备发送ArrayBuffer字节流。

系统能力：SystemCapability.DistributedSched.AppCollaboration

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

  import { abilityConnectionManager } from '@kit.DistributedServiceKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';
  import { util } from '@kit.ArkTS';

  let textEncoder = util.TextEncoder.create("utf-8");
  const arrayBuffer  = textEncoder.encodeInto("data send success");

  let sessionId = 100;
  abilityConnectionManager.sendData(sessionId, arrayBuffer.buffer).then(() => {
    hilog.info(0x0000, 'testTag', "sendMessage success");
  }).catch(() => {
    hilog.info(0x0000, 'testTag', "sendMessage failed");
  })

PeerInfo

应用协同信息。

系统能力：SystemCapability.DistributedSched.AppCollaboration

ConnectOptions

应用连接时所需的连接选项。

系统能力：SystemCapability.DistributedSched.AppCollaboration

ConnectResult

连接的结果。

系统能力：SystemCapability.DistributedSched.AppCollaboration

EventCallbackInfo

回调方法的接收信息。

系统能力：SystemCapability.DistributedSched.AppCollaboration

CollaborateEventInfo

协同事件信息。

系统能力：SystemCapability.DistributedSched.AppCollaboration

ConnectErrorCode

连接的错误码。

系统能力：SystemCapability.DistributedSched.AppCollaboration

StartOptionParams

启动选项参数的枚举。

系统能力：SystemCapability.DistributedSched.AppCollaboration

CollaborateEventType

协同事件类型的枚举。

系统能力：SystemCapability.DistributedSched.AppCollaboration

DisconnectReason

当前断连原因的枚举。

系统能力：SystemCapability.DistributedSched.AppCollaboration

CollaborationKeys

应用协作键值的枚举。

系统能力：SystemCapability.DistributedSched.AppCollaboration

CollaborationValues

应用协作相关值的枚举。

系统能力：SystemCapability.DistributedSched.AppCollaboration

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Distributed Service Kit（分布式管理服务）

harmony 鸿蒙DeviceManager

harmony 鸿蒙oh_device_manager_err_code.h

harmony 鸿蒙oh_device_manager.h

harmony 鸿蒙设备管理错误码

harmony 鸿蒙键鼠穿越管理错误码

harmony 鸿蒙增强连接错误码

harmony 鸿蒙@ohos.distributedHardware.deviceManager (设备管理)(系统接口)

harmony 鸿蒙@ohos.cooperate (键鼠穿越)（系统接口）

harmony 鸿蒙@ohos.distributedsched.abilityConnectionManager (应用多端协同管理)(系统接口)