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.
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
Name | Type | Mandatory | Description |
---|---|---|---|
bundleName | string | Yes | Bundle name of an application. |
callback | AsyncCallback<DeviceManager> | Yes | Callback used to return the DeviceManager instance created. |
- Example
deviceManager.createDeviceManager("ohos.samples.jshelloworld", (err, data) => { if (err) { console.info("createDeviceManager err:" + JSON.stringify(err)); return; } console.info("createDeviceManager success"); let dmInstance = data; });
DeviceInfo
Defines device information.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Type | Mandatory | Description |
---|---|---|---|
deviceId | string | Yes | Unique identifier of a device. |
deviceName | string | Yes | Device name. |
deviceType | DeviceType | Yes | Device type. |
networkId8+ | string | Yes | Network ID of the device. |
DeviceType
Enumerates the device types.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Default Value | Description |
---|---|---|
SPEAKER | 0x0A | Smart speaker. |
PHONE | 0x0E | Phone. |
TABLET | 0x11 | Tablet. |
WEARABLE | 0x6D | Wearable. |
TV | 0x9C | Smart TV. |
CAR | 0x83 | Car. |
UNKNOWN_TYPE | 0 | Unknown device type. |
DeviceStateChangeAction
Enumerates the device states.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Default Value | Description |
---|---|---|
ONLINE | 0 | The device is online. |
READY | 1 | The device is ready, and the device information has been synchronized. |
OFFLINE | 2 | The device is offline. |
CHANGE | 3 | The device information is changed. |
SubscribeInfo
Defines subscription information.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Type | Mandatory | Description |
---|---|---|---|
subscribeId | number | Yes | Subscription ID, used to identify a device discovery period. |
mode | DiscoverMode | No | Device discovery mode. |
medium | ExchangeMedium | No | Medium used for device discovery. |
freq | ExchangeFreq | No | Frequency of device discovery. |
isSameAccount | boolean | No | Whether the same account is used on the discovered device. |
isWakeRemote | boolean | No | Whether to wake up the discovered device. |
capability | SubscribeCap | No | Discovery capability. |
DiscoverMode
Enumerates the device discovery modes.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Default Value | Description |
---|---|---|
DISCOVER_MODE_PASSIVE | 0x55 | Passive discovery. |
DISCOVER_MODE_ACTIVE | 0xAA | Active discovery. |
ExchangeMedium
Enumerates the media used for device discovery.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Default Value | Description |
---|---|---|
AUTO | 0 | Automatic. |
BLE | 1 | Bluetooth. |
COAP | 2 | Wi-Fi. |
USB | 3 | USB. |
ExchangeFreq
Enumerates the device discovery frequencies.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Default Value | Description |
---|---|---|
LOW | 0 | Low frequency. |
MID | 1 | Medium frequency. |
HIGH | 2 | High frequency. |
SUPER_HIGH | 3 | Ultra-high frequency. |
SubscribeCap
Enumerates the discovery capabilities.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Default Value | Description |
---|---|---|
SUBSCRIBE_CAPABILITY_DDMP | 0 | DDMP capability. This will be deprecated later. |
SUBSCRIBE_CAPABILITY_OSD | 1 | OSD capability. |
AuthParam
Defines the authentication parameters.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Type | Mandatory | Description |
---|---|---|---|
authType | number | Yes | Authentication type. |
extraInfo | {[key:string] : any} | No | Extended field. |
AuthInfo
Defines authentication information.
System capability: SystemCapability.DistributedHardware.DeviceManager
Name | Type | Mandatory | Description |
---|---|---|---|
authType | number | Yes | Authentication type. |
token | number | Yes | Authentication token. |
extraInfo | {[key:string] : any} | No | Extended field. |
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
- Example
dmInstance.release();
getTrustedDeviceListSync
getTrustedDeviceListSync(): Array<DeviceInfo>
Obtains all trusted devices synchronously.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Return value
Name | Description |
---|---|
Array<DeviceInfo> | List of trusted devices obtained. |
- Example
var deviceInfoList = dmInstance.getTrustedDeviceListSync();
getTrustedDeviceList8+
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
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<Array<DeviceInfo>> | Yes | Callback used to return the list of trusted devices. |
- Example
dmInstance.getTrustedDeviceList((err, data) => { console.log("getTrustedDeviceList err: " + JSON.stringify(err)); console.log('get trusted device info: ' + JSON.stringify(data)); } );
getTrustedDeviceList8+
getTrustedDeviceList(): Promise<Array<DeviceInfo>>
Obtains all trusted devices. This API uses a promise to return the result.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Return value
Type | Description |
---|---|
Promise<Array<DeviceInfo>> | Promise used to return the list of trusted devices. |
- Example
dmInstance.getTrustedDeviceList().then((data) => { console.log('get trusted device info: ' + JSON.stringify(data)); }).catch((err) => { console.log("getTrustedDeviceList err: " + JSON.stringify(err)); });
getLocalDeviceInfoSync8+
getLocalDeviceInfoSync(): DeviceInfo
Obtains local device information synchronously.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Return value
Name | Description |
---|---|
Array<DeviceInfo> | List of local devices obtained. |
- Example
var deviceInfo = dmInstance.getLocalDeviceInfoSync();
getLocalDeviceInfo8+
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
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<DeviceInfo> | Yes | Callback used to return the local device information. |
- Example
dmInstance.getLocalDeviceInfo((err, data) => { console.log("getLocalDeviceInfo err: " + JSON.stringify(err)); console.log('get local device info: ' + JSON.stringify(data)); } );
getLocalDeviceInfo8+
getLocalDeviceInfo(): Promise<DeviceInfo>
Obtains local device information. This API uses a promise to return the result.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Return value
Type | Description |
---|---|
Promise<DeviceInfo> | Promise used to return the local device information. |
- Example
dmInstance.getLocalDeviceInfo().then((data) => { console.log('get local device info: ' + JSON.stringify(data)); }).catch((err) => { console.log("getLocalDeviceInfo err: " + JSON.stringify(err)); });
startDeviceDiscovery
startDeviceDiscovery(subscribeInfo: SubscribeInfo): void
Starts to discover peripheral devices.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
subscribeInfo | SubscribeInfo | Yes | Subscription information. |
- 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 }; dmInstance.startDeviceDiscovery(subscribeInfo); // The deviceFound callback is invoked to notify the application when a device is discovered.
stopDeviceDiscovery
stopDeviceDiscovery(subscribeId: number): void
Stops device discovery.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
subscribeId | number | Yes | Subscription ID. |
- Example
// The subscribeId input must be the same as that automatically generated in startDeviceDiscovery. dmInstance.stopDeviceDiscovery(subscribeId);
authenticateDevice
authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: AsyncCallback<{deviceId: string, pinToken ?: number}>): void
Authenticates a device.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceInfo | DeviceInfo | Yes | Device information. |
authParam | AuthParam | Yes | Authentication parameter. |
callback | AsyncCallback<{ deviceId: string, pinToken ?: number }> | Yes | Callback used to return the authentication result. |
- Example
// Information about the device to authenticate. The information can be obtained from the device discovery result. var deviceInfo ={ "deviceId": "XXXXXXXX", "deviceName": "", deviceType: 0x0E }; let authParam = { "authType": 1, // Authentication type. The value 1 means no account PIN authentication. "extraInfo": {} } dmInstance.authenticateDevice(deviceInfo, authParam, (err, data) => { if (err) { console.info(TAG + "authenticateDevice err:" + JSON.stringify(err)); return; } console.info(TAG + "authenticateDevice result:" + JSON.stringify(data)); token = data.pinToken; });
unAuthenticateDevice8+
unAuthenticateDevice(deviceInfo: DeviceInfo): void
Deauthenticates a device.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceInfo | DeviceInfo | Yes | Device information. |
- Example
dmInstance.unAuthenticateDevice(deviceInfo);
verifyAuthInfo
verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void
Verifies authentication information.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
authInfo | AuthInfo | Yes | Authentication information. |
authInfo | AsyncCallback<{ deviceId: string, level: number }> | Yes | Callback used to return the verification result. |
- Example
let authInfo = { "authType": 1, "token": xxxxxx, "extraInfo": {} } dmInstance.verifyAuthInfo(authInfo, (err, data) => { if (err) { console.info(TAG + "verifyAuthInfo err:" + JSON.stringify(err)); return; } console.info(TAG + "verifyAuthInfo result:" + JSON.stringify(data)); });
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
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value 'deviceStateChange' indicates a device state change event. |
callback | Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }> | Yes | Callback invoked to return the device information and state. |
- Example
dmInstance.on('deviceStateChange', (data) => { console.info("deviceStateChange on:" + JSON.stringify(data)); } );
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
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value 'deviceStateChange' indicates a device state change event. |
callback | Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }> | Yes | Callback invoked to return the device information and state. |
- Example
dmInstance.off('deviceStateChange', (data) => { console.info('deviceStateChange' + JSON.stringify(data)); } );
on('deviceFound')
on(type: 'deviceFound', callback: Callback<{ subscribeId: number, device: DeviceInfo }>): void
Subscribes to device discovery events.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value 'deviceFound' indicates an event reported when a device is discovered. |
callback | Callback<{ subscribeId: number, device: DeviceInfo }> | Yes | Callback used for device discovery. |
- Example
dmInstance.on('deviceFound', (data) => { console.info("deviceFound:" + JSON.stringify(data)); } );
off('deviceFound')
off(type: 'deviceFound', callback?: Callback<{ subscribeId: number, device: DeviceInfo }>): void
Unsubscribes from device discovery events.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value 'deviceFound' indicates an event reported when a device is discovered. |
callback | Callback<{ subscribeId: number, device: DeviceInfo }> | Yes | Callback used for device discovery, which is invoked to return the device information and state. |
- Example
dmInstance.off('deviceFound', (data) => { console.info('deviceFound' + JSON.stringify(data)); } );
on('discoverFail')
on(type: 'discoverFail', callback: Callback<{ subscribeId: number, reason: number }>): void
Subscribes to device discovery failures.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The event 'discoverFail' indicates an event reported when device discovery fails. |
callback | Callback<{ subscribeId: number, reason: number }> | Yes | Callback used for the device discovery failure. |
- Example
dmInstance.on('discoverFail', (data) => { this.log("discoverFail on:" + JSON.stringify(data)); } );
off('discoverFail')
off(type: 'discoverFail', callback?: Callback<{ subscribeId: number, reason: number }>): void
Unsubscribes from device discovery failures.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The event 'discoverFail' indicates an event reported when device discovery fails. |
callback | Callback<{ subscribeId: number, reason: number }> | Yes | Callback used for the device discovery failure. |
- Example
dmInstance.off('deviceFound', (data) => { console.info('deviceFound' + JSON.stringify(data)); } );
on('serviceDie')
on(type: 'serviceDie', callback: () => void): void
Subscribes to dead events of the DeviceManager service.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value 'serviceDie' indicates an event reported when the DeviceManager service is terminated unexpectedly. |
callback | () => void | Yes | Callback invoked when a dead event of the DeviceManager service occurs. |
- Example
dmInstance.on("serviceDie", () => { console.info("serviceDie on"); } );
off('serviceDie')
off(type: 'serviceDie', callback?: () => void): void
Unsubscribes from dead events of the DeviceManager service.
System capability: SystemCapability.DistributedHardware.DeviceManager
- Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value 'serviceDie' indicates an event reported when the DeviceManager service is terminated unexpectedly. |
callback | () => void | No | Callback used to return the dead event of the DeviceManager service. |
- Example
dmInstance.off("serviceDie", () => { console.info("serviceDie off"); } );