@ohos.distributedHardware.deviceManager (Device Management)

The deviceManager module provides APIs for distributed device management.

System applications can call the APIs to do the following:

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

NOTE

• The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• The APIs of this module are system APIs and cannot be called by third-party applications.

Modules to Import

import deviceManager from '@ohos.distributedHardware.deviceManager';

deviceManager.createDeviceManager

createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager>): void

Creates a DeviceManager instance.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

try {
  deviceManager.createDeviceManager("ohos.samples.jshelloworld", (err, data) => {
    if (err) { 
      console.error("createDeviceManager errCode:" + err.code + ",errMessage:" + err.message);
      return;
    }
    console.info("createDeviceManager success");
    let dmInstance = data;
  });
} catch(err) {
  console.error("createDeviceManager errCode:" + err.code + ",errMessage:" + err.message);
}

DeviceInfo

Defines device information.

System capability: SystemCapability.DistributedHardware.DeviceManager

DeviceType

Enumerates the device types.

System capability: SystemCapability.DistributedHardware.DeviceManager

DeviceStateChangeAction

Enumerates the device states.

System capability: SystemCapability.DistributedHardware.DeviceManager

SubscribeInfo

Defines subscription information.

System capability: SystemCapability.DistributedHardware.DeviceManager

DiscoverMode

Enumerates the device discovery modes.

System capability: SystemCapability.DistributedHardware.DeviceManager

ExchangeMedium

Enumerates the media used for device discovery.

System capability: SystemCapability.DistributedHardware.DeviceManager

ExchangeFreq

Enumerates the device discovery frequencies.

System capability: SystemCapability.DistributedHardware.DeviceManager

SubscribeCap

Enumerates the discovery capabilities.

System capability: SystemCapability.DistributedHardware.DeviceManager

AuthParam

Defines the authentication parameters.

System capability: SystemCapability.DistributedHardware.DeviceManager

AuthInfo

Defines authentication information.

System capability: SystemCapability.DistributedHardware.DeviceManager

PublishInfo⁹⁺

Defines published device information.

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.

release

release(): void

Releases this DeviceManager instance when it is no longer used.

System capability: SystemCapability.DistributedHardware.DeviceManager

Error codes

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

Example

try {
  dmInstance.release();
} catch (err) {
  console.error("release errCode:" + err.code + ",errMessage:" + err.message);
}

getTrustedDeviceListSync

getTrustedDeviceListSync(): Array<DeviceInfo>

Obtains all trusted devices synchronously.

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

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

Example

try {
  var deviceInfoList = dmInstance.getTrustedDeviceListSync();
} catch (err) {
  console.error("getTrustedDeviceListSync errCode:" + err.code + ",errMessage:" + err.message);
}

getTrustedDeviceList⁸⁺

getTrustedDeviceList(callback:AsyncCallback<Array<DeviceInfo>>): void

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

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

try {
  dmInstance.getTrustedDeviceList((err, data) => {
    if (err) {
      console.error("getTrustedDeviceList errCode:" + err.code + ",errMessage:" + err.message);
      return;
    }
    console.log('get trusted device info: ' + JSON.stringify(data));
  });
} catch (err) {
  console.error("getTrustedDeviceList errCode:" + err.code + ",errMessage:" + err.message);
}

getTrustedDeviceList⁸⁺

getTrustedDeviceList(): Promise<Array<DeviceInfo>>

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

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

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

Example

dmInstance.getTrustedDeviceList().then((data) => {
  console.log('get trusted device info: ' + JSON.stringify(data));
  }).catch((err) => {
    console.error("getTrustedDeviceList errCode:" + err.code + ",errMessage:" + err.message);
});

getLocalDeviceInfoSync⁸⁺

getLocalDeviceInfoSync(): DeviceInfo

Obtains local device information synchronously.

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

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

Example

try {
  var deviceInfo = dmInstance.getLocalDeviceInfoSync();
} catch (err) {
  console.error("getLocalDeviceInfoSync errCode:" + err.code + ",errMessage:" + err.message);
}

getLocalDeviceInfo⁸⁺

getLocalDeviceInfo(callback:AsyncCallback<DeviceInfo>): void

Obtains local device information. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

