diff --git a/zh-cn/application-dev/reference/apis/js-apis-device-manager.md b/zh-cn/application-dev/reference/apis/js-apis-device-manager.md index 81ee3cf000b335650a2bf6457fad449c07c678aa..d8996763d77f94da07f1eee160bdfc39fa58da3d 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-device-manager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-device-manager.md @@ -1,5 +1,15 @@ # 设备管理 +本模块提供分布式设备管理能力。 + +系统应用可调用接口实现如下功能： + +- 注册和解除注册设备上下线变化监听 +- 发现周边不可信设备 +- 认证和取消认证设备 +- 查询可信设备列表 +- 查询本地设备信息，包括设备名称，设备类型和设备标识 + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > - 本模块接口为系统接口，三方应用不支持调用。 @@ -38,19 +48,18 @@ createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager }); ``` +## DeviceInfo -## DeviceStateChangeAction - -表示设备状态变化的枚举。 +设备信息。 **系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager -| 名称 | 默认值 | 说明 | -| -------- | -------- | -------- | -| ONLINE | 0 | 设备上线。 | -| READY | 1 | 设备就绪，设备信息同步已完成。 | -| OFFLINE | 2 | 设备下线。 | -| CHANGE | 3 | 设备信息更改。 | +| 名称 | 类型 | 必填 | 描述 | +| -------- | -------- | -------- | -------- | +| deviceId | string | 是 | 设备的唯一标识。 | +| deviceName | string | 是 | 设备名称。 | +| deviceType | [DeviceType](#deviceType) | 是 | 设备类型。 | +| networkId8+ | string | 是 | 设备网络标识。 | ## DeviceType @@ -70,17 +79,109 @@ createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager | UNKNOWN_TYPE | 0 | 未知设备 | -## DeviceInfo +## DeviceStateChangeAction -设备信息。 +表示设备状态变化的枚举。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| ONLINE | 0 | 设备上线。 | +| READY | 1 | 设备就绪，设备信息同步已完成。 | +| OFFLINE | 2 | 设备下线。 | +| CHANGE | 3 | 设备信息更改。 | + +## SubscribeInfo + +发现信息。 **系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager | 名称 | 类型 | 必填 | 描述 | | -------- | -------- | -------- | -------- | -| deviceId | number | 是 | 设备的唯一标识。 | -| deviceName | string | 是 | 设备名称。 | -| deviceType | number | 是 | 设备类型。 | +| subscribeId | number | 是 | 发现标识，用于标识不同的发现周期。 | +| mode | [DiscoverMode ](#discoverMode) | 否 | 发现模式。 | +| medium | [ExchangeMedium](#exchangeMedium) | 否 | 发现类型。 | +| freq | [ExchangeFreq](#exchangeFreq) | 否 | 发现频率。 | +| isSameAccount | boolean | 否 | 是否同账号。 | +| isWakeRemote | boolean | 否 | 是否唤醒设备。 | +| capability | [SubscribeCap](#subscribeCap) | 否 | 发现能力。 | + + +## DiscoverMode + +表示发现模式的枚举。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| DISCOVER_MODE_PASSIVE | 0x55 | 被动模式。 | +| DISCOVER_MODE_ACTIVE | 0xAA | 主动模式。 | + + +## ExchangeMedium + +表示发现类型的枚举。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| AUTO | 0 | 自动发现类型。 | +| BLE | 1 | 蓝牙发现类型。 | +| COAP | 2 | WiFi发现类型。 | +| USB | 3 | USB发现类型。 | + +## ExchangeFreq + +表示发现频率的枚举。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| LOW | 0 | 低频率。 | +| MID | 1 | 中频率。 | +| HIGH | 2 | 高频率。 | +| SUPER_HIGH | 3 | 超高频率。 | + + +## SubscribeCap + +表示发现能力的枚举。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| SUBSCRIBE_CAPABILITY_DDMP | 0 | DDMP能力，后续会被废弃。 | +| SUBSCRIBE_CAPABILITY_OSD | 1 | OSD能力。 | + + +## AuthParam + +认证参数。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager + +| 名称 | 类型 | 必填 | 描述 | +| -------- | -------- | -------- | -------- | +| authType | number | 是 | 认证类型。 | +| extraInfo | {[key:string] : any} | 否 | 认证参数可扩展字段。 | + +## AuthInfo + +认证信息。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager + +| 名称 | 类型 | 必填 | 描述 | +| -------- | -------- | -------- | -------- | +| authType | number | 是 | 认证类型。 | +| token | number | 是 | 认证Token。 | +| extraInfo | {[key:string] : any} | 否 | 认证信息可扩展字段。 | ## DeviceManager @@ -97,7 +198,7 @@ release(): void **系统能力**：SystemCapability.DistributedHardware.DeviceManager - 示例： - ``` + ```js dmInstance.release(); ``` @@ -116,11 +217,253 @@ getTrustedDeviceListSync(): Array<DeviceInfo> | Array<[DeviceInfo](#deviceinfo)> | 返回可信设备列表。 | - 示例： - ``` + ```js var deviceInfoList = dmInstance.getTrustedDeviceListSync(); ``` +### getTrustedDeviceList8+ + +getTrustedDeviceList(callback:AsyncCallback<Array<DeviceInfo>>): void + +获取所有可信设备列表。使用callback异步回调。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<Array<[DeviceInfo](#deviceinfo)>> | 是 | 获取所有可信设备列表的回调，返回设备信息。 | + +- 示例： + ```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>> + +获取所有可信设备列表。使用Promise异步回调。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<Array<[DeviceInfo](#deviceinfo)>> | Promise实例，用于获取异步返回结果。 | + +- 示例： + ```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) + +同步获取本地设备信息。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 返回值： + | 名称 | 说明 | + | -------- | -------- | + | Array<[DeviceInfo](#deviceinfo)> | 返回可信设备列表。 | + +- 示例： + ```js + var deviceInfo = dmInstance.getLocalDeviceInfoSync(); + ``` + + +### getLocalDeviceInfo8+ + +getLocalDeviceInfo(callback:AsyncCallback<DeviceInfo>): void + +获取本地设备信息。使用callback异步回调。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[DeviceInfo](#deviceinfo)> | 是 | 获取本地设备信息。 | + +- 示例： + ```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> + +获取本地设备信息。使用Promise异步回调。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<[DeviceInfo](#deviceinfo)> | Promise实例，用于获取异步返回结果。 | + +- 示例： + ```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 + +发现周边设备。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | subscribeInfo | [SubscribeInfo](#subscribeInfo) | 是 | 发现信息。 | + +- 示例： + ```js + //生成发现标识，随机数确保每次调用发现接口的标识不一致 + var subscribeId = Math.floor(Math.random() * 10000 + 1000); + var subscribeInfo = { + "subscribeId": subscribeId, + "mode": 0xAA, //主动模式 + "medium": 0, //自动发现类型，同时支持多种发现类型 + "freq": 2, //高频率 + "isSameAccount": false, + "isWakeRemote": false, + "capability": 1 + }; + dmInstance.startDeviceDiscovery(subscribeInfo); //当有设备发现时，通过deviceFound回调通知给应用程序 + ``` + +### stopDeviceDiscovery + +stopDeviceDiscovery(subscribeId: number): void + +停止发现周边设备。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | subscribeId | number | 是 | 发现标识。 | + +- 示例： + ```js + //入参需要和startDeviceDiscovery接口传入的subscribeId配对使用 + dmInstance.stopDeviceDiscovery(subscribeId); + ``` + +### authenticateDevice + +authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: AsyncCallback<{deviceId: string, pinToken ?: number}>): void + +认证设备。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | deviceInfo | [DeviceInfo](#deviceInfo) | 是 | 设备信息。 | + | authParam | [AuthParam](#authParam) | 是 | 认证参数。 | + | callback | AsyncCallback<{ deviceId: string, pinToken ?: number }> | 是 | 认证结果回调。 | + +- 示例： + ```js + //认证的设备信息，可以从发现的结果中获取 + var deviceInfo ={ + "deviceId": "XXXXXXXX", + "deviceName": "", + deviceType: 0x0E + }; + let authParam = { + "authType": 1, //认证类型： 1 - 无账号PIN码认证 + "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 + +解除认证设备。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | deviceInfo | [DeviceInfo](#deviceInfo) | 是 | 设备信息。 | + +- 示例： + ```js + dmInstance.unAuthenticateDevice(deviceInfo); + ``` + + +### verifyAuthInfo + +verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void + +验证认证信息。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | authInfo | [AuthInfo](#authInfo) | 是 | 认证信息。 | + | authInfo | AsyncCallback<{ deviceId: string, level: number }> | 是 | 验证结果回调。 | + +- 示例： + ```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 @@ -136,7 +479,7 @@ on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChange | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | 是 | 指示要注册的设备状态回调，返回设备状态和设备信息。 | - 示例： - ``` + ```js dmInstance.on('deviceStateChange', (data) => { console.info("deviceStateChange on:" + JSON.stringify(data)); } @@ -146,7 +489,7 @@ on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChange ### off('deviceStateChange') -off(type: 'deviceStateChange', callback?: Call back<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void +off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void 取消注册设备状态回调。 @@ -159,7 +502,7 @@ off(type: 'deviceStateChange', callback?: Call back<{ action: DeviceStateChan | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo)  }> | 是 | 指示要取消注册的设备状态回调，返回设备状态和设备信息。 | - 示例： - ``` + ```js dmInstance.off('deviceStateChange', (data) => { console.info('deviceStateChange' + JSON.stringify(data)); } @@ -167,6 +510,95 @@ off(type: 'deviceStateChange', callback?: Call back<{ action: DeviceStateChan ``` +### on('deviceFound') + +on(type: 'deviceFound', callback: Callback<{ subscribeId: number, device: DeviceInfo }>): void + +注册发现设备回调监听。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 注册设备发现回调，以便在发现周边设备时通知应用程序。 | + | callback | Callback<{ subscribeId: number, device: DeviceInfo }> | 是 | 注册设备发现的回调方法。 | + +- 示例： + ```js + dmInstance.on('deviceFound', (data) => { + console.info("deviceFound:" + JSON.stringify(data)); + } + ); + ``` + +### off('deviceFound') + +off(type: 'deviceFound', callback?: Callback<{ subscribeId: number, device: DeviceInfo }>): void + +取消注册设备发现回调。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取消注册设备发现回调。 | + | callback | Callback<{ subscribeId: number, device: DeviceInfo }> | 是 | 指示要取消注册的设备发现回调，返回设备状态和设备信息。 | + +- 示例： + ```js + dmInstance.off('deviceFound', (data) => { + console.info('deviceFound' + JSON.stringify(data)); + } + ); + ``` + +### on('discoverFail') + +on(type: 'discoverFail', callback: Callback<{ subscribeId: number, reason: number }>): void + +注册设备发现失败回调监听。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 注册设备发现失败回调，以便在发现周边设备失败时通知应用程序。 | + | callback | Callback<{ subscribeId: number, reason: number }> | 是 | 注册设备发现失败的回调方法。 | + +- 示例： + ```js + dmInstance.on('discoverFail', (data) => { + this.log("discoverFail on:" + JSON.stringify(data)); + } + ); + ``` + +### off('discoverFail') + +off(type: 'discoverFail', callback?: Callback<{ subscribeId: number, reason: number }>): void + +取消注册设备发现失败回调。 + +**系统能力**：SystemCapability.DistributedHardware.DeviceManager + +- 参数： + | 名称 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 取消注册设备发现失败回调。 | + | callback | Callback<{ subscribeId: number, reason: number }> | 是 | 指示要取消注册的设备发现失败回调。 | + +- 示例： + ```js + dmInstance.off('deviceFound', (data) => { + console.info('deviceFound' + JSON.stringify(data)); + } + ); + ``` + + ### on('serviceDie') on(type: 'serviceDie', callback: () => void): void @@ -182,7 +614,7 @@ on(type: 'serviceDie', callback: () => void): void | callback | () => void | 是 | 注册serviceDie的回调方法。 | - 示例： - ``` + ```js dmInstance.on("serviceDie", () => { console.info("serviceDie on"); } @@ -205,9 +637,9 @@ off(type: 'serviceDie', callback?: () => void): void | callback | () => void | 否 | 取消注册serviceDie的回调方法。 | - 示例： - ``` + ```js dmInstance.off("serviceDie", () => { console.info("serviceDie off"); } ); - ``` + ``` \ No newline at end of file