diff --git a/en/application-dev/reference/apis/js-apis-device-manager.md b/en/application-dev/reference/apis/js-apis-device-manager.md index 93ab553ef10e531fea0b2d0871b65183d22bf6fa..8c27495f208ad620ed6e104fb19c958350805c1e 100644 --- a/en/application-dev/reference/apis/js-apis-device-manager.md +++ b/en/application-dev/reference/apis/js-apis-device-manager.md @@ -1,11 +1,22 @@ # Device Management -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +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: +## Modules to Import ``` import deviceManager from '@ohos.distributedHardware.deviceManager'; @@ -21,10 +32,10 @@ Creates a **DeviceManager** instance. **System capability**: SystemCapability.DistributedHardware.DeviceManager - **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | bundleName | string | Yes| Bundle name of the application.| - | callback | AsyncCallback<[DeviceManager](#devicemanager)> | Yes| Callback invoked to return the **DeviceManager** instance created.| + | Name | Type | Mandatory | Description | + | ---------- | ---------------------------------------- | ---- | ------------------------------------ | + | bundleName | string | Yes | Bundle name of an application. | + | callback | AsyncCallback<[DeviceManager](#devicemanager)> | Yes | Callback used to return the **DeviceManager** instance created.| - Example ``` @@ -34,10 +45,40 @@ Creates a **DeviceManager** instance. return; } console.info("createDeviceManager success"); - this.dmInstance = data; + 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](#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 @@ -45,42 +86,103 @@ 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.| +| 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 -## DeviceType +Defines subscription information. -Enumerates the device types. +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +| Name | Type | Mandatory | Description | +| ------------- | --------------------------------- | ---- | ----------------- | +| subscribeId | number | Yes | Subscription ID, used to identify a device discovery period.| +| mode | [DiscoverMode ](#discovermode) | No | Device discovery mode. | +| medium | [ExchangeMedium](#exchangemedium) | No | Medium used for device discovery. | +| freq | [ExchangeFreq](#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](#subscribecap) | No | Discovery capability. | + + +## DiscoverMode + +Enumerates the device discovery modes. **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.| +| Name | Default Value | Description | +| --------------------- | ---- | ----- | +| DISCOVER_MODE_PASSIVE | 0x55 | Passive discovery.| +| DISCOVER_MODE_ACTIVE | 0xAA | Active discovery.| -## DeviceInfo +## ExchangeMedium -Defines device information. +Enumerates the media used for device discovery. **System capability**: SystemCapability.DistributedHardware.DeviceManager -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| deviceId | number | Yes| Unique device identifier.| -| deviceName | string | Yes| Device name.| -| deviceType | number | Yes| Device type.| +| 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 @@ -92,12 +194,12 @@ Provides APIs to obtain information about trusted devices and local devices. Bef release(): void -Releases the **DeviceManager** instance that is no longer used. +Releases this **DeviceManager** instance when it is no longer used. **System capability**: SystemCapability.DistributedHardware.DeviceManager - Example - ``` + ```js dmInstance.release(); ``` @@ -111,16 +213,258 @@ Obtains all trusted devices synchronously. **System capability**: SystemCapability.DistributedHardware.DeviceManager - Return value - | Name| Description| - | -------- | -------- | + | Name | Description | + | -------------------------------------- | --------- | | Array<[DeviceInfo](#deviceinfo)> | List of trusted devices obtained.| - Example - ``` + ```js 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](#deviceinfo)>> | Yes | Callback used to return the list of trusted devices.| + +- Example + ```js + 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](#deviceinfo)>> | Promise used to return the list of trusted devices.| + +- Example + ```js + 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](#deviceinfo) + +Obtains local device information synchronously. + +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +- Return value + | Name | Description | + | -------------------------------------- | --------- | + | Array<[DeviceInfo](#deviceinfo)> | List of local devices obtained.| + +- Example + ```js + 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](#deviceinfo)> | Yes | Callback used to return the local device information.| + +- Example + ```js + 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](#deviceinfo)> | Promise used to return the local device information.| + +- Example + ```js + 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](#subscribeinfo) | Yes | Subscription information.| + +- Example + ```js + // 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 + ```js + // 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](#deviceinfo) | Yes | Device information. | + | authParam | [AuthParam](#authparam) | Yes | Authentication parameter. | + | callback | AsyncCallback<{ deviceId: string, pinToken ?: number }> | Yes | Callback used to return the authentication result.| + +- Example + ```js + // 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](#deviceinfo) | Yes | Device information.| + +- Example + ```js + 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](#authinfo) | Yes | Authentication information. | + | authInfo | AsyncCallback<{ deviceId: string, level: number }> | Yes | Callback used to return the verification result.| + +- Example + ```js + 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 @@ -130,13 +474,13 @@ Subscribes to changes in the device state. **System capability**: SystemCapability.DistributedHardware.DeviceManager - **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value is **deviceStateChange**, which indicates a device state change event.| - | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | Yes| Callback invoked to return the device information and state.| + | Name | Type | Mandatory | Description | + | -------- | ---------------------------------------- | ---- | ------------------------------ | + | type | string | Yes | Event type. The value **'deviceStateChange'** indicates a device state change event.| + | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | Yes | Callback invoked to return the device information and state. | - Example - ``` + ```js dmInstance.on('deviceStateChange', (data) => { console.info("deviceStateChange on:" + JSON.stringify(data)); } @@ -146,20 +490,20 @@ Subscribes to changes in the device state. ### off('deviceStateChange') -off(type: 'deviceStateChange', callback?: Call back<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void +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 an event of device state change.| - | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo)  }> | Yes| Callback invoked to return the device information and state.| + | Name | Type | Mandatory | Description | + | -------- | ---------------------------------------- | ---- | --------------------------- | + | type | string | Yes | Event type. The value **'deviceStateChange'** indicates a device state change event. | + | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | Yes | Callback invoked to return the device information and state.| - Example - ``` + ```js dmInstance.off('deviceStateChange', (data) => { console.info('deviceStateChange' + JSON.stringify(data)); } @@ -167,6 +511,95 @@ Unsubscribes from changes in the device state. ``` +### 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 + ```js + 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](#deviceinfo) }> | Yes | Callback used for device discovery, which is invoked to return the device information and state.| + +- Example + ```js + 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 + ```js + 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 + ```js + dmInstance.off('deviceFound', (data) => { + console.info('deviceFound' + JSON.stringify(data)); + } + ); + ``` + + ### on('serviceDie') on(type: 'serviceDie', callback: () => void): void @@ -176,13 +609,13 @@ 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.| + | 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 - ``` + ```js dmInstance.on("serviceDie", () => { console.info("serviceDie on"); } @@ -199,13 +632,13 @@ 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.| + | 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 - ``` + ```js dmInstance.off("serviceDie", () => { console.info("serviceDie off"); }