try {
  dmInstance.getLocalDeviceInfo((err, data) => {
  if (err) {
    console.error("getLocalDeviceInfo errCode:" + err.code + ",errMessage:" + err.message);
    return;
  }
    console.log('get local device info: ' + JSON.stringify(data));
  });
} catch (err) {
  console.error("getLocalDeviceInfo errCode:" + err.code + ",errMessage:" + err.message);
}

getLocalDeviceInfo⁸⁺

getLocalDeviceInfo(): Promise<DeviceInfo>

Obtains local device information. This API uses a promise to return the result.

System capability: SystemCapability.DistributedHardware.DeviceManager

Return value

Error codes

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

Example

dmInstance.getLocalDeviceInfo().then((data) => {
  console.log('get local device info: ' + JSON.stringify(data));
}).catch((err) => {
  console.error("getLocalDeviceInfo errCode:" + err.code + ",errMessage:" + err.message);
});

startDeviceDiscovery⁸⁺

startDeviceDiscovery(subscribeInfo: SubscribeInfo): void

Starts to discover peripheral devices.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

// Automatically generate a unique subscription ID.
var subscribeId = Math.floor(Math.random() * 10000 + 1000);
var subscribeInfo = {
    "subscribeId": subscribeId,
    "mode": 0xAA, // Active discovery
    "medium": 0, // Automatic. Multiple media can be used for device discovery.
    "freq": 2, // High frequency
    "isSameAccount": false,
    "isWakeRemote": false,
    "capability": 1
};
try {
  dmInstance.startDeviceDiscovery(subscribeInfo); // The deviceFound callback is invoked to notify the application when a device is discovered.
} catch (err) {
  console.error("startDeviceDiscovery errCode:" + err.code + ",errMessage:" + err.message);
}

startDeviceDiscovery⁹⁺

startDeviceDiscovery(subscribeInfo: SubscribeInfo, filterOptions?: string): void

Starts to discover peripheral devices and filters discovered devices.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

// Automatically generate a unique subscription ID.
var subscribeId = Math.floor(Math.random() * 10000 + 1000);
var subscribeInfo = {
    "subscribeId": subscribeId,
    "mode": 0xAA, // Active discovery
    "medium": 0, // Automatic. Multiple media can be used for device discovery.
    "freq": 2, // High frequency
    "isSameAccount": false,
    "isWakeRemote": false,
    "capability": 1
};
var filterOptions = {
  "filter_op": "OR", // Optional. The default value is OR.
  "filters": [
      {
          "type": "range",
          "value": 50 // Filter discovered devices based on the distance (in cm).
      }
  ]
};
try {
  dmInstance.startDeviceDiscovery(subscribeInfo, JSON.stringify(filterOptions)); // The deviceFound callback is invoked to notify the application when a device is discovered.
} catch (err) {
  console.error("startDeviceDiscovery errCode:" + err.code + ",errMessage:" + err.message);
}

stopDeviceDiscovery

stopDeviceDiscovery(subscribeId: number): void

Stops device discovery.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

try {
  // stopDeviceDiscovery and startDeviceDiscovery must be used in pairs, and the input parameter **subscribeId** passed in them must be the same.
  var subscribeId = 12345;
  dmInstance.stopDeviceDiscovery(subscribeId);
} catch (err) {
  console.error("stopDeviceDiscovery errCode:" + err.code + ",errMessage:" + err.message);
}

publishDeviceDiscovery⁹⁺

publishDeviceDiscovery(publishInfo: PublishInfo): void

Publishes device information for discovery purposes.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

// Automatically generate a unique subscription ID.
var publishId = Math.floor(Math.random() * 10000 + 1000);
var publishInfo = {
    "publishId": publishId,
    "mode": 0xAA, // Active discovery
    "freq": 2, // High frequency
    "ranging": true  // The device supports reporting the distance to the discovery initiator.
};
try {
  dmInstance.publishDeviceDiscovery(publishInfo); // A callback is invoked to notify the application when the device information is published.
} catch (err) {
  console.error("publishDeviceDiscovery errCode:" + err.code + ",errMessage:" + err.message);
}

unPublishDeviceDiscovery⁹⁺

unPublishDeviceDiscovery(publishId: number): void

Stops publishing device information.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

try {
  // unPublishDeviceDiscovery and publishDeviceDiscovery must be used in pairs, and the input parameter **publishId** passed in them must be the same.
  var publishId = 12345;
  dmInstance.unPublishDeviceDiscovery(publishId);
} catch (err) {
  console.error("unPublishDeviceDiscovery errCode:" + err.code + ",errMessage:" + err.message);
}

