@ohos.distributedDeviceManager (Device Management)

The distributedDeviceManager module provides APIs for distributed device management.

Applications can call the APIs to:

• Subscribe to or unsubscribe from device state changes.
• Discover untrusted devices nearby.
• Authenticate or deauthenticate a device.
• Query the trusted device list.
• Query local device information, including the device name, type, and ID.

NOTE

• The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import deviceManager from '@ohos.distributedDeviceManager';

deviceManager.createDeviceManager

createDeviceManager(bundleName: string): DeviceManager;

Creates a DeviceManager instance. The DeviceManager instance is the entry for invoking the APIs for distributed device management. It can be used to obtain information about trusted devices and local devices.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Return value

Example

import deviceManager from '@ohos.distributedDeviceManager'
import { BusinessError } from '@ohos.base'

try {
  let dmInstance = deviceManager.createDeviceManager("ohos.samples.jshelloworld");
} catch(err) {
  let e: BusinessError = err as BusinessError;
  console.error("createDeviceManager errCode:" + e.code + ",errMessage:" + e.message);
}

deviceManager.releaseDeviceManager

releaseDeviceManager(deviceManager: DeviceManager): void;

Releases a DeviceManager instance that is no longer used.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'
import deviceManager from '@ohos.distributedDeviceManager'

try {
  let dmInstance = deviceManager.createDeviceManager("ohos.samples.jshelloworld");
  deviceManager.releaseDeviceManager(dmInstance);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("release device manager errCode:" + e.code + ",errMessage:" + e.message);
}

DeviceBasicInfo

Represents the basic information about a distributed device.

System capability: SystemCapability.DistributedHardware.DeviceManager

DeviceStateChange

Enumerates the device states.

System capability: SystemCapability.DistributedHardware.DeviceManager

DeviceManager

Provides APIs to obtain information about trusted devices and local devices. Before calling any API in DeviceManager, you must use createDeviceManager to create a DeviceManager instance, for example, dmInstance.

getAvailableDeviceListSync

getAvailableDeviceListSync(): Array<DeviceBasicInfo>;

Obtains all trusted devices synchronously.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import deviceManager from '@ohos.distributedDeviceManager'
import { BusinessError } from '@ohos.base'

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

getAvailableDeviceList

getAvailableDeviceList(callback:AsyncCallback<Array<DeviceBasicInfo>>): void;

Obtains all trusted devices. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import deviceManager from '@ohos.distributedDeviceManager'
import { BusinessError } from '@ohos.base'

