【鸿蒙next开发】分布式开发：@ohos.distributedDeviceManager (设备管理)
往期鸿蒙5.0全套实战文章必看：（文中附带鸿蒙5.0全栈学习资料）
-
鸿蒙开发核心知识点，看这篇文章就够了
-
最新版！鸿蒙HarmonyOS Next应用开发实战学习路线
-
鸿蒙HarmonyOS NEXT开发技术最全学习路线指南
-
鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）
@ohos.distributedDeviceManager (设备管理)
本模块提供分布式设备管理能力。
应用可调用接口实现如下功能：
- 注册和解除注册设备上下线变化监听。
- 发现周边不可信设备。
- 认证和取消认证设备。
- 查询可信设备列表。
- 查询本地设备信息，包括设备名称，设备类型和设备标识等。
说明
本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
导入模块
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';distributedDeviceManager.createDeviceManager
createDeviceManager(bundleName: string): DeviceManager;
创建一个设备管理实例。设备管理实例是分布式设备管理方法的调用入口。用于获取可信设备和本地设备的相关信息。
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
返回值：
错误码：
以下的错误码的详细介绍。
示例：
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';import { BusinessError } from \'@kit.BasicServicesKit\';try { let dmInstance = distributedDeviceManager.createDeviceManager(\'ohos.samples.jsHelloWorld\');} catch(err) { let e: BusinessError = err as BusinessError; console.error(\'createDeviceManager errCode:\' + e.code + \',errMessage:\' + e.message);}distributedDeviceManager.releaseDeviceManager
releaseDeviceManager(deviceManager: DeviceManager): void;
设备管理实例不再使用后，通过该方法释放DeviceManager实例。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';import { BusinessError } from \'@kit.BasicServicesKit\';try { let dmInstance = distributedDeviceManager.createDeviceManager(\'ohos.samples.jsHelloWorld\'); distributedDeviceManager.releaseDeviceManager(dmInstance);} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'release device manager errCode:\' + e.code + \',errMessage:\' + e.message);}DeviceBasicInfo
分布式设备基本信息。
系统能力：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
DeviceStateChange
表示设备状态。
系统能力：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
DeviceManager
设备管理实例，用于获取可信设备和本地设备的相关信息。在调用DeviceManager的方法前，需要先通过createDeviceManager构建一个DeviceManager实例dmInstance。
getAvailableDeviceListSync
getAvailableDeviceListSync(): Array;
同步获取所有可信设备列表。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
返回值：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';import { BusinessError } from \'@kit.BasicServicesKit\';try { let deviceInfoList: Array = dmInstance.getAvailableDeviceListSync();} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'getAvailableDeviceListSync errCode:\' + e.code + \',errMessage:\' + e.message);}getAvailableDeviceList
getAvailableDeviceList(callback:AsyncCallback<Array>): void;
获取所有可信设备列表。使用callback异步回调。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';import { BusinessError } from \'@kit.BasicServicesKit\';try { dmInstance.getAvailableDeviceList((err: BusinessError, data: Array) => { if (err) { console.error(\'getAvailableDeviceList errCode:\' + err.code + \',errMessage:\' + err.message); return; } console.log(\'get available device info: \' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'getAvailableDeviceList errCode:\' + e.code + \',errMessage:\' + e.message);}getAvailableDeviceList
getAvailableDeviceList(): Promise<Array>;
获取所有可信设备列表。使用Promise异步回调。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
返回值：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';import { BusinessError } from \'@kit.BasicServicesKit\';dmInstance.getAvailableDeviceList().then((data: Array) => { console.log(\'get available device info: \' + JSON.stringify(data)); }).catch((err: BusinessError) => { console.error(\'getAvailableDeviceList errCode:\' + err.code + \',errMessage:\' + err.message);});getLocalDeviceNetworkId
getLocalDeviceNetworkId(): string;
获取本地设备网络标识。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
返回值：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { let deviceNetworkId: string = dmInstance.getLocalDeviceNetworkId(); console.log(\'local device networkId: \' + JSON.stringify(deviceNetworkId));} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'getLocalDeviceNetworkId errCode:\' + e.code + \',errMessage:\' + e.message);}getLocalDeviceName
getLocalDeviceName(): string;
获取本地设备名称。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
返回值：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { let deviceName: string = dmInstance.getLocalDeviceName(); console.log(\'local device name: \' + JSON.stringify(deviceName));} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'getLocalDeviceName errCode:\' + e.code + \',errMessage:\' + e.message);}getLocalDeviceType
getLocalDeviceType(): number;
获取本地设备类型。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
返回值：
返回本地设备类型。目前仅支持以下设备类型：
-0: UNKNOWN。
-14: PHONE。
-17: TABLET。
-156: TV。
-131: CAR。
-109: WATCH。
-8: WiFiCamera。
-2562: SMART_DISPLAY。
-2607: 2in1。
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { let deviceType: number = dmInstance.getLocalDeviceType(); console.log(\'local device type: \' + JSON.stringify(deviceType));} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'getLocalDeviceType errCode:\' + e.code + \',errMessage:\' + e.message);}getLocalDeviceId
getLocalDeviceId(): string;
获取本地设备id，实际值为udid-hash与appid和盐值基于sha256方式进行混淆后的值。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
返回值：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { let deviceId: string = dmInstance.getLocalDeviceId(); console.log(\'local device id: \' + JSON.stringify(deviceId));} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'getLocalDeviceId errCode:\' + e.code + \',errMessage:\' + e.message);}getDeviceName
getDeviceName(networkId: string): string;
通过指定设备的网络标识获取该设备名称。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
返回值：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { // 设备网络标识，可以从可信设备列表中获取 let networkId = \'xxxxxxx\'; let deviceName: string = dmInstance.getDeviceName(networkId); console.log(\'device name: \' + JSON.stringify(deviceName)); } catch (err) { let e: BusinessError = err as BusinessError; console.error(\'getDeviceName errCode:\' + e.code + \',errMessage:\' + e.message);}getDeviceType
getDeviceType(networkId: string): number;
通过指定设备的网络标识获取该设备类型。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
返回值：
返回指定设备类型。目前仅支持以下设备类型：
-0: UNKNOWN。
-14: PHONE。
-17: TABLET。
-156: TV。
-131: CAR。
-109: WATCH。
-8: WiFiCamera。
-2562: SMART_DISPLAY。
-2607: 2in1。
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { // 设备网络标识，可以从可信设备列表中获取 let networkId = \'xxxxxxx\'; let deviceType: number = dmInstance.getDeviceType(networkId); console.log(\'device type: \' + JSON.stringify(deviceType)); } catch (err) { let e: BusinessError = err as BusinessError; console.error(\'getDeviceType errCode:\' + e.code + \',errMessage:\' + e.message);}startDiscovering
startDiscovering(discoverParam: {[key: string]: Object;} , filterOptions?: {[key: string]: Object;} ): void;
发现周边设备。发现状态持续两分钟，超过两分钟，会停止发现，最大发现数量99个。wifi场景要求同局域网。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
发现标识。 标识发现的目标类型。
discoverTargetType: 发现目标默认为设备，值为1。
发现设备过滤信息。可选，默认为undefined，发现未上线设备。会携带以下key值：
availableStatus(0-1)：仅发现设备可信，值为0表示设备不可信。
-0：设备离线，客户端需要通过调用bindTarget绑定设备。
-1：设备已在线，客户可以进行连接。
discoverDistance(0-100)：发现距离本地一定距离内的设备，单位为cm。wifi场景不传该参数。
authenticationStatus(0-1)：根据不同的认证状态发现设备：
-0：设备未认证。
-1：设备已认证。
authorizationType(0-2)：根据不同的授权类型发现设备：
-0：根据临时协商的会话密钥认证的设备。
-1：基于同账号密钥进行身份验证的设备。
-2：基于不同账号凭据密钥认证的设备。
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';interface DiscoverParam { discoverTargetType: number;}interface FilterOptions { availableStatus: number; discoverDistance: number; authenticationStatus: number; authorizationType: number;}let discoverParam: Record = { \'discoverTargetType\': 1};let filterOptions: Record = { \'availableStatus\': 0};try { dmInstance.startDiscovering(discoverParam, filterOptions); // 当有设备发现时，通过discoverSuccess回调通知给应用程序} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'startDiscovering errCode:\' + e.code + \',errMessage:\' + e.message);}stopDiscovering
stopDiscovering(): void;
停止发现周边设备。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { dmInstance.stopDiscovering();} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'stopDiscovering errCode:\' + e.code + \',errMessage:\' + e.message);}bindTarget
bindTarget(deviceId: string, bindParam: {[key: string]: Object;} , callback: AsyncCallback): void;
认证设备。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
认证参数。由开发者自行决定传入的键值对。默认会携带以下key值：
bindType 此值是绑定的类型，必填。
-1：PIN码。
targetPkgName 绑定目标的包名。
appName 尝试绑定目标的应用程序名称。
appOperation 应用程序要绑定目标的原因。
customDescription 操作的详细说明。
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';class Data { deviceId: string = \'\';}// 认证的设备信息，可以从发现的结果中获取let deviceId = \'XXXXXXXX\';let bindParam: Record = { \'bindType\': 1, // 认证类型： 1 - 无账号PIN码认证 \'targetPkgName\': \'xxxx\', \'appName\': \'xxxx\', \'appOperation\': \'xxxx\', \'customDescription\': \'xxxx\'};try { dmInstance.bindTarget(deviceId, bindParam, (err: BusinessError, data: Data) => { if (err) { console.error(\'bindTarget errCode:\' + err.code + \',errMessage:\' + err.message); return; } console.info(\'bindTarget result:\' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'bindTarget errCode:\' + e.code + \',errMessage:\' + e.message);}unbindTarget
unbindTarget(deviceId: string): void;
解除认证设备。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { let deviceId = \'XXXXXXXX\'; dmInstance.unbindTarget(deviceId);} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'unbindTarget errCode:\' + e.code + \',errMessage:\' + e.message);}on(\'deviceStateChange\')
on(type: \'deviceStateChange\', callback: Callback): void;
注册设备状态回调，以便在设备状态发生变化时根据应用捆绑包名通知应用。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';import { BusinessError } from \'@kit.BasicServicesKit\';class Data { action: distributedDeviceManager.DeviceStateChange = 0; device: distributedDeviceManager.DeviceBasicInfo = { deviceId: \'\', deviceName: \'\', deviceType: \'\', networkId: \'\' };}try { dmInstance.on(\'deviceStateChange\', (data: Data) => { console.info(\'deviceStateChange on:\' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'deviceStateChange errCode:\' + e.code + \',errMessage:\' + e.message);}off(\'deviceStateChange\')
off(type: \'deviceStateChange\', callback?: Callback): void;
取消注册设备状态回调。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';import { BusinessError } from \'@kit.BasicServicesKit\';class Data { action: distributedDeviceManager.DeviceStateChange = 0; device: distributedDeviceManager.DeviceBasicInfo = { deviceId: \'\', deviceName: \'\', deviceType: \'\', networkId: \'\' };}try { dmInstance.off(\'deviceStateChange\', (data: Data) => { console.info(\'deviceStateChange\' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'deviceStateChange errCode:\' + e.code + \',errMessage:\' + e.message);}on(\'discoverSuccess\')
on(type: \'discoverSuccess\', callback: Callback): void;
注册发现设备成功回调监听。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';import { BusinessError } from \'@kit.BasicServicesKit\';class Data { device: distributedDeviceManager.DeviceBasicInfo = { deviceId: \'\', deviceName: \'\', deviceType: \'\', networkId: \'\' };}try { dmInstance.on(\'discoverSuccess\', (data: Data) => { console.info(\'discoverSuccess:\' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'discoverSuccess errCode:\' + e.code + \',errMessage:\' + e.message);}off(\'discoverSuccess\')
off(type: \'discoverSuccess\', callback?: Callback): void;
取消注册设备发现成功回调。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
import { distributedDeviceManager } from \'@kit.DistributedServiceKit\';import { BusinessError } from \'@kit.BasicServicesKit\';class Data { device: distributedDeviceManager.DeviceBasicInfo = { deviceId: \'\', deviceName: \'\', deviceType: \'\', networkId: \'\' };}try { dmInstance.off(\'discoverSuccess\', (data: Data) => { console.info(\'discoverSuccess\' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'discoverSuccess errCode:\' + e.code + \',errMessage:\' + e.message);}on(\'deviceNameChange\')
on(type: \'deviceNameChange\', callback: Callback): void;
注册设备名称变更回调，以便在设备名称改变时通知应用程序。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';class Data { deviceName: string = \'\';}try { dmInstance.on(\'deviceNameChange\', (data: Data) => { console.info(\'deviceNameChange on:\' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'deviceNameChange errCode:\' + e.code + \',errMessage:\' + e.message);}off(\'deviceNameChange\')
off(type: \'deviceNameChange\', callback?: Callback): void;
取消注册设备名称变更回调监听。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';class Data { deviceName: string = \'\';}try { dmInstance.off(\'deviceNameChange\', (data: Data) => { console.info(\'deviceNameChange\' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'deviceNameChange errCode:\' + e.code + \',errMessage:\' + e.message);}on(\'discoverFailure\')
on(type: \'discoverFailure\', callback: Callback): void;
注册设备发现失败回调监听。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';class Data { reason: number = 0;}try { dmInstance.on(\'discoverFailure\', (data: Data) => { console.info(\'discoverFailure on:\' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'discoverFailure errCode:\' + e.code + \',errMessage:\' + e.message);}off(\'discoverFailure\')
off(type: \'discoverFailure\', callback?: Callback): void;
取消注册设备发现失败回调。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';class Data { reason: number = 0;}try { dmInstance.off(\'discoverFailure\', (data: Data) => { console.info(\'discoverFailure\' + JSON.stringify(data)); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'discoverFailure errCode:\' + e.code + \',errMessage:\' + e.message);}on(\'serviceDie\')
on(type: \'serviceDie\', callback?: Callback): void;
注册设备管理服务死亡回调，以便在服务死亡时通知应用程序。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { dmInstance.on(\'serviceDie\', () => { console.info(\'serviceDie on\'); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'serviceDie errCode:\' + e.code + \',errMessage:\' + e.message);}off(\'serviceDie\')
off(type: \'serviceDie\', callback?: Callback): void;
取消注册设备管理服务死亡回调。
需要权限：ohos.permission.DISTRIBUTED_DATASYNC
系统能力：SystemCapability.DistributedHardware.DeviceManager
参数：
错误码：
以下的错误码的详细介绍。
示例：
示例中dmInstance的初始化请参见创建一个设备管理实例。
import { BusinessError } from \'@kit.BasicServicesKit\';try { dmInstance.off(\'serviceDie\', () => { console.info(\'serviceDie off\'); });} catch (err) { let e: BusinessError = err as BusinessError; console.error(\'serviceDie errCode:\' + e.code + \',errMessage:\' + e.message);}
