鸿蒙跨设备协同开发03——分布式设备管理

如果你也对鸿蒙开发感兴趣，加入“Harmony自习室”吧！扫描下方名片，关注公众号，公众号更新更快，同时也有更多学习资料和技术讨论群。

1、概 述

随着用户不同种类的终端设备数量不断增多，将不同设备作为本端设备能力的扩展，使设备之间协同合作完成各种复杂场景即为: 设备的分布式业务。

HarmonyOS分布式管理服务套件（Distributed Service Kit）实现了分布式设备管理、分布式硬件管理、分布式键鼠穿越等能力。我们可以通过分布式设备管理服务进行周边设备的发现、认证、信息查询、状态监听等。分布式设备管理提供如下四大功能：

• 【 发 现 】

发现周围终端设备并上报。周围设备需要连接同局域网或者同时打开蓝牙，可以根据设备类型、距离、设备是否可信等进行筛选。

• 【 绑 定 】

不同设备协同合作完成分布式业务的前提是设备间可信，对于周边发现的不可信设备，可通过绑定使彼此建立可信关系，提供pin码、碰、扫、靠等设备认证框架，支持对接各种认证交互接口。

• 【 查 询 】

查询功能包含：查询本机设备信息、查询周围的在线的可信设备、查询可信设备信息。

• 【 监 听 】

监听设备上、下线。设备上线表示设备间已经可信，业务可以发起分布式操作；设备下线表示分布业务不可用。

设备管理服务作为分布式业务入口，需要应用在所使用的业务场景，向发现设备主动发起绑定建立可信关系；业务结束后由业务自主判断是否解除绑定关系，设备间可信关系的解除由业务自己控制。

有一些问题需要注意：

1. 使用设备管理能力时，需要用户确认不同设备已连接同一局域网或者蓝牙开关已开启，否则该能力不可用。

2. 设备信息属于用户敏感数据，所以即使用户已连接同一局域网或者蓝牙开关已开启，应用在获取设备位置前仍需向用户申请数据同步权限。在用户确认允许后，系统才会向应用提供设备管理能力。

3. 使用分布式设备管理，需要用户进行相关权限的申请。

2、权限申请

应用在使用分布式设备管理系统能力前，需要检查是否已经获取用户授权访问分布式数据同步信息。如未获得授权，可以向用户申请需要的分布式数据同步权限。ohos.permission.DISTRIBUTED_DATASYNC：分布式数据同步权限。

【使用设备管理能力，必须申请权限并且获得用户授权】

分布式数据同步权限申请分为以下两步：

👉🏻 step 1

在module.json5配置文件中配置分布式数据同步权限（ohos.permission.DISTRIBUTED_DATASYNC）示例如下：

{  "module" : {    "requestPermissions":[      {        "name" : "ohos.permission.DISTRIBUTED_DATASYNC",        "reason": "$string:distributed_permission",        "usedScene": {          "abilities": [            "MainAbility"          ],          "when": "inuse"        }      }    ]  }}

👉🏻 step 2

arkTs中调用相关接口，以动态弹窗的方式向用户申请权限。示例代码如下：​​​​​​​

// 导入common和abilityAccessCtrl模块，用于获取权限申请的能力。import { common, abilityAccessCtrl } from '@kit.AbilityKit';// ... let context = getContext(this) as common.UIAbilityContext;let atManager = abilityAccessCtrl.createAtManager();try {  atManager.requestPermissionsFromUser(context, ['ohos.permission.DISTRIBUTED_DATASYNC']).then((data) => {    console.log('data: ' + JSON.stringify(data));  }).catch((err: object) => {    console.log('err: ' + JSON.stringify(err));  })} catch (err) {  console.log('catch err->' + JSON.stringify(err));}

由于分布式数据同步权限的授权方式为user_grant，因此需要调用requestPermissionsFromUser接口，以动态弹窗的方式向用户申请授权。

3、设备发现

我们可以调用DeviceManager设备发现相关接口，获取周边可用的设备。接口定义如下：

startDiscovering(discoverParam: {[key: string]: Object;} , filterOptions?: {[key: string]: Object;} ): void;

发现周边同局域网或者开启蓝牙的设备。发现状态持续两分钟，超过两分钟，会停止发现，最大发现数量99个。wifi场景要求同局域网。

startDiscovering有两个参数，分别为：

• discoverParam

发现标识。标识发现的目标类型。discoverTargetType: 发现目标默认为设备，值为1。

• filterOptions

发现设备过滤信息。可选，默认为undefined，发现未上线设备。会携带以下key值：

availableStatus(0-1)：仅发现设备可信，值为0表示设备不可信。

    -0：设备离线，客户端需要通过调用bindTarget绑定设备。

    -1：设备已在线，客户可以进行连接。

discoverDistance(0-100)：发现距离本地一定距离内的设备，单位为cm。wifi场景不传该参数。

authenticationStatus(0-1)：根据不同的认证状态发现设备：

    -0：设备未认证。

    -1：设备已认证。

authorizationType(0-2)：根据不同的授权类型发现设备：

    -0：根据临时协商的会话密钥认证的设备。

    -1：基于同账号密钥进行身份验证的设备。

    -2：基于不同账号凭据密钥认证的设备。

申请完权限后，设备发现的开发步骤一般分为三步：

👉🏻 step 1: 导入相关模块​​​​​​​

import { distributedDeviceManager } from '@kit.DistributedServiceKit';import { BusinessError } from '@kit.BasicServicesKit';

