设备管理
本模块提供分布式设备管理能力。
系统应用可调用接口实现如下功能:
- 注册和解除注册设备上下线变化监听
- 发现周边不可信设备
- 认证和取消认证设备
- 查询可信设备列表
- 查询本地设备信息,包括设备名称,设备类型和设备标识
说明:
- 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
- 本模块接口为系统接口,三方应用不支持调用。
导入模块
import deviceManager from '@ohos.distributedHardware.deviceManager';
deviceManager.createDeviceManager
createDeviceManager(bundleName: string, callback: AsyncCallback): void
创建一个设备管理器实例。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
参数名 类型 必填 说明 bundleName string 是 指示应用程序的包名。 callback AsyncCallback<[DeviceManager]> 是 DeviceManager实例创建时调用的回调,返回设备管理器对象实例。 -
示例:
deviceManager.createDeviceManager("ohos.samples.jshelloworld", (err, data) => { if (err) { console.info("createDeviceManager err:" + JSON.stringify(err)); return; } console.info("createDeviceManager success"); this.dmInstance = data; });
DeviceInfo
设备信息。
系统能力:以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
deviceId | string | 是 | 设备的唯一标识。 |
deviceName | string | 是 | 设备名称。 |
deviceType | [DeviceType] | 是 | 设备类型。 |
networkId8+ | string | 是 | 设备网络标识。 |
DeviceType
表示设备类型的枚举类。
系统能力:以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
名称 | 默认值 | 说明 |
---|---|---|
SPEAKER | 0x0A | 智能音箱 |
PHONE | 0x0E | 手机 |
TABLET | 0x11 | 平板 |
WEARABLE | 0x6D | 智能穿戴 |
TV | 0x9C | 智慧屏 |
CAR | 0x83 | 车 |
UNKNOWN_TYPE | 0 | 未知设备 |
DeviceStateChangeAction
表示设备状态变化的枚举。
系统能力:以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
名称 | 默认值 | 说明 |
---|---|---|
ONLINE | 0 | 设备上线。 |
READY | 1 | 设备就绪,设备信息同步已完成。 |
OFFLINE | 2 | 设备下线。 |
CHANGE | 3 | 设备信息更改。 |
SubscribeInfo
发现信息。
系统能力:以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
subscribeId | number | 是 | 发现标识,用于标识不同的发现周期。 |
mode | [DiscoverMode] | 否 | 发现模式。 |
medium | [ExchangeMedium] | 否 | 发现类型。 |
freq | [ExchangeFreq] | 否 | 发现频率。 |
isSameAccount | boolean | 否 | 是否同账号。 |
isWakeRemote | boolean | 否 | 是否唤醒设备。 |
capability | [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
设备管理实例,用于获取可信设备和本地设备的相关信息。在调用DeviceManager的方法前,需要先通过createDeviceManager构建一个DeviceManager实例dmInstance。
release
release(): void
设备管理实例不再使用后,通过该方法释放DeviceManager实例。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
示例:
dmInstance.release();
getTrustedDeviceListSync
getTrustedDeviceListSync(): Array
同步获取所有可信设备列表。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
返回值:
名称 说明 Array<[DeviceInfo]> 返回可信设备列表。 -
示例:
var deviceInfoList = dmInstance.getTrustedDeviceListSync();
getTrustedDeviceList8+
getTrustedDeviceList(callback:AsyncCallback<Array>): void
获取所有可信设备列表。使用callback异步回调。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
名称 参数类型 必填 说明 callback AsyncCallback<Array<[DeviceInfo]>> 是 获取所有可信设备列表的回调,返回设备信息。 -
示例:
dmInstance.getTrustedDeviceList((err, data) => { console.log("getTrustedDeviceList err: " + JSON.stringify(err)); console.log('get trusted device info: ' + JSON.stringify(data)); } );
getTrustedDeviceList8+
getTrustedDeviceList(): Promise<Array>
获取所有可信设备列表。使用Promise异步回调。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
返回值:
类型 说明 Promise<Array<[DeviceInfo]>> Promise实例,用于获取异步返回结果。 -
示例:
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]
同步获取本地设备信息。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
返回值:
名称 说明 Array<[DeviceInfo]> 返回可信设备列表。 -
示例:
var deviceInfo = dmInstance.getLocalDeviceInfoSync();
getLocalDeviceInfo8+
getLocalDeviceInfo(callback:AsyncCallback): void
获取本地设备信息。使用callback异步回调。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
名称 参数类型 必填 说明 callback AsyncCallback<[DeviceInfo]> 是 获取本地设备信息。 -
示例:
dmInstance.getLocalDeviceInfo((err, data) => { console.log("getLocalDeviceInfo err: " + JSON.stringify(err)); console.log('get local device info: ' + JSON.stringify(data)); } );
getLocalDeviceInfo8+
getLocalDeviceInfo(): Promise
获取本地设备信息。使用Promise异步回调。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
返回值:
类型 说明 Promise<[DeviceInfo]> Promise实例,用于获取异步返回结果。 -
示例:
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] 是 发现信息。 -
示例:
//生成发现标识,随机数确保每次调用发现接口的标识不一致 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 是 发现标识。 -
示例:
//入参需要和startDeviceDiscovery接口传入的subscribeId配对使用 dmInstance.stopDeviceDiscovery(subscribeId);
authenticateDevice
authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: AsyncCallback<{deviceId: string, pinToken ?: number}>): void
认证设备。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
名称 参数类型 必填 说明 deviceInfo [DeviceInfo] 是 设备信息。 authParam [AuthParam] 是 认证参数。 callback AsyncCallback<{ deviceId: string, pinToken ?: number }> 是 认证结果回调。 -
示例:
//认证的设备信息,可以从发现的结果中获取 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] 是 设备信息。 -
示例:
dmInstance.unAuthenticateDevice(deviceInfo);
verifyAuthInfo
verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void
验证认证信息。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
名称 参数类型 必填 说明 authInfo [AuthInfo] 是 认证信息。 authInfo AsyncCallback<{ deviceId: string, level: number }> 是 验证结果回调。 -
示例:
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
注册设备状态回调。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
名称 参数类型 必填 说明 type string 是 注册设备状态回调,固定为deviceStateChange。 callback Callback<{ action: [DeviceStateChangeAction], device: [DeviceInfo] }> 是 指示要注册的设备状态回调,返回设备状态和设备信息。 -
示例:
dmInstance.on('deviceStateChange', (data) => { console.info("deviceStateChange on:" + JSON.stringify(data)); } );
off(‘deviceStateChange’)
off(type: ‘deviceStateChange’, callback?: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void
取消注册设备状态回调。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
名称 参数类型 必填 说明 type string 是 根据应用程序的包名取消注册设备状态回调。 callback Callback<{ action: [DeviceStateChangeAction], device: [DeviceInfo] }> 是 指示要取消注册的设备状态回调,返回设备状态和设备信息。 -
示例:
dmInstance.off('deviceStateChange', (data) => { console.info('deviceStateChange' + JSON.stringify(data)); } );
on(‘deviceFound’)
on(type: ‘deviceFound’, callback: Callback<{ subscribeId: number, device: DeviceInfo }>): void
注册发现设备回调监听。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
名称 参数类型 必填 说明 type string 是 注册设备发现回调,以便在发现周边设备时通知应用程序。 callback Callback<{ subscribeId: number, device: DeviceInfo }> 是 注册设备发现的回调方法。 -
示例:
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 }> 是 指示要取消注册的设备发现回调,返回设备状态和设备信息。 -
示例:
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 }> 是 注册设备发现失败的回调方法。 -
示例:
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 }> 是 指示要取消注册的设备发现失败回调。 -
示例:
dmInstance.off('deviceFound', (data) => { console.info('deviceFound' + JSON.stringify(data)); } );
on(‘serviceDie’)
on(type: ‘serviceDie’, callback: () => void): void
注册设备管理服务死亡监听。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
名称 参数类型 必填 说明 type string 是 注册serviceDie回调,以便在devicemanager服务异常终止时通知应用程序。 callback () => void 是 注册serviceDie的回调方法。 -
示例:
dmInstance.on("serviceDie", () => { console.info("serviceDie on"); } );
off(‘serviceDie’)
off(type: ‘serviceDie’, callback?: () => void): void
取消注册设备管理服务死亡监听。
系统能力:SystemCapability.DistributedHardware.DeviceManager
-
参数:
名称 参数类型 必填 说明 type string 是 取消注册serviceDie回调,以便在devicemanager服务异常终止时通知应用程序。 callback () => void 否 取消注册serviceDie的回调方法。
-
示例:
dmInstance.off("serviceDie", () => { console.info("serviceDie off"); } );