1# 设备管理 2 3本模块提供分布式设备管理能力。 4 5系统应用可调用接口实现如下功能： 6 7- 注册和解除注册设备上下线变化监听 8- 发现周边不可信设备 9- 认证和取消认证设备 10- 查询可信设备列表 11- 查询本地设备信息，包括设备名称，设备类型和设备标识 12 13>  **说明：** 14> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> - 本模块接口为系统接口，三方应用不支持调用。 16 17 18## 导入模块 19 20``` 21import deviceManager from '@ohos.distributedHardware.deviceManager'; 22``` 23 24 25## deviceManager.createDeviceManager 26 27createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager>): void 28 29创建一个设备管理器实例。 30 31**系统能力**：SystemCapability.DistributedHardware.DeviceManager 32 33- 参数： 34 | 参数名 | 类型 | 必填 | 说明 | 35 | -------- | -------- | -------- | -------- | 36 | bundleName | string | 是 | 指示应用程序的包名。 | 37 | callback | AsyncCallback<[DeviceManager](#devicemanager)> | 是 | DeviceManager实例创建时调用的回调，返回设备管理器对象实例。 | 38 39- 示例： 40 ``` 41 deviceManager.createDeviceManager("ohos.samples.jshelloworld", (err, data) => { 42 if (err) { 43 console.info("createDeviceManager err:" + JSON.stringify(err)); 44 return; 45 } 46 console.info("createDeviceManager success"); 47 this.dmInstance = data; 48 }); 49 ``` 50 51## DeviceInfo 52 53设备信息。 54 55**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 56 57| 名称 | 类型 | 必填 | 描述 | 58| -------- | -------- | -------- | -------- | 59| deviceId | string | 是 | 设备的唯一标识。 | 60| deviceName | string | 是 | 设备名称。 | 61| deviceType | [DeviceType](#deviceType) | 是 | 设备类型。 | 62| networkId<sup>8+</sup> | string | 是 | 设备网络标识。 | 63 64 65## DeviceType 66 67表示设备类型的枚举类。 68 69**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 70 71| 名称 | 默认值 | 说明 | 72| -------- | -------- | -------- | 73| SPEAKER | 0x0A | 智能音箱 | 74| PHONE | 0x0E | 手机 | 75| TABLET | 0x11 | 平板 | 76| WEARABLE | 0x6D | 智能穿戴 | 77| TV | 0x9C | 智慧屏 | 78| CAR | 0x83 | 车 | 79| UNKNOWN_TYPE | 0 | 未知设备 | 80 81 82## DeviceStateChangeAction 83 84表示设备状态变化的枚举。 85 86**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 87 88| 名称 | 默认值 | 说明 | 89| -------- | -------- | -------- | 90| ONLINE | 0 | 设备上线。 | 91| READY | 1 | 设备就绪，设备信息同步已完成。 | 92| OFFLINE | 2 | 设备下线。 | 93| CHANGE | 3 | 设备信息更改。 | 94 95## SubscribeInfo 96 97发现信息。 98 99**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 100 101| 名称 | 类型 | 必填 | 描述 | 102| -------- | -------- | -------- | -------- | 103| subscribeId | number | 是 | 发现标识，用于标识不同的发现周期。 | 104| mode | [DiscoverMode ](#discoverMode) | 否 | 发现模式。 | 105| medium | [ExchangeMedium](#exchangeMedium) | 否 | 发现类型。 | 106| freq | [ExchangeFreq](#exchangeFreq) | 否 | 发现频率。 | 107| isSameAccount | boolean | 否 | 是否同账号。 | 108| isWakeRemote | boolean | 否 | 是否唤醒设备。 | 109| capability | [SubscribeCap](#subscribeCap) | 否 | 发现能力。 | 110 111 112## DiscoverMode 113 114表示发现模式的枚举。 115 116**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 117 118| 名称 | 默认值 | 说明 | 119| -------- | -------- | -------- | 120| DISCOVER_MODE_PASSIVE | 0x55 | 被动模式。 | 121| DISCOVER_MODE_ACTIVE | 0xAA | 主动模式。 | 122 123 124## ExchangeMedium 125 126表示发现类型的枚举。 127 128**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 129 130| 名称 | 默认值 | 说明 | 131| -------- | -------- | -------- | 132| AUTO | 0 | 自动发现类型。 | 133| BLE | 1 | 蓝牙发现类型。 | 134| COAP | 2 | WiFi发现类型。 | 135| USB | 3 | USB发现类型。 | 136 137## ExchangeFreq 138 139表示发现频率的枚举。 140 141**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 142 143| 名称 | 默认值 | 说明 | 144| -------- | -------- | -------- | 145| LOW | 0 | 低频率。 | 146| MID | 1 | 中频率。 | 147| HIGH | 2 | 高频率。 | 148| SUPER_HIGH | 3 | 超高频率。 | 149 150 151## SubscribeCap 152 153表示发现能力的枚举。 154 155**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 156 157| 名称 | 默认值 | 说明 | 158| -------- | -------- | -------- | 159| SUBSCRIBE_CAPABILITY_DDMP | 0 | DDMP能力，后续会被废弃。 | 160| SUBSCRIBE_CAPABILITY_OSD | 1 | OSD能力。 | 161 162 163## AuthParam 164 165认证参数。 166 167**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 168 169| 名称 | 类型 | 必填 | 描述 | 170| -------- | -------- | -------- | -------- | 171| authType | number | 是 | 认证类型。 | 172| extraInfo | {[key:string] : any} | 否 | 认证参数可扩展字段。 | 173 174## AuthInfo 175 176认证信息。 177 178**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 179 180| 名称 | 类型 | 必填 | 描述 | 181| -------- | -------- | -------- | -------- | 182| authType | number | 是 | 认证类型。 | 183| token | number | 是 | 认证Token。 | 184| extraInfo | {[key:string] : any} | 否 | 认证信息可扩展字段。 | 185 186 187## DeviceManager 188 189设备管理实例，用于获取可信设备和本地设备的相关信息。在调用DeviceManager的方法前，需要先通过createDeviceManager构建一个DeviceManager实例dmInstance。 190 191 192### release 193 194release(): void 195 196设备管理实例不再使用后，通过该方法释放DeviceManager实例。 197 198**系统能力**：SystemCapability.DistributedHardware.DeviceManager 199 200- 示例： 201 ```js 202 dmInstance.release(); 203 ``` 204 205 206### getTrustedDeviceListSync 207 208getTrustedDeviceListSync(): Array<DeviceInfo> 209 210同步获取所有可信设备列表。 211 212**系统能力**：SystemCapability.DistributedHardware.DeviceManager 213 214- 返回值： 215 | 名称 | 说明 | 216 | -------- | -------- | 217 | Array<[DeviceInfo](#deviceinfo)> | 返回可信设备列表。 | 218 219- 示例： 220 ```js 221 var deviceInfoList = dmInstance.getTrustedDeviceListSync(); 222 ``` 223 224 225### getTrustedDeviceList<sup>8+</sup> 226 227getTrustedDeviceList(callback:AsyncCallback<Array<DeviceInfo>>): void 228 229获取所有可信设备列表。使用callback异步回调。 230 231**系统能力**：SystemCapability.DistributedHardware.DeviceManager 232 233- 参数： 234 | 名称 | 参数类型 | 必填 | 说明 | 235 | -------- | -------- | -------- | -------- | 236 | callback | AsyncCallback<Array<[DeviceInfo](#deviceinfo)>> | 是 | 获取所有可信设备列表的回调，返回设备信息。 | 237 238- 示例： 239 ```js 240 dmInstance.getTrustedDeviceList((err, data) => { 241 console.log("getTrustedDeviceList err: " + JSON.stringify(err)); 242 console.log('get trusted device info: ' + JSON.stringify(data)); 243 } 244 ); 245 ``` 246 247### getTrustedDeviceList<sup>8+</sup> 248 249getTrustedDeviceList(): Promise<Array<DeviceInfo>> 250 251获取所有可信设备列表。使用Promise异步回调。 252 253**系统能力**：SystemCapability.DistributedHardware.DeviceManager 254 255- 返回值： 256 | 类型 | 说明 | 257 | -------- | -------- | 258 | Promise<Array<[DeviceInfo](#deviceinfo)>> | Promise实例，用于获取异步返回结果。 | 259 260- 示例： 261 ```js 262 dmInstance.getTrustedDeviceList().then((data) => { 263 console.log('get trusted device info: ' + JSON.stringify(data)); 264 }).catch((err) => { 265 console.log("getTrustedDeviceList err: " + JSON.stringify(err)); 266 }); 267 ``` 268 269### getLocalDeviceInfoSync<sup>8+</sup> 270 271getLocalDeviceInfoSync(): [DeviceInfo](#deviceinfo) 272 273同步获取本地设备信息。 274 275**系统能力**：SystemCapability.DistributedHardware.DeviceManager 276 277- 返回值： 278 | 名称 | 说明 | 279 | -------- | -------- | 280 | Array<[DeviceInfo](#deviceinfo)> | 返回可信设备列表。 | 281 282- 示例： 283 ```js 284 var deviceInfo = dmInstance.getLocalDeviceInfoSync(); 285 ``` 286 287 288### getLocalDeviceInfo<sup>8+</sup> 289 290getLocalDeviceInfo(callback:AsyncCallback<DeviceInfo>): void 291 292获取本地设备信息。使用callback异步回调。 293 294**系统能力**：SystemCapability.DistributedHardware.DeviceManager 295 296- 参数： 297 | 名称 | 参数类型 | 必填 | 说明 | 298 | -------- | -------- | -------- | -------- | 299 | callback | AsyncCallback<[DeviceInfo](#deviceinfo)> | 是 | 获取本地设备信息。 | 300 301- 示例： 302 ```js 303 dmInstance.getLocalDeviceInfo((err, data) => { 304 console.log("getLocalDeviceInfo err: " + JSON.stringify(err)); 305 console.log('get local device info: ' + JSON.stringify(data)); 306 } 307 ); 308 ``` 309 310### getLocalDeviceInfo<sup>8+</sup> 311 312getLocalDeviceInfo(): Promise<DeviceInfo> 313 314获取本地设备信息。使用Promise异步回调。 315 316**系统能力**：SystemCapability.DistributedHardware.DeviceManager 317 318- 返回值： 319 | 类型 | 说明 | 320 | -------- | -------- | 321 | Promise<[DeviceInfo](#deviceinfo)> | Promise实例，用于获取异步返回结果。 | 322 323- 示例： 324 ```js 325 dmInstance.getLocalDeviceInfo().then((data) => { 326 console.log('get local device info: ' + JSON.stringify(data)); 327 }).catch((err) => { 328 console.log("getLocalDeviceInfo err: " + JSON.stringify(err)); 329 }); 330 ``` 331 332### startDeviceDiscovery 333 334startDeviceDiscovery(subscribeInfo: SubscribeInfo): void 335 336发现周边设备。 337 338**系统能力**：SystemCapability.DistributedHardware.DeviceManager 339 340- 参数： 341 | 名称 | 参数类型 | 必填 | 说明 | 342 | -------- | -------- | -------- | -------- | 343 | subscribeInfo | [SubscribeInfo](#subscribeInfo) | 是 | 发现信息。 | 344 345- 示例： 346 ```js 347 //生成发现标识，随机数确保每次调用发现接口的标识不一致 348 var subscribeId = Math.floor(Math.random() * 10000 + 1000); 349 var subscribeInfo = { 350 "subscribeId": subscribeId, 351 "mode": 0xAA, //主动模式 352 "medium": 0, //自动发现类型，同时支持多种发现类型 353 "freq": 2, //高频率 354 "isSameAccount": false, 355 "isWakeRemote": false, 356 "capability": 1 357 }; 358 dmInstance.startDeviceDiscovery(subscribeInfo); //当有设备发现时，通过deviceFound回调通知给应用程序 359 ``` 360 361### stopDeviceDiscovery 362 363stopDeviceDiscovery(subscribeId: number): void 364 365停止发现周边设备。 366 367**系统能力**：SystemCapability.DistributedHardware.DeviceManager 368 369- 参数： 370 | 名称 | 参数类型 | 必填 | 说明 | 371 | -------- | -------- | -------- | -------- | 372 | subscribeId | number | 是 | 发现标识。 | 373 374- 示例： 375 ```js 376 //入参需要和startDeviceDiscovery接口传入的subscribeId配对使用 377 dmInstance.stopDeviceDiscovery(subscribeId); 378 ``` 379 380### authenticateDevice 381 382authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: AsyncCallback<{deviceId: string, pinToken ?: number}>): void 383 384认证设备。 385 386**系统能力**：SystemCapability.DistributedHardware.DeviceManager 387 388- 参数： 389 | 名称 | 参数类型 | 必填 | 说明 | 390 | -------- | -------- | -------- | -------- | 391 | deviceInfo | [DeviceInfo](#deviceInfo) | 是 | 设备信息。 | 392 | authParam | [AuthParam](#authParam) | 是 | 认证参数。 | 393 | callback | AsyncCallback<{ deviceId: string, pinToken ?: number }> | 是 | 认证结果回调。 | 394 395- 示例： 396 ```js 397 //认证的设备信息，可以从发现的结果中获取 398 var deviceInfo ={ 399 "deviceId": "XXXXXXXX", 400 "deviceName": "", 401 deviceType: 0x0E 402 }; 403 let authParam = { 404 "authType": 1, //认证类型： 1 - 无账号PIN码认证 405 "extraInfo": {} 406 } 407 dmInstance.authenticateDevice(deviceInfo, authParam, (err, data) => { 408 if (err) { 409 console.info(TAG + "authenticateDevice err:" + JSON.stringify(err)); 410 return; 411 } 412 console.info(TAG + "authenticateDevice result:" + JSON.stringify(data)); 413 token = data.pinToken; 414 }); 415 ``` 416 417### unAuthenticateDevice<sup>8+</sup> 418 419unAuthenticateDevice(deviceInfo: DeviceInfo): void 420 421解除认证设备。 422 423**系统能力**：SystemCapability.DistributedHardware.DeviceManager 424 425- 参数： 426 | 名称 | 参数类型 | 必填 | 说明 | 427 | -------- | -------- | -------- | -------- | 428 | deviceInfo | [DeviceInfo](#deviceInfo) | 是 | 设备信息。 | 429 430- 示例： 431 ```js 432 dmInstance.unAuthenticateDevice(deviceInfo); 433 ``` 434 435 436### verifyAuthInfo 437 438verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void 439 440验证认证信息。 441 442**系统能力**：SystemCapability.DistributedHardware.DeviceManager 443 444- 参数： 445 | 名称 | 参数类型 | 必填 | 说明 | 446 | -------- | -------- | -------- | -------- | 447 | authInfo | [AuthInfo](#authInfo) | 是 | 认证信息。 | 448 | authInfo | AsyncCallback<{ deviceId: string, level: number }> | 是 | 验证结果回调。 | 449 450- 示例： 451 ```js 452 let authInfo = { 453 "authType": 1, 454 "token": xxxxxx, 455 "extraInfo": {} 456 } 457 dmInstance.verifyAuthInfo(authInfo, (err, data) => { 458 if (err) { 459 console.info(TAG + "verifyAuthInfo err:" + JSON.stringify(err)); 460 return; 461 } 462 console.info(TAG + "verifyAuthInfo result:" + JSON.stringify(data)); 463 }); 464 ``` 465 466 467### on('deviceStateChange') 468 469on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void 470 471注册设备状态回调。 472 473**系统能力**：SystemCapability.DistributedHardware.DeviceManager 474 475- 参数： 476 | 名称 | 参数类型 | 必填 | 说明 | 477 | -------- | -------- | -------- | -------- | 478 | type | string | 是 | 注册设备状态回调，固定为deviceStateChange。 | 479 | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | 是 | 指示要注册的设备状态回调，返回设备状态和设备信息。 | 480 481- 示例： 482 ```js 483 dmInstance.on('deviceStateChange', (data) => { 484 console.info("deviceStateChange on:" + JSON.stringify(data)); 485 } 486 ); 487 ``` 488 489 490### off('deviceStateChange') 491 492off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void 493 494取消注册设备状态回调。 495 496**系统能力**：SystemCapability.DistributedHardware.DeviceManager 497 498- 参数： 499 | 名称 | 参数类型 | 必填 | 说明 | 500 | -------- | -------- | -------- | -------- | 501 | type | string | 是 | 根据应用程序的包名取消注册设备状态回调。 | 502 | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | 是 | 指示要取消注册的设备状态回调，返回设备状态和设备信息。 | 503 504- 示例： 505 ```js 506 dmInstance.off('deviceStateChange', (data) => { 507 console.info('deviceStateChange' + JSON.stringify(data)); 508 } 509 ); 510 ``` 511 512 513### on('deviceFound') 514 515on(type: 'deviceFound', callback: Callback<{ subscribeId: number, device: DeviceInfo }>): void 516 517注册发现设备回调监听。 518 519**系统能力**：SystemCapability.DistributedHardware.DeviceManager 520 521- 参数： 522 | 名称 | 参数类型 | 必填 | 说明 | 523 | -------- | -------- | -------- | -------- | 524 | type | string | 是 | 注册设备发现回调，以便在发现周边设备时通知应用程序。 | 525 | callback | Callback<{ subscribeId: number, device: DeviceInfo }> | 是 | 注册设备发现的回调方法。 | 526 527- 示例： 528 ```js 529 dmInstance.on('deviceFound', (data) => { 530 console.info("deviceFound:" + JSON.stringify(data)); 531 } 532 ); 533 ``` 534 535### off('deviceFound') 536 537off(type: 'deviceFound', callback?: Callback<{ subscribeId: number, device: DeviceInfo }>): void 538 539取消注册设备发现回调。 540 541**系统能力**：SystemCapability.DistributedHardware.DeviceManager 542 543- 参数： 544 | 名称 | 参数类型 | 必填 | 说明 | 545 | -------- | -------- | -------- | -------- | 546 | type | string | 是 | 取消注册设备发现回调。 | 547 | callback | Callback<{ subscribeId: number, device: DeviceInfo }> | 是 | 指示要取消注册的设备发现回调，返回设备状态和设备信息。 | 548 549- 示例： 550 ```js 551 dmInstance.off('deviceFound', (data) => { 552 console.info('deviceFound' + JSON.stringify(data)); 553 } 554 ); 555 ``` 556 557### on('discoverFail') 558 559on(type: 'discoverFail', callback: Callback<{ subscribeId: number, reason: number }>): void 560 561注册设备发现失败回调监听。 562 563**系统能力**：SystemCapability.DistributedHardware.DeviceManager 564 565- 参数： 566 | 名称 | 参数类型 | 必填 | 说明 | 567 | -------- | -------- | -------- | -------- | 568 | type | string | 是 | 注册设备发现失败回调，以便在发现周边设备失败时通知应用程序。 | 569 | callback | Callback<{ subscribeId: number, reason: number }> | 是 | 注册设备发现失败的回调方法。 | 570 571- 示例： 572 ```js 573 dmInstance.on('discoverFail', (data) => { 574 this.log("discoverFail on:" + JSON.stringify(data)); 575 } 576 ); 577 ``` 578 579### off('discoverFail') 580 581off(type: 'discoverFail', callback?: Callback<{ subscribeId: number, reason: number }>): void 582 583取消注册设备发现失败回调。 584 585**系统能力**：SystemCapability.DistributedHardware.DeviceManager 586 587- 参数： 588 | 名称 | 参数类型 | 必填 | 说明 | 589 | -------- | -------- | -------- | -------- | 590 | type | string | 是 | 取消注册设备发现失败回调。 | 591 | callback | Callback<{ subscribeId: number, reason: number }> | 是 | 指示要取消注册的设备发现失败回调。 | 592 593- 示例： 594 ```js 595 dmInstance.off('deviceFound', (data) => { 596 console.info('deviceFound' + JSON.stringify(data)); 597 } 598 ); 599 ``` 600 601 602### on('serviceDie') 603 604on(type: 'serviceDie', callback: () => void): void 605 606注册设备管理服务死亡监听。 607 608**系统能力**：SystemCapability.DistributedHardware.DeviceManager 609 610- 参数： 611 | 名称 | 参数类型 | 必填 | 说明 | 612 | -------- | -------- | -------- | -------- | 613 | type | string | 是 | 注册serviceDie回调，以便在devicemanager服务异常终止时通知应用程序。 | 614 | callback | () => void | 是 | 注册serviceDie的回调方法。 | 615 616- 示例： 617 ```js 618 dmInstance.on("serviceDie", () => { 619 console.info("serviceDie on"); 620 } 621 ); 622 ``` 623 624 625### off('serviceDie') 626 627off(type: 'serviceDie', callback?: () => void): void 628 629取消注册设备管理服务死亡监听。 630 631**系统能力**：SystemCapability.DistributedHardware.DeviceManager 632 633- 参数： 634 | 名称 | 参数类型 | 必填 | 说明 | 635 | -------- | -------- | -------- | -------- | 636 | type | string | 是 | 取消注册serviceDie回调，以便在devicemanager服务异常终止时通知应用程序。 | 637 | callback | () => void | 否 | 取消注册serviceDie的回调方法。 | 638 639- 示例： 640 ```js 641 dmInstance.off("serviceDie", () => { 642 console.info("serviceDie off"); 643 } 644 ); 645 ```