👉🏻 step 2: 创建设备管理实例(设备管理实例是分布式设备管理方法的调用入口)并注册发现设备的回调。​​​​​​​

try {  let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld');  dmInstance.on('discoverSuccess', data => console.log('discoverSuccess on:' + JSON.stringify(data)));  dmInstance.on('discoverFailure', data => console.log('discoverFailure on:' + JSON.stringify(data)));} catch(err) {  let e: BusinessError = err as BusinessError;  console.error('createDeviceManager errCode:' + e.code + ',errMessage:' + e.message);}

👉🏻 step 3： 发现周边设备。发现状态持续两分钟，超过两分钟，会停止发现，最大发现数量99个。​​​​​​​

interface DiscoverParam {  discoverTargetType: number;}interface FilterOptions {  availableStatus: number;  discoverDistance: number;  authenticationStatus: number;  authorizationType: number;}let discoverParam: Record<string, number> = {  'discoverTargetType': 1};let filterOptions: Record<string, number> = {  'availableStatus': 0};try {  dmInstance.startDiscovering(discoverParam, filterOptions);} catch (err) {  let e: BusinessError = err as BusinessError;  console.error('startDiscovering errCode:' + e.code + ',errMessage:' + e.message);}

4、设备绑定

开发者发现周边不可信设备后，通过绑定接口建立可信关系。设备绑定接口定义如下：

bindTarget(deviceId: string, bindParam: {[key: string]: Object;} , callback: AsyncCallback<{deviceId: string;}>): void;

bindTarget有两个参数，分别为：

• deviceId:

  设备标识。

• bindParam

    认证参数。由开发者自行决定传入的键值对。默认会携带以下key值：

    bindType 此值是绑定的类型，必填。

    -1：PIN码。

    targetPkgName 绑定目标的包名。

    appName 尝试绑定目标的应用程序名称。

    appOperation 应用程序要绑定目标的原因。

    customDescription 操作的详细说明。

• callback

    认证结果回调。    

完成申请权限和设备扫描后，发起设备绑定的代码大致如下：​​​​​​​

class Data {  deviceId: string = '';}let deviceId = 'XXXXXXXX';let bindParam: Record<string, string | number> = {  'bindType': 1,   'targetPkgName': 'xxxx',  'appName': 'xxxx',  'appOperation': 'xxxx',  'customDescription': 'xxxx'};try {  dmInstance.bindTarget(deviceId, bindParam, (err: BusinessError, data: Data) => {    if (err) {      console.error('bindTarget errCode:' + err.code + ',errMessage:' + err.message);      return;    }    console.info('bindTarget result:' + JSON.stringify(data));  });} catch (err) {  let e: BusinessError = err as BusinessError;  console.error('bindTarget errCode:' + e.code + ',errMessage:' + e.message);}

5、设备信息查询

经历过第四步与周边设备建立可信关系后，我们可以通过设备信息查询接口获取所有上线并且可信的设备信息。查询接口定义如下：

getAvailableDeviceListSync(): Array<DeviceBasicInfo>;

返回值 DeviceBasicInfo结构如下：​​​​​​​

interface DeviceBasicInfo {deviceId: string // 设备的唯一标识。实际值为udid-hash与appid基于sha256方式进行加密后的值。deviceName: string //  设备名称。deviceType: string //  设备类型。networkId: string // 设备网络标识。}

绑定完设备后，设备信息查询示例代码如下：​​​​​​​

try {  let deviceInfoList: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync();} catch (err) {  let e: BusinessError = err as BusinessError;  console.error('getAvailableDeviceListSync errCode:' + e.code + ',errMessage:' + e.message);}

6、设备上下线监听

周边可信设备可用后会给业务报上线通知，当设备不可用时会给业务报下线通知。接口定义如下：

on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChange; device: DeviceBasicInfo; }>): void;

注册设备状态回调，以便在设备状态发生变化时根据应用捆绑包名通知应用。

其中callback函数有两个入参，分别是:

• DeviceStateChange

表示设备状态，枚举值有三个：UNKNOWN、AVAILABLE、UNAVAILABLE。含义分别为：

    UNKOWN: 设备物理上线，此时状态未知，在状态更改为可用之前，分布式业务无法使用。

    AVAILABLE：设备可用状态，表示设备间信息已在分布式数据中同步完成, 可以运行分布式业务。

    UNAVAILABLE：设备物理下线，此时状态未知。

• DeviceBasicInfo结构如下

interface DeviceBasicInfo {deviceId: string // 设备的唯一标识。实际值为udid-hash与appid基于sha256方式进行加密后的值。deviceName: string //  设备名称。deviceType: string //  设备类型。networkId: string // 设备网络标识。}

完成权限申请后，监听设备上下线的步骤一般分为两步：

👉🏻 step 1：导入相关模块​​​​​​​

import { distributedDeviceManager } from '@kit.DistributedServiceKit';import { BusinessError } from '@kit.BasicServicesKit';

👉🏻 step 2：创建设备管理实例，设备管理实例是分布式设备管理方法的调用入口，并注册设备上下线回调。​​​​​​​

try {  let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld');  dmInstance.on('deviceStateChange', data => console.log('deviceStateChange on:' + JSON.stringify(data)));} catch(err) {  let e: BusinessError = err as BusinessError;  console.error('createDeviceManager errCode:' + e.code + ',errMessage:' + e.message);}