鸿蒙开发设备管理：【@ohos.distributedHardware.deviceManager (设备管理)】

设备管理

本模块提供分布式设备管理能力。

系统应用可调用接口实现如下功能：

注册和解除注册设备上下线变化监听
发现周边不可信设备
认证和取消认证设备
查询可信设备列表
查询本地设备信息，包括设备名称，设备类型和设备标识

说明：

本模块首批接口从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]> 返回可信设备列表。

名称	说明
Array<[DeviceInfo]>	返回可信设备列表。

示例：

var deviceInfoList = dmInstance.getTrustedDeviceListSync();

getTrustedDeviceList8+

getTrustedDeviceList(callback:AsyncCallback<Array>): void

获取所有可信设备列表。使用callback异步回调。

系统能力：SystemCapability.DistributedHardware.DeviceManager

参数：

名称参数类型必填说明

callback AsyncCallback<Array<[DeviceInfo]>> 是获取所有可信设备列表的回调，返回设备信息。

名称	参数类型	必填	说明
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实例，用于获取异步返回结果。

类型	说明
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]> 返回可信设备列表。

名称	说明
Array<[DeviceInfo]>	返回可信设备列表。

示例：

var deviceInfo = dmInstance.getLocalDeviceInfoSync();

getLocalDeviceInfo8+

getLocalDeviceInfo(callback:AsyncCallback): void

获取本地设备信息。使用callback异步回调。

系统能力：SystemCapability.DistributedHardware.DeviceManager

参数：

名称参数类型必填说明

callback AsyncCallback<[DeviceInfo]> 是获取本地设备信息。

名称	参数类型	必填	说明
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实例，用于获取异步返回结果。

类型	说明
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] 是发现信息。

名称	参数类型	必填	说明
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 是发现标识。

名称	参数类型	必填	说明
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 }> 是验证结果回调。

名称	参数类型	必填	说明
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");
  }
);