authenticateDevice

authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: AsyncCallback<{deviceId: string, pinToken ?: number}>): void

Authenticates a device.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

// Information about the device to authenticate. The information can be obtained from the device discovery result.
var deviceInfo ={
    "deviceId": "XXXXXXXX",
    "deviceName": "",
    "deviceType": 0x0E,
    "networkId" : "xxxxxxx",
    "range" : 0
};
let extraInfo = {
        'targetPkgName': 'ohos.samples.xxx',
        'appName': 'xxx',
        'appDescription': 'xxx',
        'business': '0'
}
let authParam = {
    'authType': 1, // Authentication type. The value 1 means no account PIN authentication.
    'extraInfo': extraInfo
}
try {
  dmInstance.authenticateDevice(deviceInfo, authParam, (err, data) => {
    if (err) {
        console.error("authenticateDevice errCode:" + err.code + ",errMessage:" + err.message);
        return;
    }
    console.info("authenticateDevice result:" + JSON.stringify(data));
    let token = data.pinToken;
  });
} catch (err) {
  console.error("authenticateDevice errCode:" + err.code + ",errMessage:" + err.message);
}

unAuthenticateDevice⁸⁺

unAuthenticateDevice(deviceInfo: DeviceInfo): void

Deauthenticates a device.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

try {
  var deviceInfo ={
    "deviceId": "XXXXXXXX",
    "deviceName": "",
    "deviceType": 0x0E,
    "networkId" : "xxxxxxx",
    "range" : 0
  };
  dmInstance.unAuthenticateDevice(deviceInfo);
} catch (err) {
  console.error("unAuthenticateDevice errCode:" + err.code + ",errMessage:" + err.message);
}

verifyAuthInfo

verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void

Verifies authentication information.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Error codes

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

Example

let authInfo = {
  "authType": 1,
  "token": 123456,
  "extraInfo": {}
}
try {
  dmInstance.verifyAuthInfo(authInfo, (err, data) => {
  if (err) {
      console.error("verifyAuthInfo errCode:" + err.code + ",errMessage:" + err.message);
      return;
  }
  console.info("verifyAuthInfo result:" + JSON.stringify(data));
  });
} catch (err) {
  console.error("verifyAuthInfo errCode:" + err.code + ",errMessage:" + err.message);
}

setUserOperation⁹⁺

setUserOperation(operateAction: number, params: string): void;

Sets a user operation.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

on('uiStateChange')⁹⁺

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

Subscribes to UI status changes.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

off('uiStateChange')⁹⁺

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

Unsubscribes from UI status changes.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

try {
  dmInstance.off('uiStateChange');
} catch (err) {
  console.error("uiStateChange errCode:" + err.code + ",errMessage:" + err.message);
}

on('deviceStateChange')

on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void

Subscribes to changes in the device state.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

off('deviceStateChange')

off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void

Unsubscribes from changes in the device state.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

on('deviceFound')

on(type: 'deviceFound', callback: Callback<{ subscribeId: number, device: DeviceInfo }>): void

Subscribes to device discovery events.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

off('deviceFound')

off(type: 'deviceFound', callback?: Callback<{ subscribeId: number, device: DeviceInfo }>): void

Unsubscribes from device discovery events.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

on('discoverFail')

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

Subscribes to device discovery failures.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

off('discoverFail')

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

Unsubscribes from device discovery failures.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

on('publishSuccess')⁹⁺

on(type: 'publishSuccess', callback: Callback<{ publishId: number }>): void

Subscribes to device information publication success events.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

off('publishSuccess')⁹⁺

off(type: 'publishSuccess', callback?: Callback<{ publishId: number }>): void

Unsubscribes from device information publication success events.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

on('publishFail')⁹⁺

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

Subscribes to device information publication failures.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

off('publishFail')⁹⁺

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

Unsubscribes from device information publication failures.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

on('serviceDie')

on(type: 'serviceDie', callback: () => void): void

Subscribes to dead events of the DeviceManager service.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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

off('serviceDie')

off(type: 'serviceDie', callback?: () => void): void

Unsubscribes from dead events of the DeviceManager service.

System capability: SystemCapability.DistributedHardware.DeviceManager

Parameters

Example

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