try {
  dmInstance.getAvailableDeviceList((err: BusinessError, data: Array<deviceManager.DeviceBasicInfo>) => {
    if (err) {
      console.error("getAvailableDeviceList errCode:" + err.code + ",errMessage:" + err.message);
      return;
    }
    console.log('get available device info: ' + JSON.stringify(data));
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("getAvailableDeviceList errCode:" + e.code + ",errMessage:" + e.message);
}

getAvailableDeviceList

getAvailableDeviceList(): Promise<Array<DeviceBasicInfo>>;

Obtains all trusted devices. This API uses a promise to return the result.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import deviceManager from '@ohos.distributedDeviceManager'
import { BusinessError } from '@ohos.base'

dmInstance.getAvailableDeviceList().then((data: Array<deviceManager.DeviceBasicInfo>) => {
  console.log('get available device info: ' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error("getAvailableDeviceList errCode:" + err.code + ",errMessage:" + err.message);
});

getLocalDeviceNetworkId

getLocalDeviceNetworkId(): string;

Obtains the network ID of the local device.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

try {
  let deviceNetworkId: string = dmInstance.getLocalDeviceNetworkId();
  console.log('local device networkId: ' + JSON.stringify(deviceNetworkId));
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("getLocalDeviceNetworkId errCode:" + e.code + ",errMessage:" + e.message);
}

getLocalDeviceName

getLocalDeviceName(): string;

Obtains the local device name.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

try {
  let deviceName: string = dmInstance.getLocalDeviceName();
  console.log('local device name: ' + JSON.stringify(deviceName));
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("getLocalDeviceName errCode:" + e.code + ",errMessage:" + e.message);
}

getLocalDeviceType

getLocalDeviceType(): number;

Obtains the local device type.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

try {
  let deviceType: number = dmInstance.getLocalDeviceType();
  console.log('local device type: ' + JSON.stringify(deviceType));
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("getLocalDeviceType errCode:" + e.code + ",errMessage:" + e.message);
}

getLocalDeviceId

getLocalDeviceId(): string;

Obtains the local device ID.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

try {
  let deviceId: string = dmInstance.getLocalDeviceId();
  console.log('local device id: ' + JSON.stringify(deviceId));
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("getLocalDeviceId errCode:" + e.code + ",errMessage:" + e.message);
}

getDeviceName

getDeviceName(networkId: string): string;

Obtains the device name based on the network ID of the specified device.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Return value

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

try {
  // Network ID of the device, which can be obtained from the trusted device list.
  let networkId = "xxxxxxx"
  let deviceName: string = dmInstance.getDeviceName(networkId);
  console.log('device name: ' + JSON.stringify(deviceName)); 
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("getDeviceName errCode:" + e.code + ",errMessage:" + e.message);
}

getDeviceType

getDeviceType(networkId: string): number;

Obtains the device type based on the network ID of the specified device.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Return value

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

try {
  // Network ID of the device, which can be obtained from the trusted device list.
  let networkId = "xxxxxxx"
  let deviceType: number = dmInstance.getDeviceType(networkId);
  console.log('device type: ' + JSON.stringify(deviceType)); 
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("getDeviceType errCode:" + e.code + ",errMessage:" + e.message);
}

startDiscovering

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

Starts to discover devices nearby. The discovery process lasts 2 minutes. A maximum of 99 devices can be discovered. In Wi-Fi scenarios, only the devices in the same LAN can be discovered.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

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); // When devices are discovered, discoverSuccess is called to notify the application.
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("startDiscovering errCode:" + e.code + ",errMessage:" + e.message);
}

stopDiscovering

stopDiscovering(): void;

Stops device discovery.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

try {
  dmInstance.stopDiscovering();
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("stopDiscovering errCode:" + e.code + ",errMessage:" + e.message);
}

bindTarget

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

Binds a device.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

class Data {
  deviceId: string = ""
}

// Information about the device to authenticate. The information can be obtained from the device discovery result.
let deviceId = "XXXXXXXX";
let bindParam: Record<string, string | number> = {
  'bindType': 1, // Authentication type. The value 1 means PIN authentication.
  '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);
}

unbindTarget

unbindTarget(deviceId: string): void;

Unbinds a device.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

For details about the error codes, see Device Management Error Codes.

Example

import { BusinessError } from '@ohos.base'

try {
  let deviceId = "XXXXXXXX";
  dmInstance.unbindTarget(deviceId);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("unbindTarget errCode:" + e.code + ",errMessage:" + e.message);
}

replyUiAction

replyUiAction(action: number, actionResult: string): void;

Replies to the user's UI operation. This API can be used only by the PIN HAP of the deviceManager.

Required permissions: ohos.permission.ACCESS_SERVICE_DM

System capability: SystemCapability.DistributedHardware.DeviceManager

System API: This is a system API.

Parameters

Example

import { BusinessError } from '@ohos.base'

try {
  /*
    action = 0 - Grant the permission.
    action = 1 - Revoke the permission.
    action = 2 - The user operation in the permission request dialog box times out.
    action = 3 - Cancel the display of the PIN box.
    action = 4 - Cancel the display of the PIN input box.
    action = 5 - Confirm the input in the PIN input box.
  */
  let operation = 0;
  dmInstance.replyUiAction(operation, "extra")
  } catch (err) {
    let e: BusinessError = err as BusinessError;
    console.error("replyUiAction errCode:" + e.code + ",errMessage:" + e.message);
}

on('replyResult')

on(type: 'replyResult', callback: Callback<{ param: string}>): void;

Subscribes to the reply to the UI operation result.

Required permissions: ohos.permission.ACCESS_SERVICE_DM

System capability: SystemCapability.DistributedHardware.DeviceManager

System API: This is a system API.

Parameters

Example

import { BusinessError } from '@ohos.base'

class Data {
  param: string = ""
}

interface TmpStr {
  verifyFailed: boolean
}

try {
  dmInstance.on('replyResult', (data: Data) => {
  console.log("replyResult executed, dialog closed" + JSON.stringify(data))
  let tmpStr: TmpStr = JSON.parse(data.param)
  let isShow = tmpStr.verifyFailed
  console.log("replyResult executed, dialog closed" + isShow)
});
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("replyResult errCode:" + e.code + ",errMessage:" + e.message);
}

off('replyResult')

off(type: 'replyResult', callback?: Callback<{ param: string}>): void;

Unsubscribes from the reply to the UI operation result.

Required permissions: ohos.permission.ACCESS_SERVICE_DM

System capability: SystemCapability.DistributedHardware.DeviceManager

System API: This is a system API.

Parameters

Example

import { BusinessError } from '@ohos.base'

try {
  dmInstance.off('replyResult');
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("replyResult errCode:" + e.code + ",errMessage:" + e.message);
}

on('deviceStateChange')

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

Subscribes to device state changes.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import deviceManager from '@ohos.distributedDeviceManager'
import { BusinessError } from '@ohos.base'

class Data {
  action: deviceManager.DeviceStateChange = 0
  device: deviceManager.DeviceBasicInfo = {
    deviceId: "",
    deviceName: "",
    deviceType: "",
    networkId: "",
  }
}

try {
  dmInstance.on('deviceStateChange', (data: Data) => {
    console.info("deviceStateChange on:" + JSON.stringify(data));
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("deviceStateChange errCode:" + e.code + ",errMessage:" + e.message);
}

off('deviceStateChange')

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

Unsubscribes from the device state changes.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import deviceManager from '@ohos.distributedDeviceManager'
import { BusinessError } from '@ohos.base'

class Data {
  action: deviceManager.DeviceStateChange = 0
  device: deviceManager.DeviceBasicInfo = {
    deviceId: "",
    deviceName: "",
    deviceType: "",
    networkId: "",
  }
}

try {
  dmInstance.off('deviceStateChange', (data: Data) => {
    console.info('deviceStateChange' + JSON.stringify(data));
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("deviceStateChange errCode:" + e.code + ",errMessage:" + e.message);
}

on('discoverSuccess')

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

Subscribes to the 'discoverSuccess' event. The application will be notified when a device is successfully discovered.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import deviceManager from '@ohos.distributedDeviceManager'
import { BusinessError } from '@ohos.base'

class Data {
  device: deviceManager.DeviceBasicInfo = {
    deviceId: "",
    deviceName: "",
    deviceType: "",
    networkId: "",
  }
}

try {
  dmInstance.on('discoverSuccess', (data: Data) => {
    console.info("discoverSuccess:" + JSON.stringify(data));
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("discoverSuccess errCode:" + e.code + ",errMessage:" + e.message);
}

off('discoverSuccess')

off(type: 'discoverSuccess', callback?: Callback<{ device: DeviceBasicInfo }>): void;

Unsubscribes from the 'discoverSuccess' event.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import deviceManager from '@ohos.distributedDeviceManager'
import { BusinessError } from '@ohos.base'

class Data {
  device: deviceManager.DeviceBasicInfo = {
    deviceId: "",
    deviceName: "",
    deviceType: "",
    networkId: "",
  }
}

try {
  dmInstance.off('discoverSuccess', (data: Data) => {
    console.info('discoverSuccess' + JSON.stringify(data));
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("discoverSuccess errCode:" + e.code + ",errMessage:" + e.message);
}

on('deviceNameChange')

on(type: 'deviceNameChange', callback: Callback<{ deviceName: string }>): void;

Subscribes to device name changes.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import { BusinessError } from '@ohos.base'

class Data {
  deviceName: string = ""
}

try {
  dmInstance.on('deviceNameChange', (data: Data) => {
      console.info("deviceNameChange on:" + JSON.stringify(data));
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("deviceNameChange errCode:" + e.code + ",errMessage:" + e.message);
}

off('deviceNameChange')

off(type: 'deviceNameChange', callback?: Callback<{ deviceName: string }>): void;

Unsubscribes from the device name changes.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import { BusinessError } from '@ohos.base'

class Data {
  deviceName: string = ""
}

try {
  dmInstance.off('deviceNameChange', (data: Data) => {
    console.info('deviceNameChange' + JSON.stringify(data));
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("deviceNameChange errCode:" + e.code + ",errMessage:" + e.message);
}

on('discoverFailure')

on(type: 'discoverFailure', callback: Callback<{ reason: number }>): void;

Subscribes to the 'discoverFailure' event. The application will be notified when a device fails to be discovered.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import { BusinessError } from '@ohos.base'

class Data {
  reason: number = 0
}

try {
  dmInstance.on('discoverFailure', (data: Data) => {
      console.info("discoverFailure on:" + JSON.stringify(data));
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("discoverFailure errCode:" + e.code + ",errMessage:" + e.message);
}

off('discoverFailure')

off(type: 'discoverFailure', callback?: Callback<{ reason: number }>): void;

Unsubscribes from the 'discoverFailure' event.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import { BusinessError } from '@ohos.base'

class Data {
  reason: number = 0
}

try {
  dmInstance.off('discoverFailure', (data: Data) => {
    console.info('discoverFailure' + JSON.stringify(data));
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("discoverFailure errCode:" + e.code + ",errMessage:" + e.message);
}

on('serviceDie')

on(type: 'serviceDie', callback?: Callback<{}>): void;

Subscribes to dead events of the DeviceManager service.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import { BusinessError } from '@ohos.base'

try {
  dmInstance.on("serviceDie", () => {
    console.info("serviceDie on");
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("serviceDie errCode:" + e.code + ",errMessage:" + e.message);
}

off('serviceDie')

off(type: 'serviceDie', callback?: Callback<{}>): void;

Unsubscribes from dead events of the DeviceManager service.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

import { BusinessError } from '@ohos.base'

try {
  dmInstance.off("serviceDie", () => {
    console.info("serviceDie off");
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error("serviceDie errCode:" + e.code + ",errMessage:" + e.message);
}