Distributed Device Management Development

Introduction

The distributed service allows multiple physically separated devices to be integrated into a virtual Super Device, allowing one device to control others and sharing data among devices with distributed communication capabilities.

As the entry of the distributed service, distributed device management implements unified management of trusted and untrusted devices nearby.

Distributed device management provides the following functionalities:

Discovering devices
Discover and report the devices that are connected to the same LAN or have Bluetooth enabled. You can filter devices based on the device type, distance, and whether the device is trusted.
Binding a device
Bind an untrusted device discovered to establish a trust relationship with each other. The device authentication framework provides a variety of authentication modes, such as PIN-based pairing, tap-to-pair, and scan-to-pair, and supports diversified authentication APIs.
Querying device information
Obtain local device information, brief information about all the trusted devices, and detailed information about a trusted device.
Listening for devices
Listen for online/offline status of nearby devices. If a device goes online, the device is trusted and distributed operations can be performed. If a device goes offline, the distributed service is unavailable.

Working Principles

When discovering a device, the application initiates a request for binding the device to establish a trust relationship. When the service ends, the service determines whether to unbind the device.

Constraints

The distributed service is available only for the devices connected to the same LAN or have Bluetooth enabled.

Device information is sensitive user data. Even if the devices are connected to the same LAN or have Bluetooth enabled, the application must request the ohos.permission.DISTRIBUTED_DATASYNC permission from the user before obtaining the device location. The system provides the device management capabilities for the application only after the user has granted the permission.

Requesting Permissions

Scenario

To use the distributed device management capabilities, your application must have the ohos.permission.DISTRIBUTED_DATASYNC permission, which allows the application data to be exchanged between devices. This permission is a user_grant permission, which means the application must apply for user authorization.

Before using the distributed device management capabilities, the application must be checked for the required permission.

How to Develop

The APIs used in this section are based on the stage model.

Declare the ohos.permission.DISTRIBUTED_DATASYNC permission in the module.json5 file.

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

Import the common and abilityAccessCtrl modules.

import common from '@ohos.app.ability.common';
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

Use requestPermissionsFromUser to request user authorization for the ohos.permission.DISTRIBUTED_DATASYNC permission.

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));
}

Discovering Devices

Scenario

Discover nearby devices.

Available APIs

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

Starts to discover the devices that are in the same LAN or have Bluetooth enabled. For details, see startDiscovering.

How to Develop

Request the ohos.permission.DISTRIBUTED_DATASYNC permission for your application.
Import the deviceManager module, which provides APIs for device management.
```
import deviceManager from '@ohos.distributedDeviceManager';
```
Import the BusinessError module, which provides the error codes thrown by the APIs of the deviceManager module.
```
import { BusinessError } from '@ohos.base';
```

Create a DeviceManager instance, which is the entry for calling distributed device management APIs and registering the callback for discovering devices.

try {
  let dmInstance = deviceManager.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);
}

Start to discover devices. The discovery process lasts 2 minutes, and a maximum of 99 devices can be discovered.

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);
}

Binding a Device

Scenario

Bind an untrusted device discovered to establish a trust relationship.

Available APIs

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

Binds a device. For details, see bindTarget.

How to Develop

Request the ohos.permission.DISTRIBUTED_DATASYNC permission for your application.
Discover devices nearby.

Bind an untrusted device.

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);
}

Querying Device Information

Scenario

Obtain information about all the online and trusted devices.

Available APIs

getAvailableDeviceListSync(): Array<DeviceBasicInfo>;

Obtains information about all the available devices. For details, see getAvailableDeviceListSync.

How to Develop

Request the ohos.permission.DISTRIBUTED_DATASYNC permission for your application.
Discover devices nearby.
Bind an untrust device to establish a trust relationship.

Obtain information about all the online and trusted devices.

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

Listening for Device Online/Offline Status

Scenario

You can listen for the device online/offline status. The service will be notified when a device goes offline or online.

Available APIs

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

Listens for device online/offline status. For details, see on('deviceStateChange').

How to Develop

Request the ohos.permission.DISTRIBUTED_DATASYNC permission for your application.
Import the deviceManager module, which provides APIs for device management.
```
import deviceManager from '@ohos.distributedDeviceManager';
```
Import the BusinessError module, which provides the error codes thrown by the APIs of the deviceManager module.
```
import { BusinessError } from '@ohos.base';
```

Create a DeviceManager instance.

try {
  let dmInstance = deviceManager.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);
}