1# **DeviceManager部件** 2 3## 简介 4 5DeviceManager组件在OpenHarmony上提供账号无关的分布式设备的认证组网能力，并为开发者提供了一套用于分布式设备间监听、发现和认证的接口。 6 7其组成及依赖如下所示： 8 9 10 11dsoftbus提供能力： 12 提供设备上下线通知及设备信息，设备认证通道和设备发现能力。 13deviceauth提供能力： 14 提供设备群组管理和群组认证能力。 15 16 17## 目录 18 19``` 20foundation/distributedhardware/distributedhardware_device_manager 21├── common # 公共能力头文件存放目录 22│ ├── include 23│ │ ├── dfx # dfx功能头文件存放目录 24│ │ └── ipc # ipc功能头文件存放目录 25│ │ ├── lite # small 26│ │ ├── model # ipc功能模块头文件存放目录 27│ │ └── standard # standard 28│ └── src 29│ ├── dfx # dfx功能实现相关代码 30│ └── ipc # ipc公共功能代码 31│ ├── lite # small 32│ └── standard # standard 33├── display # DM显示hap代码 34│ └── entry 35│ └── src 36│ └── main 37│ ├── js # DM PIN码显示ServiceExtensionAbility相关JS代码 38│ └── resources # DM PIN码显示ServiceExtensionAbility相关资源配置文件目录 39├── figures 40├── interfaces 41| ├── cj # 仓颉接口ffi层实现存放目录 42│ ├── inner_kits # 内部接口及实现存放目录 43│ │ └── native_cpp # 内部native接口及实现存放目录 44│ │ ├── include 45│ │ │ ├── ipc # ipc头文件存放目录 46│ │ │ │ ├── lite # small 47│ │ │ │ └── standard # standard 48│ │ │ └── notify # ipc回调通知头文件目录 49│ │ └── src 50│ │ ├── ipc # ipc功能代码 51│ │ │ ├── lite # small 52│ │ │ └── standard # standard 53│ │ └── notify # ipc回调通知功能代码 54│ └── kits # 外部接口及实现存放目录 55│ ├── js # 外部JS接口及实现存放目录 56│ │ ├── include # 外部JS接口及实现头文件存放目录 57│ │ └── src # 外部JS接口及实现代码 58| └── js4.0 # 从Openharmony 4.0.9.2版本开始新增外部JS接口及实现存放目录 59| ├── include # 新增外部JS接口及实现头文件存放目录 60| └── src # 新增外部JS接口及实现代码 61| 62├── sa_profile # SA进程配置相关文件存放目录 63├── services 64│ ├── implementation # devicemanagerservice服务实现核心代码 65│ │ ├── include 66│ │ │ ├── ability # 与PIN码显示ServiceExtensionAbility拉起管理相关头文件 67│ │ │ ├── adapter # DM适配扩展功能相关头文件 68│ │ │ ├── authentication # device_auth交互相关头文件 69│ │ │ ├── config # DM适配扩展相关配置功能头文件 70│ │ │ ├── credential # 凭据管理功能相关头文件 71│ │ │ ├── dependency # 外部依赖模块相关头文件 72│ │ │ │ ├── commonevent # 事件处理功能相关头文件 73│ │ │ │ ├── hichain # 与hichain功能交互相关头文件 74│ │ │ │ ├── mini # mini 75│ │ │ │ ├── multipleuser # 多用户功能相关头文件 76│ │ │ │ ├── softbus # 与软总线功能交互相关头文件 77│ │ │ │ └── timer # 定时器处理相关头文件 78│ │ │ ├── devicestate # 设备状态管理功能相关头文件 79│ │ │ ├── discovery # 设备发现功能相关头文件 80│ │ │ ├── dispath # L0上功能实现相关头文件 81│ │ │ └── publish # 设备主动发现功能相关头文件 82│ │ └── src 83│ │ ├── ability # 与PIN码显示ServiceExtensionAbility拉起管理相关功能代码 84│ │ ├── adapter # DM适配扩展功能代码 85│ │ ├── authentication # device_auth交互相关核心代码 86│ │ ├── config # DM适配扩展相关配置功能代码 87│ │ ├── credential # 凭据管理功能代码 88│ │ ├── dependency # 外部依赖模块功能代码 89│ │ │ ├── commonevent # 事件处理功能代码 90│ │ │ ├── hichain # 与hichain功能交互代码 91│ │ │ ├── mini # mini 92│ │ │ ├── multipleuser # 多用户功能代码 93│ │ │ ├── softbus # 与软总线功能交互代码 94│ │ │ └── timer # 定时器处理相关功能代码 95│ │ ├── devicestate # 设备状态管理功能代码 96│ │ ├── discovery # 设备发现功能代码 97│ │ ├── dispath # mini上功能实现代码 98│ │ └── publish # 设备主动发现功能 99│ └── service # devicemanagerservice服务实现核心代码 100│ ├── include 101│ │ ├── ipc # 进程间通信相关头文件 102│ │ │ ├── lite # small 103│ │ │ └── standard # standard 104│ │ └── softbus # 软总线相关头文件 105│ └── src 106│ ├── ipc # 进程间通信相关功能代码 107│ │ ├── lite # small 108│ │ └── standard # standard 109│ └── softbus # 通道建立功能核心代码 110└── utils # 公共能力头文件存放目录 111 ├── include 112 │ ├── fwkload # 拉起其他sa功能相关头文件 113 │ └── permission # 权限校验相关头文件存放目录 114 └── src 115 ├── fwkload # 拉起其他sa功能相关功能代码 116 └── permission # 权限校验相关功能代码 117``` 118 119## 约束 120 121- 开发语言：JS、C++ 122- 适用于Hi3516DV300单板等OpenHarmony设备 123 124 125## 废弃接口说明 126 127该部分接口暂时可继续使用，但是暂停维护，建议使用新接口进行开发。 128 129当前版本设备管理服务不具备权限管理的能力，接口中的system api仅供系统调用，后续版本会进行严格的权限管控。 130接口参见[**interface_sdk-js仓库的**](https://gitee.com/openharmony/interface_sdk-js/) *ohos.distributedHardware.deviceManager.d.ts* 131 132- 公共接口： 133 134 使用DeviceManager相关接口之前，需要通过createDeviceManager接口创建DeviceManager实例； 135 136 不使用DeviceManager接口的时候需要释放对应的DeviceManager实例。 137 138| 原型 | 描述 | 139| ------------------------------------------------------------ | ------------------------------- | 140| createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager>): void; | 以异步方法获取DeviceManager实例 | 141| release(): void; | 释放DeviceManager实例 | 142 143- 系统能力接口： 144 145 提供可信设备列表获取、可信设备状态监听、周边设备发现、设备认证等相关接口，该部分作为系统能力接口，仅供系统应用调用。 146 147 开始设备发现、停止发现设备接口要配对使用，使用同一个subscribeId。 148 149| 原型 | 描述 | 150| ------------------------------------------------------------ | -------------------- | 151| getTrustedDeviceListSync(): Array<DeviceInfo>; | 获取信任设备列表 | 152| getTrustedDeviceList(callback:AsyncCallback<Array<DeviceInfo>>): void; | 获取信任设备列表 | 153| getTrustedDeviceList(): Promise<Array<DeviceInfo>>; | 获取信任设备列表 | 154| getLocalDeviceInfoSync(): DeviceInfo; | 获取本地设备信息 | 155| getLocalDeviceInfo(callback:AsyncCallback<DeviceInfo>): void; | 获取本地设备信息 | 156| getLocalDeviceInfo(): Promise<DeviceInfo>; | 获取本地设备信息 | 157| on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void; | 设备状态变更回调 | 158| off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void; | 取消设备状态变更回调 | 159| on(type: 'serviceDie', callback: () => void): void; | 服务错误回调 | 160| off(type: 'serviceDie', callback?: () => void): void; | 取消服务错误回调 | 161| startDeviceDiscovery(subscribeInfo: SubscribeInfo): void; | 开始设备发现 | 162| stopDeviceDiscovery(subscribeId: number): void; | 停止发现设备 | 163| authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: AsyncCallback<{deviceId: string, pinToken ?: number}>): void; | 设备认证接口 | 164| unAuthenticateDevice(deviceInfo: DeviceInfo): void; | 解除认证设备 | 165| setUserOperation(operateAction: number, params: string): void; | 设置用户ui操作行为 | 166| verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void; | 设备认证信息校验 | 167| startDeviceDiscovery(subscribeInfo: SubscribeInfo, filterOptions?: string): void; | 发现周边设备 | 168| publishDeviceDiscovery(publishInfo: PublishInfo): void; | 发布设备发现 | 169| unPublishDeviceDiscovery(publishId: number): void; | 停止发布设备发现 | 170| on(type: 'deviceFound', callback: Callback<{ subscribeId: number, device: DeviceInfo }>): void; | 发现设备列表回调 | 171| off(type: 'deviceFound', callback?: Callback<{ subscribeId: number, device: DeviceInfo }>): void; | 取消发现设备列表回调 | 172| on(type: 'discoverFail', callback: Callback<{ subscribeId: number, reason: number }>): void; | 发现设备失败回调 | 173| off(type: 'discoverFail', callback?: Callback<{ subscribeId: number, reason: number }>): void; | 取消发现设备失败回调 | 174| on(type: 'publishSuccess', callback: Callback<{ publishId: number }>): void; | 发布设备成功回调 | 175| off(type: 'publishSuccess', callback?: Callback<{ publishId: number }>): void; | 取消发布设备成功回调 | 176| on(type: 'publishFail', callback: Callback<{ publishId: number, reason: number }>): void; | 发布设备失败回调 | 177| off(type: 'publishFail', callback?: Callback<{ publishId: number, reason: number }>): void; | 取消发布设备失败回调 | 178| on(type: 'uiStateChange', callback: Callback<{ param: string}>): void; | ui状态变更回调 | 179| off(type: 'uiStateChange', callback?: Callback<{ param: string}>): void; | 取消ui状态变更回调 | 180 181## 新增接口说明 182 183 从Openharmony 4.0.9.2版本开始，新增设备管理接口。 184 185接口参见[**interface_sdk-js仓库的**](https://gitee.com/openharmony/interface_sdk-js/) *ohos.distributedDeviceManager.d.ts* 186 187- 公共接口： 188 189 调用以下接口，需要申请ohos.permission.DISTRIBUTED_DATASYNC权限才能正常调用。 190 191 使用DeviceManager相关接口之前，需要通过createDeviceManager接口创建DeviceManager实例； 192 193 不使用DeviceManager接口的时候需要释放对应的DeviceManager实例。 194 195 提供可信设备列表获取、可信设备状态监听、周边设备发现、设备认证等相关接口，支持三方应用调用。 196 197| 原型 | 描述 | 198| ------------------------------------------------------------ | ------------------------------- | 199| createDeviceManager(bundleName: string): DeviceManager; | 创建一个设备管理实例。设备管理实例是分布式设备管理方法的调用入口。用于获取可信设备和本地设备的相关信息。 | 200| releaseDeviceManager(deviceManager: DeviceManager): void; | 设备管理实例不再使用后，通过该方法释放DeviceManager实例。 | 201| getAvailableDeviceListSync(): Array<DeviceBasicInfo>; | 同步获取所有可信设备列表。 | 202| getAvailableDeviceList(callback:AsyncCallback<Array<DeviceBasicInfo>>): void; | 获取所有可信设备列表。使用callback异步回调。 | 203| getAvailableDeviceList(): Promise<Array<DeviceBasicInfo>>; | 获取所有可信设备列表。使用Promise异步回调。 | 204| getLocalDeviceNetworkId(): string; | 获取本地设备网络标识。 | 205| getLocalDeviceName(): string; | 获取本地设备名称。 | 206| getLocalDeviceType(): number; | 获取本地设备类型。 | 207| getLocalDeviceId(): string; | 获取本地设备id。 | 208| getDeviceName(networkId: string): string; | 通过指定设备的网络标识获取该设备名称。 | 209| getDeviceType(networkId: string): number; | 通过指定设备的网络标识获取该设备类型。 | 210| startDiscovering(discoverParam: {[key: string]: Object} , filterOptions?: {[key: string]: Object} ): void; | 发现周边设备。发现状态持续两分钟，超过两分钟，会停止发现，最大发现数量99个。 | 211| stopDiscovering(): void; | 停止发现周边设备。 | 212| bindTarget(deviceId: string, bindParam: {[key: string]: Object} , callback: AsyncCallback<{deviceId: string}>): void; | 认证设备。 | 213| unbindTarget(deviceId: string): void; | 解除认证设备。 | 214| on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChange, device: DeviceBasicInfo }>): void; | 注册设备状态回调。 | 215| off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChange, device: DeviceBasicInfo }>): void; | 取消注册设备状态回调。 | 216| on(type: 'discoverSuccess', callback: Callback<{ device: DeviceBasicInfo }>): void; | 注册发现设备成功回调监听。 | 217| off(type: 'discoverSuccess', callback?: Callback<{ device: DeviceBasicInfo }>): void; | 取消注册设备发现成功回调。 | 218| on(type: 'deviceNameChange', callback: Callback<{ deviceName: string }>): void; | 注册设备名称变更回调监听。 | 219| off(type: 'deviceNameChange', callback?: Callback<{ deviceName: string }>): void; | 取消注册设备名称变更回调监听。 | 220| on(type: 'discoverFailure', callback: Callback<{ reason: number }>): void; | 注册设备发现失败回调监听。 | 221| off(type: 'discoverFailure', callback?: Callback<{ reason: number }>): void; | 取消注册设备发现失败回调。 | 222| on(type: 'serviceDie', callback?: Callback<{}>): void; | 注册设备管理服务死亡监听。 | 223| off(type: 'serviceDie', callback?: Callback<{}>): void; | 取消注册设备管理服务死亡监听。 | 224 225- 示例如下： 226 227```js 228try { 229 let dmClass = deviceManager.createDeviceManager("ohos.samples.jshelloworld"); 230} catch(err) { 231 console.error("createDeviceManager errCode:" + err.code + ",errMessage:" + err.message); 232} 233 234try { 235 // 注册设备管理服务死亡监听。 236 dmClass.on("serviceDie", () => { 237 console.info("serviceDie on"); 238 }); 239} catch (err) { 240 console.error("serviceDie errCode:" + err.code + ",errMessage:" + err.message); 241} 242 243try { 244 dmClass.on('deviceStateChange', (data) => { 245 console.info("deviceStateChange on:" + JSON.stringify(data)); 246 }); 247} catch (err) { 248 console.error("deviceStateChange errCode:" + err.code + ",errMessage:" + err.message); 249} 250 251// 同步获取所有可信设备列表。 252try { 253 let trustList = dmClass.getAvailableDeviceListSync(); 254 console.log("trustList:" + JSON.stringify(this.trustList)); 255} catch(err) { 256 console.log("getAvailableDeviceList failed: " + JSON.stringify(err)); 257} 258// 获取本地设备类型。 259var data = dmClass.getLocalDeviceType(); 260 261// 获取本地设备名称。 262var data = dmClass.getLocalDeviceName(); 263 264// 发现周边设备。 265try { 266 // 注册发现设备成功回调监听。 267 dmClass.on('discoverSuccess', (data) => { 268 if (data == null) { 269 console.log("discoverSuccess error data = null") 270 return; 271 } 272 console.info(TAG + "discoverSuccess:" + JSON.stringify(data)); 273 }); 274 // 注册设备发现失败回调监听。 275 dmClass.on('discoverFailure', (data) => { 276 console.info("discoverFailure on:" + JSON.stringify(data)); 277 }); 278 var discoverParam = { 279 'discoverTargetType': 1 280 }; 281 var filterOptions = { 282 'availableStatus': 1, 283 'discoverDistance': 50, 284 'authenticationStatus': 0, 285 'authorizationType': 0 286 }; 287 dmClass.startDiscovering(discoverParam, filterOptions); // 当有设备发现时，通过discoverSuccess回调通知给应用程序 288} catch (err) { 289 console.log("startDiscovering err:" + err.code + "," + err.message); 290} 291 292// 停止发现周边设备。 293try { 294 dmClass.stopDiscovering(); 295 // 取消注册设备发现成功回调。 296 dmClass.off('discoverSuccess'); 297 // 取消注册设备发现失败回调。 298 dmClass.off('discoverFailure'); 299} catch (err) { 300 console.log("err:" + err.code + "," + err.message); 301} 302 303// 设备认证 304var deviceId ="XXXXXXXX"; 305let bindParam = { 306 'bindType': 1,// 认证类型： 1 - 无帐号PIN码认证 307 'targetPkgName': 'xxxx', 308 'appName': 'xxxx', 309 'appOperation': 'xxxx', 310 'customDescription': 'xxxx' 311} 312try { 313 // 设备认证 314 dmClass.bindTarget(deviceId, bindParam, (err, data) => { 315 if (err) { 316 console.info(TAG + "bindTarget err:" + JSON.stringify(err)); 317 return; 318 } else { 319 console.info(TAG + "bindTarget result:" + JSON.stringify(data)); 320 let token = data.pinTone; 321 } 322 }); 323} catch (err) { 324 console.log("bindTarget err:" + err.code + "," + err.message); 325} 326// 设备取消认证 327try { 328 var deviceId = "xxxxxxxx"; 329 let result = dmClass.unbindTarget(deviceId); 330 console.log("unbindTarget last device: " + JSON.stringify(deviceId) + " and result = " 331 + result); 332 } catch (err) { 333 console.log("unbindTarget err:" + err.code + "," + err.message); 334} 335 336try { 337 // 取消注册设备管理服务死亡监听。 338 dmClass.off('serviceDie'); 339 // 取消注册设备状态回调。 340 dmClass.off('deviceStateChange', (data) => { 341 console.info('deviceStateChange' + JSON.stringify(data)); 342 }); 343 // 释放DeviceManager实例。 344 deviceManager.releaseDeviceManager(dmClass); 345} catch (err) { 346 console.log("err:" + err.code + "," + err.message); 347} 348``` 349 350- 系统接口： 351 352 该部分接口仅支持系统应用调用。 353 调用以下接口，需要申请ohos.permission.ACCESSS_SERVICE_DM权限才能正常调用。 354 355| 原型 | 描述 | 356| ------------------------------------------------------------ | -------------------- | 357| replyUiAction(action: number, actionResult: string): void; | 回复用户ui操作行为。此接口只能被devicemanager的PIN码hap使用。 | 358| on(type: 'replyResult', callback: Callback<{ param: string}>): void; | 回复UI操作结果回调。 | 359| off(type: 'replyResult', callback?: Callback<{ param: string}>): void; | 取消回复UI操作结果回调。 | 360 361- 示例如下： 362 363```js 364// 设置用户ui操作行为 365/* action = 0 - 允许授权 366 action = 1 - 取消授权 367 action = 2 - 授权框用户操作超时 368 action = 3 - 取消pin码框展示 369 action = 4 - 取消pin码输入框展示 370 action = 5 - pin码输入框确定操作 371*/ 372try { 373 let action = 0; 374 dmClass.replyUiAction(action, "extra") 375 dmClass.on('replyResult', (data) => { 376 console.log("replyResult executed, dialog closed" + JSON.stringify(data)) 377 var tmpStr = JSON.parse(data.param) 378 var isShow = tmpStr.verifyFailed 379 console.log("replyResult executed, dialog closed" + isShow) 380 }); 381} catch (err) { 382 console.log("err:" + err.code + "," + err.message); 383} 384 385``` 386 387详细接口说明请参考[**API文档**](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-distributedservice-kit/js-apis-distributedDeviceManager.md) 388 389## 系统弹框ServiceExtensionAbility 390 391当前版本只支持PIN码认证，需要提供PIN码认证的授权提示界面、PIN码显示界面、PIN码输入界面； 392 393当前，由于系统通过native层直接进行弹窗的能力尚不具备，这里使用ServiceExtensionAbility来进行对应界面的弹窗。 394 395该ServiceExtensionAbility为：DeviceManager_UI.hap，作为系统应用进行预置。 396 397- 编译运行： 398 399 将devicemanager/display工程导入DevEco Studio 2.2 Beta1，复制display目录下的@ohos.distributedHardware.deviceManager.d.ts文件到Sdk\js\2.2.0.1\api\common目录下，进行编译构建及运行调试. 400 401- 编译环境依赖：IDE 2.2 SDK6 402 403- DeviceManager_UI.hap包源码存放位置：[device_manager仓库](https://gitee.com/openharmony/distributedhardware_device_manager/tree/master/display) 404 405- UI显示： 406 407 DeviceManager作为认证被控端，授权提示界面、PIN码显示界面由DeviceManager_UI ServiceExtensionAbility默认进行显示； 408 409 DeviceManager作为认证发起端，PIN码输入界面可以选择由DeviceManager_UI ServiceExtensionAbility进行显示，还是由开发者自行显示。开发者如需自己定制PIN码输入界面，需要在authenticateDevice接口的认证参数AuthParam中，extraInfo属性里面指定displayOwner参数为1。 410 411## 相关仓 412**** 413 414[**interface_sdk-js**](https://gitee.com/openharmony/interface_sdk-js/) 415 416[**applications_hap**](https://gitee.com/openharmony/applications_hap) 417
