1# @ohos.distributedDeviceManager (设备管理) 2 3本模块提供分布式设备管理能力。 4 5应用可调用接口实现如下功能： 6 7- 注册和解除注册设备上下线变化监听 8- 发现周边不可信设备 9- 认证和取消认证设备 10- 查询可信设备列表 11- 查询本地设备信息，包括设备名称，设备类型和设备标识等。 12 13 14> **说明：** 15> 16> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 17 18 19## 导入模块 20 21```ts 22import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 23``` 24 25 26## distributedDeviceManager.createDeviceManager 27 28createDeviceManager(bundleName: string): DeviceManager; 29 30创建一个设备管理实例。设备管理实例是分布式设备管理方法的调用入口。用于获取可信设备和本地设备的相关信息。 31 32**系统能力**：SystemCapability.DistributedHardware.DeviceManager 33 34**参数：** 35 36| 参数名 | 类型 | 必填 | 说明 | 37| ---------- | ---------------------------------------------------- | ---- | ----------------------------------------------------------- | 38| bundleName | string | 是 | 指示应用程序的Bundle名称。 | 39 40**返回值：** 41 42 | 类型 | 说明 | 43 | ------------------------------------------- | --------- | 44 | [DeviceManager](#devicemanager) | 返回设备管理器对象实例。 | 45 46**错误码：** 47 48以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 49 50| 错误码ID | 错误信息 | 51| -------- | --------------------------------------------------------------- | 52| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed. | 53 54**示例：** 55 56 ```ts 57 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 58 import { BusinessError } from '@kit.BasicServicesKit'; 59 60 try { 61 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 62 } catch(err) { 63 let e: BusinessError = err as BusinessError; 64 console.error('createDeviceManager errCode:' + e.code + ',errMessage:' + e.message); 65 } 66 ``` 67 68## distributedDeviceManager.releaseDeviceManager 69 70releaseDeviceManager(deviceManager: DeviceManager): void; 71 72设备管理实例不再使用后，通过该方法释放DeviceManager实例。 73 74**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 75 76**系统能力**：SystemCapability.DistributedHardware.DeviceManager 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| ---------- | ---------------------------------------------------- | ---- | --------------------------------- | 82| deviceManager | [DeviceManager](#devicemanager) | 是 | 设备管理器对象实例。 | 83 84**错误码：** 85 86以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 87 88| 错误码ID | 错误信息 | 89| -------- | --------------------------------------------------------------- | 90| 201 | Permission verification failed. The application does not have the permission required to call the API. | 91| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 92| 11600101 | Failed to execute the function. | 93 94**示例：** 95 96 ```ts 97 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 98 import { BusinessError } from '@kit.BasicServicesKit'; 99 100 try { 101 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 102 distributedDeviceManager.releaseDeviceManager(dmInstance); 103 } catch (err) { 104 let e: BusinessError = err as BusinessError; 105 console.error('release device manager errCode:' + e.code + ',errMessage:' + e.message); 106 } 107 ``` 108 109## DeviceBasicInfo 110 111分布式设备基本信息。 112 113**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 114 115| 名称 | 类型 | 必填 | 说明 | 116| ---------------------- | ------------------------- | ---- | -------- | 117| deviceId | string | 是 | 设备标识符。 实际值为udid-hash与appid和盐值基于sha256方式进行混淆后的值。| 118| deviceName | string | 是 | 设备名称。 | 119| deviceType | string | 是 | [设备类型](#getdevicetype)。 | 120| networkId | string | 否 | 设备网络标识。 | 121 122## DeviceStateChange 123 124表示设备状态。 125 126**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager 127 128| 名称 | 值 | 说明 | 129| ----------- | ---- | --------------- | 130| UNKNOWN | 0 | 设备物理上线，此时状态未知，在状态更改为可用之前，分布式业务无法使用。 | 131| AVAILABLE | 1 | 设备可用状态，表示设备间信息已在分布式数据中同步完成, 可以运行分布式业务。 | 132| UNAVAILABLE | 2 | 设备物理下线，此时状态未知。 | 133 134 135## DeviceManager 136 137设备管理实例，用于获取可信设备和本地设备的相关信息。在调用DeviceManager的方法前，需要先通过createDeviceManager构建一个DeviceManager实例dmInstance。 138 139### getAvailableDeviceListSync 140 141getAvailableDeviceListSync(): Array<DeviceBasicInfo>; 142 143同步获取所有可信设备列表。 144 145**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 146 147**系统能力**：SystemCapability.DistributedHardware.DeviceManager 148 149**返回值：** 150 151 | 类型 | 说明 | 152 | ------------------------------------------- | --------- | 153 | Array<[DeviceBasicInfo](#devicebasicinfo)> | 返回可信设备列表。 | 154 155**错误码：** 156 157以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 158 159| 错误码ID | 错误信息 | 160| -------- | --------------------------------------------------------------- | 161| 201 | Permission verification failed. The application does not have the permission required to call the API. | 162| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 163| 11600101 | Failed to execute the function. | 164 165**示例：** 166 167示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 168 ```ts 169 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 170 import { BusinessError } from '@kit.BasicServicesKit'; 171 172 try { 173 let deviceInfoList: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync(); 174 } catch (err) { 175 let e: BusinessError = err as BusinessError; 176 console.error('getAvailableDeviceListSync errCode:' + e.code + ',errMessage:' + e.message); 177 } 178 ``` 179 180### getAvailableDeviceList 181 182getAvailableDeviceList(callback:AsyncCallback<Array<DeviceBasicInfo>>): void; 183 184获取所有可信设备列表。使用callback异步回调。 185 186**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 187 188**系统能力**：SystemCapability.DistributedHardware.DeviceManager 189 190**参数：** 191 192 | 参数名 | 类型 | 必填 | 说明 | 193 | -------- | ---------------------------------------- | ---- | --------------------- | 194 | callback | AsyncCallback<Array<[DeviceBasicInfo](#devicebasicinfo)>> | 是 | 获取所有可信设备列表的回调，返回设备信息。 | 195 196**错误码：** 197 198以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 199 200| 错误码ID | 错误信息 | 201| -------- | --------------------------------------------------------------- | 202| 201 | Permission verification failed. The application does not have the permission required to call the API. | 203| 11600101 | Failed to execute the function. | 204 205**示例：** 206 207示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 208 ```ts 209 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 210 import { BusinessError } from '@kit.BasicServicesKit'; 211 212 try { 213 dmInstance.getAvailableDeviceList((err: BusinessError, data: Array<distributedDeviceManager.DeviceBasicInfo>) => { 214 if (err) { 215 console.error('getAvailableDeviceList errCode:' + err.code + ',errMessage:' + err.message); 216 return; 217 } 218 console.log('get available device info: ' + JSON.stringify(data)); 219 }); 220 } catch (err) { 221 let e: BusinessError = err as BusinessError; 222 console.error('getAvailableDeviceList errCode:' + e.code + ',errMessage:' + e.message); 223 } 224 ``` 225 226### getAvailableDeviceList 227 228getAvailableDeviceList(): Promise<Array<DeviceBasicInfo>>; 229 230获取所有可信设备列表。使用Promise异步回调。 231 232**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 233 234**系统能力**：SystemCapability.DistributedHardware.DeviceManager 235 236**返回值：** 237 238 | 类型 | 说明 | 239 | ---------------------------------------------------------- | ---------------------------------- | 240 | Promise<Array<[DeviceBasicInfo](#devicebasicinfo)>> | Promise实例，用于获取异步返回结果。 | 241 242**错误码：** 243 244以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 245 246| 错误码ID | 错误信息 | 247| -------- | --------------------------------------------------------------- | 248| 201 | Permission verification failed. The application does not have the permission required to call the API. | 249| 11600101 | Failed to execute the function. | 250 251**示例：** 252 253示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 254 ```ts 255 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 256 import { BusinessError } from '@kit.BasicServicesKit'; 257 258 dmInstance.getAvailableDeviceList().then((data: Array<distributedDeviceManager.DeviceBasicInfo>) => { 259 console.log('get available device info: ' + JSON.stringify(data)); 260 }).catch((err: BusinessError) => { 261 console.error('getAvailableDeviceList errCode:' + err.code + ',errMessage:' + err.message); 262 }); 263 ``` 264 265### getLocalDeviceNetworkId 266 267getLocalDeviceNetworkId(): string; 268 269获取本地设备网络标识。 270 271**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 272 273**系统能力**：SystemCapability.DistributedHardware.DeviceManager 274 275**返回值：** 276 277 | 类型 | 说明 | 278 | ------------------------- | ---------------- | 279 | string | 返回本地设备网络标识。 | 280 281**错误码：** 282 283以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 284 285| 错误码ID | 错误信息 | 286| -------- | --------------------------------------------------------------- | 287| 201 | Permission verification failed. The application does not have the permission required to call the API. | 288| 11600101 | Failed to execute the function. | 289 290**示例：** 291 292示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 293 ```ts 294 import { BusinessError } from '@kit.BasicServicesKit'; 295 296 try { 297 let deviceNetworkId: string = dmInstance.getLocalDeviceNetworkId(); 298 console.log('local device networkId: ' + JSON.stringify(deviceNetworkId)); 299 } catch (err) { 300 let e: BusinessError = err as BusinessError; 301 console.error('getLocalDeviceNetworkId errCode:' + e.code + ',errMessage:' + e.message); 302 } 303 ``` 304 305### getLocalDeviceName 306 307getLocalDeviceName(): string; 308 309获取本地设备名称。 310 311**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 312 313**系统能力**：SystemCapability.DistributedHardware.DeviceManager 314 315**返回值：** 316 317 | 类型 | 说明 | 318 | ------------------------- | ---------------- | 319 | string | 返回本地设备名称。 | 320 321**错误码：** 322 323以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 324 325| 错误码ID | 错误信息 | 326| -------- | --------------------------------------------------------------- | 327| 201 | Permission verification failed. The application does not have the permission required to call the API. | 328| 11600101 | Failed to execute the function. | 329 330**示例：** 331 332示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 333 ```ts 334 import { BusinessError } from '@kit.BasicServicesKit'; 335 336 try { 337 let deviceName: string = dmInstance.getLocalDeviceName(); 338 console.log('local device name: ' + JSON.stringify(deviceName)); 339 } catch (err) { 340 let e: BusinessError = err as BusinessError; 341 console.error('getLocalDeviceName errCode:' + e.code + ',errMessage:' + e.message); 342 } 343 ``` 344 345### getLocalDeviceType 346 347getLocalDeviceType(): number; 348 349获取本地设备类型。 350 351**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 352 353**系统能力**：SystemCapability.DistributedHardware.DeviceManager 354 355**返回值：** 356 357 | 类型 | 说明 | 358 | ------------------------- | ---------------- | 359 | number | <!--RP1-->返回本地设备类型。<!--RP1End--> | 360 361**错误码：** 362 363以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 364 365| 错误码ID | 错误信息 | 366| -------- | --------------------------------------------------------------- | 367| 201 | Permission verification failed. The application does not have the permission required to call the API. | 368| 11600101 | Failed to execute the function. | 369 370**示例：** 371 372示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 373 ```ts 374 import { BusinessError } from '@kit.BasicServicesKit'; 375 376 try { 377 let deviceType: number = dmInstance.getLocalDeviceType(); 378 console.log('local device type: ' + JSON.stringify(deviceType)); 379 } catch (err) { 380 let e: BusinessError = err as BusinessError; 381 console.error('getLocalDeviceType errCode:' + e.code + ',errMessage:' + e.message); 382 } 383 ``` 384 385### getLocalDeviceId 386 387getLocalDeviceId(): string; 388 389获取本地设备id，实际值为udid-hash与appid和盐值基于sha256方式进行混淆后的值。 390 391**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 392 393**系统能力**：SystemCapability.DistributedHardware.DeviceManager 394 395**返回值：** 396 397 | 类型 | 说明 | 398 | ------------------------- | ---------------- | 399 | string | 返回本地设备id。 | 400 401**错误码：** 402 403以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 404 405| 错误码ID | 错误信息 | 406| -------- | --------------------------------------------------------------- | 407| 201 | Permission verification failed. The application does not have the permission required to call the API. | 408| 11600101 | Failed to execute the function. | 409 410**示例：** 411 412示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 413 ```ts 414 import { BusinessError } from '@kit.BasicServicesKit'; 415 416 try { 417 let deviceId: string = dmInstance.getLocalDeviceId(); 418 console.log('local device id: ' + JSON.stringify(deviceId)); 419 } catch (err) { 420 let e: BusinessError = err as BusinessError; 421 console.error('getLocalDeviceId errCode:' + e.code + ',errMessage:' + e.message); 422 } 423 ``` 424 425### getDeviceName 426 427getDeviceName(networkId: string): string; 428 429通过指定设备的网络标识获取该设备名称。 430 431**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 432 433**系统能力**：SystemCapability.DistributedHardware.DeviceManager 434 435**参数：** 436 437 | 参数名 | 类型 | 必填 | 说明 | 438 | -------- | ---------------------------------------- | ---- | --------- | 439 | networkId| string | 是 | 设备的网络标识。 | 440 441**返回值：** 442 443 | 类型 | 说明 | 444 | ------------------------- | ---------------- | 445 | string | 返回指定设备名称。 | 446 447**错误码：** 448 449以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 450 451| 错误码ID | 错误信息 | 452| -------- | --------------------------------------------------------------- | 453| 201 | Permission verification failed. The application does not have the permission required to call the API. | 454| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified networkId is greater than 255. | 455| 11600101 | Failed to execute the function. | 456 457**示例：** 458 459示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 460 ```ts 461 import { BusinessError } from '@kit.BasicServicesKit'; 462 463 try { 464 // 设备网络标识，可以从可信设备列表中获取 465 let networkId = 'xxxxxxx'; 466 let deviceName: string = dmInstance.getDeviceName(networkId); 467 console.log('device name: ' + JSON.stringify(deviceName)); 468 } catch (err) { 469 let e: BusinessError = err as BusinessError; 470 console.error('getDeviceName errCode:' + e.code + ',errMessage:' + e.message); 471 } 472 ``` 473 474### getDeviceType 475 476getDeviceType(networkId: string): number; 477 478通过指定设备的网络标识获取该设备类型。 479 480**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 481 482**系统能力**：SystemCapability.DistributedHardware.DeviceManager 483 484**参数：** 485 486 | 参数名 | 类型 | 必填 | 说明 | 487 | -------- | ---------------------------------------- | ---- | --------- | 488 | networkId| string | 是 | 设备的网络标识。 | 489 490**返回值：** 491 492 | 类型 | 说明 | 493 | ------------------------- | ---------------- | 494 | number | <!--RP2-->返回指定设备类型。<!--RP2End--> | 495 496**错误码：** 497 498以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 499 500| 错误码ID | 错误信息 | 501| -------- | --------------------------------------------------------------- | 502| 201 | Permission verification failed. The application does not have the permission required to call the API. | 503| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified networkId is greater than 255. | 504| 11600101 | Failed to execute the function. | 505 506**示例：** 507 508示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 509 ```ts 510 import { BusinessError } from '@kit.BasicServicesKit'; 511 512 try { 513 // 设备网络标识，可以从可信设备列表中获取 514 let networkId = 'xxxxxxx'; 515 let deviceType: number = dmInstance.getDeviceType(networkId); 516 console.log('device type: ' + JSON.stringify(deviceType)); 517 } catch (err) { 518 let e: BusinessError = err as BusinessError; 519 console.error('getDeviceType errCode:' + e.code + ',errMessage:' + e.message); 520 } 521 ``` 522 523### startDiscovering 524 525startDiscovering(discoverParam: {[key: string]: Object;} , filterOptions?: {[key: string]: Object;} ): void; 526 527发现周边设备。发现状态持续两分钟，超过两分钟，会停止发现，最大发现数量99个。wifi场景要求同局域网。 528 529**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 530 531**系统能力**：SystemCapability.DistributedHardware.DeviceManager 532 533**参数：** 534 535 | 参数名 | 类型 | 必填 | 说明 | 536 | ------------- | ------------------------------- | ---- | ----- | 537 | discoverParam | {[key: string]: Object;} | 是 | 发现标识。 标识发现的目标类型。<br>discoverTargetType: 发现目标默认为设备，值为1。| 538 | filterOptions | {[key: string]: Object;} | 否 | 发现设备过滤信息。可选，默认为undefined，发现未上线设备。会携带以下key值：<br>availableStatus(0-1)：仅发现设备可信，值为0表示设备不可信。<br />-0：设备离线，客户端需要通过调用bindTarget绑定设备。<br />-1：设备已在线，客户可以进行连接。<br>discoverDistance(0-100)：发现距离本地一定距离内的设备，单位为cm。wifi场景不传该参数。 <br>authenticationStatus(0-1)：根据不同的认证状态发现设备：<br />-0：设备未认证。<br />-1：设备已认证。<br>authorizationType(0-2)：根据不同的授权类型发现设备：<br />-0：根据临时协商的会话密钥认证的设备。<br />-1：基于同账号密钥进行身份验证的设备。<br />-2：基于不同账号凭据密钥认证的设备。| 539 540**错误码：** 541 542以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 543 544| 错误码ID | 错误信息 | 545| -------- | --------------------------------------------------------------- | 546| 201 | Permission verification failed. The application does not have the permission required to call the API. | 547| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed. | 548| 11600101 | Failed to execute the function. | 549| 11600104 | Discovery unavailable. | 550 551**示例：** 552 553示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 554 ```ts 555 import { BusinessError } from '@kit.BasicServicesKit'; 556 557 interface DiscoverParam { 558 discoverTargetType: number; 559 } 560 561 interface FilterOptions { 562 availableStatus: number; 563 discoverDistance: number; 564 authenticationStatus: number; 565 authorizationType: number; 566 } 567 568 let discoverParam: Record<string, number> = { 569 'discoverTargetType': 1 570 }; 571 let filterOptions: Record<string, number> = { 572 'availableStatus': 0 573 }; 574 575 try { 576 dmInstance.startDiscovering(discoverParam, filterOptions); // 当有设备发现时，通过discoverSuccess回调通知给应用程序 577 } catch (err) { 578 let e: BusinessError = err as BusinessError; 579 console.error('startDiscovering errCode:' + e.code + ',errMessage:' + e.message); 580 } 581 ``` 582 583### stopDiscovering 584 585stopDiscovering(): void; 586 587停止发现周边设备。 588 589**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 590 591**系统能力**：SystemCapability.DistributedHardware.DeviceManager 592 593**错误码：** 594 595以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 596 597| 错误码ID | 错误信息 | 598| -------- | --------------------------------------------------------------- | 599| 201 | Permission verification failed. The application does not have the permission required to call the API. | 600| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed. | 601| 11600101 | Failed to execute the function. | 602| 11600104 | Discovery unavailable. | 603 604**示例：** 605 606示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 607 ```ts 608 import { BusinessError } from '@kit.BasicServicesKit'; 609 610 try { 611 dmInstance.stopDiscovering(); 612 } catch (err) { 613 let e: BusinessError = err as BusinessError; 614 console.error('stopDiscovering errCode:' + e.code + ',errMessage:' + e.message); 615 } 616 ``` 617 618### bindTarget 619 620bindTarget(deviceId: string, bindParam: {[key: string]: Object;} , callback: AsyncCallback<{deviceId: string;}>): void; 621 622认证设备。 623 624**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 625 626**系统能力**：SystemCapability.DistributedHardware.DeviceManager 627 628**参数：** 629 630 | 参数名 | 类型 | 必填 | 说明 | 631 | ---------- | --------------------------------------------------- | ----- | ------------ | 632 | deviceId | string | 是 | 设备标识。 | 633 | bindParam | {[key: string]: Object;} | 是 | 认证参数。由开发者自行决定传入的键值对。默认会携带以下key值：<br>bindType 此值是绑定的类型，必填。<br />-1：PIN码。<br>targetPkgName 绑定目标的包名。<br>appName 尝试绑定目标的应用程序名称。<br>appOperation 应用程序要绑定目标的原因。<br>customDescription 操作的详细说明。 | 634 | callback | AsyncCallback<{deviceId: string; }> | 是 | 认证结果回调。 | 635 636**错误码：** 637 638以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 639 640| 错误码ID | 错误信息 | 641| -------- | --------------------------------------------------------------- | 642| 201 | Permission verification failed. The application does not have the permission required to call the API. | 643| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified deviceId is greater than 255. | 644| 11600101 | Failed to execute the function. | 645| 11600103 | Authentication unavailable. | 646 647**示例：** 648 649示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 650 ```ts 651 import { BusinessError } from '@kit.BasicServicesKit'; 652 653 class Data { 654 deviceId: string = ''; 655 } 656 657 // 认证的设备信息，可以从发现的结果中获取 658 let deviceId = 'XXXXXXXX'; 659 let bindParam: Record<string, string | number> = { 660 'bindType': 1, // 认证类型： 1 - 无账号PIN码认证 661 'targetPkgName': 'xxxx', 662 'appName': 'xxxx', 663 'appOperation': 'xxxx', 664 'customDescription': 'xxxx' 665 }; 666 667 try { 668 dmInstance.bindTarget(deviceId, bindParam, (err: BusinessError, data: Data) => { 669 if (err) { 670 console.error('bindTarget errCode:' + err.code + ',errMessage:' + err.message); 671 return; 672 } 673 console.info('bindTarget result:' + JSON.stringify(data)); 674 }); 675 } catch (err) { 676 let e: BusinessError = err as BusinessError; 677 console.error('bindTarget errCode:' + e.code + ',errMessage:' + e.message); 678 } 679 ``` 680 681### unbindTarget 682 683unbindTarget(deviceId: string): void; 684 685解除认证设备。 686 687**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 688 689**系统能力**：SystemCapability.DistributedHardware.DeviceManager 690 691**参数：** 692 693 | 参数名 | 类型 | 必填 | 说明 | 694 | -------- | ------------------------- | ---- | ---------- | 695 | deviceId | string | 是 | 设备标识。 | 696 697**错误码：** 698 699以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md) 700 701| 错误码ID | 错误信息 | 702| -------- | --------------------------------------------------------------- | 703| 201 | Permission verification failed. The application does not have the permission required to call the API. | 704| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified deviceId is greater than 255. | 705| 11600101 | Failed to execute the function. | 706 707**示例：** 708 709示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 710 ```ts 711 import { BusinessError } from '@kit.BasicServicesKit'; 712 713 try { 714 let deviceId = 'XXXXXXXX'; 715 dmInstance.unbindTarget(deviceId); 716 } catch (err) { 717 let e: BusinessError = err as BusinessError; 718 console.error('unbindTarget errCode:' + e.code + ',errMessage:' + e.message); 719 } 720 ``` 721 722### on('deviceStateChange') 723 724on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChange; device: DeviceBasicInfo; }>): void; 725 726注册设备状态回调，以便在设备状态发生变化时根据应用捆绑包名通知应用。 727 728**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 729 730**系统能力**：SystemCapability.DistributedHardware.DeviceManager 731 732**参数：** 733 734 | 参数名 | 类型 | 必填 | 说明 | 735 | -------- | ---------------------------------------- | ---- | ------------------------------ | 736 | type | string | 是 | 注册设备状态回调，固定为deviceStateChange。 | 737 | callback | Callback<{ action: [DeviceStateChange](#devicestatechange); device: [DeviceBasicInfo](#devicebasicinfo); }> | 是 | 指示要注册的设备状态回调，返回设备状态和设备信息。 | 738 739**错误码：** 740 741以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 742 743| 错误码ID | 错误信息 | 744| -------- | --------------------------------------------------------------- | 745| 201 | Permission verification failed. The application does not have the permission required to call the API. | 746| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 747 748**示例：** 749 750示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 751 ```ts 752 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 753 import { BusinessError } from '@kit.BasicServicesKit'; 754 755 class Data { 756 action: distributedDeviceManager.DeviceStateChange = 0; 757 device: distributedDeviceManager.DeviceBasicInfo = { 758 deviceId: '', 759 deviceName: '', 760 deviceType: '', 761 networkId: '' 762 }; 763 } 764 765 try { 766 dmInstance.on('deviceStateChange', (data: Data) => { 767 console.info('deviceStateChange on:' + JSON.stringify(data)); 768 }); 769 } catch (err) { 770 let e: BusinessError = err as BusinessError; 771 console.error('deviceStateChange errCode:' + e.code + ',errMessage:' + e.message); 772 } 773 ``` 774 775### off('deviceStateChange') 776 777off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChange; device: DeviceBasicInfo; }>): void; 778 779取消注册设备状态回调。 780 781**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 782 783**系统能力**：SystemCapability.DistributedHardware.DeviceManager 784 785**参数：** 786 787 | 参数名 | 类型 | 必填 | 说明 | 788 | -------- | ---------------------------------------- | ---- | --------------------------- | 789 | type | string | 是 | 根据应用程序的包名取消注册设备状态回调，固定为deviceStateChange。 | 790 | callback | Callback<{ action: [deviceStateChange](#devicestatechange); device: [DeviceBasicInfo](#devicebasicinfo); }> | 否 | 指示要取消注册的设备状态回调，返回设备状态和设备信息。 | 791 792**错误码：** 793 794以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 795 796| 错误码ID | 错误信息 | 797| -------- | --------------------------------------------------------------- | 798| 201 | Permission verification failed. The application does not have the permission required to call the API. | 799| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 800 801**示例：** 802 803示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 804 ```ts 805 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 806 import { BusinessError } from '@kit.BasicServicesKit'; 807 808 class Data { 809 action: distributedDeviceManager.DeviceStateChange = 0; 810 device: distributedDeviceManager.DeviceBasicInfo = { 811 deviceId: '', 812 deviceName: '', 813 deviceType: '', 814 networkId: '' 815 }; 816 } 817 818 try { 819 dmInstance.off('deviceStateChange', (data: Data) => { 820 console.info('deviceStateChange' + JSON.stringify(data)); 821 }); 822 } catch (err) { 823 let e: BusinessError = err as BusinessError; 824 console.error('deviceStateChange errCode:' + e.code + ',errMessage:' + e.message); 825 } 826 ``` 827 828### on('discoverSuccess') 829 830on(type: 'discoverSuccess', callback: Callback<{ device: DeviceBasicInfo; }>): void; 831 832注册发现设备成功回调监听。 833 834**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 835 836**系统能力**：SystemCapability.DistributedHardware.DeviceManager 837 838**参数：** 839 840 | 参数名 | 类型 | 必填 | 说明 | 841 | -------- | ---------------------------------------- | ---- | -------------------------- | 842 | type | string | 是 | 注册设备发现回调，以便在发现周边设备时通知应用程序，固定为discoverSuccess。 | 843 | callback | Callback<{ device: [DeviceBasicInfo](#devicebasicinfo); }> | 是 | 注册设备发现的回调方法。 | 844 845**错误码：** 846 847以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 848 849| 错误码ID | 错误信息 | 850| -------- | --------------------------------------------------------------- | 851| 201 | Permission verification failed. The application does not have the permission required to call the API. | 852| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 853 854**示例：** 855 856示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 857 ```ts 858 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 859 import { BusinessError } from '@kit.BasicServicesKit'; 860 861 class Data { 862 device: distributedDeviceManager.DeviceBasicInfo = { 863 deviceId: '', 864 deviceName: '', 865 deviceType: '', 866 networkId: '' 867 }; 868 } 869 870 try { 871 dmInstance.on('discoverSuccess', (data: Data) => { 872 console.info('discoverSuccess:' + JSON.stringify(data)); 873 }); 874 } catch (err) { 875 let e: BusinessError = err as BusinessError; 876 console.error('discoverSuccess errCode:' + e.code + ',errMessage:' + e.message); 877 } 878 ``` 879 880### off('discoverSuccess') 881 882off(type: 'discoverSuccess', callback?: Callback<{ device: DeviceBasicInfo; }>): void; 883 884取消注册设备发现成功回调。 885 886**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 887 888**系统能力**：SystemCapability.DistributedHardware.DeviceManager 889 890**参数：** 891 892 | 参数名 | 类型 | 必填 | 说明 | 893 | -------- | ---------------------------------------- | ---- | --------------------------- | 894 | type | string | 是 | 取消注册设备发现回调，固定为discoverSuccess。 | 895 | callback | Callback<{ device: [DeviceBasicInfo](#devicebasicinfo); }> | 否 | 指示要取消注册的设备发现回调，返回设备状态和设备信息。 | 896 897**错误码：** 898 899以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 900 901| 错误码ID | 错误信息 | 902| -------- | --------------------------------------------------------------- | 903| 201 | Permission verification failed. The application does not have the permission required to call the API. | 904| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 905 906**示例：** 907 908 ```ts 909 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 910 import { BusinessError } from '@kit.BasicServicesKit'; 911 912 class Data { 913 device: distributedDeviceManager.DeviceBasicInfo = { 914 deviceId: '', 915 deviceName: '', 916 deviceType: '', 917 networkId: '' 918 }; 919 } 920 921 try { 922 dmInstance.off('discoverSuccess', (data: Data) => { 923 console.info('discoverSuccess' + JSON.stringify(data)); 924 }); 925 } catch (err) { 926 let e: BusinessError = err as BusinessError; 927 console.error('discoverSuccess errCode:' + e.code + ',errMessage:' + e.message); 928 } 929 ``` 930 931### on('deviceNameChange') 932 933on(type: 'deviceNameChange', callback: Callback<{ deviceName: string; }>): void; 934 935注册设备名称变更回调，以便在设备名称改变时通知应用程序。 936 937**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 938 939**系统能力**：SystemCapability.DistributedHardware.DeviceManager 940 941**参数：** 942 943 | 参数名 | 类型 | 必填 | 说明 | 944 | -------- | ---------------------------------------- | ---- | ------------------------------ | 945 | type | string | 是 | 注册设备名称改变回调，以便在设备名称改变时通知应用程序，固定为deviceNameChange。 | 946 | callback | Callback<{ deviceName: string;}> | 是 | 注册设备名称改变的回调方法。 | 947 948**错误码：** 949 950以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 951 952| 错误码ID | 错误信息 | 953| -------- | --------------------------------------------------------------- | 954| 201 | Permission verification failed. The application does not have the permission required to call the API. | 955| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 956 957**示例：** 958 959示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 960 ```ts 961 import { BusinessError } from '@kit.BasicServicesKit'; 962 963 class Data { 964 deviceName: string = ''; 965 } 966 967 try { 968 dmInstance.on('deviceNameChange', (data: Data) => { 969 console.info('deviceNameChange on:' + JSON.stringify(data)); 970 }); 971 } catch (err) { 972 let e: BusinessError = err as BusinessError; 973 console.error('deviceNameChange errCode:' + e.code + ',errMessage:' + e.message); 974 } 975 ``` 976 977### off('deviceNameChange') 978 979off(type: 'deviceNameChange', callback?: Callback<{ deviceName: string; }>): void; 980 981取消注册设备名称变更回调监听。 982 983**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 984 985**系统能力**：SystemCapability.DistributedHardware.DeviceManager 986 987**参数：** 988 989 | 参数名 | 类型 | 必填 | 说明 | 990 | -------- | ---------------------------------------- | ---- | ------------------------------ | 991 | type | string | 是 | 取消注册设备名称改变回调，固定为deviceNameChange。 | 992 | callback | Callback<{ deviceName: string;}> | 否 | 指示要取消注册设备名称改变的回调方法。 | 993 994**错误码：** 995 996以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 997 998| 错误码ID | 错误信息 | 999| -------- | --------------------------------------------------------------- | 1000| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1001| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 1002 1003**示例：** 1004 1005示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 1006 ```ts 1007 import { BusinessError } from '@kit.BasicServicesKit'; 1008 1009 class Data { 1010 deviceName: string = ''; 1011 } 1012 1013 try { 1014 dmInstance.off('deviceNameChange', (data: Data) => { 1015 console.info('deviceNameChange' + JSON.stringify(data)); 1016 }); 1017 } catch (err) { 1018 let e: BusinessError = err as BusinessError; 1019 console.error('deviceNameChange errCode:' + e.code + ',errMessage:' + e.message); 1020 } 1021 ``` 1022 1023### on('discoverFailure') 1024 1025on(type: 'discoverFailure', callback: Callback<{ reason: number; }>): void; 1026 1027注册设备发现失败回调监听。 1028 1029**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 1030 1031**系统能力**：SystemCapability.DistributedHardware.DeviceManager 1032 1033**参数：** 1034 1035 | 参数名 | 类型 | 必填 | 说明 | 1036 | -------- | ---------------------------------------- | ---- | ------------------------------ | 1037 | type | string | 是 | 注册设备发现失败回调，以便在发现周边设备失败时通知应用程序，固定为discoverFailure。 | 1038 | callback | Callback<{ reason: number; }> | 是 | 注册设备发现失败的回调方法。 | 1039 1040**错误码：** 1041 1042以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 1043 1044| 错误码ID | 错误信息 | 1045| -------- | --------------------------------------------------------------- | 1046| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1047| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 1048 1049**示例：** 1050 1051示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 1052 ```ts 1053 import { BusinessError } from '@kit.BasicServicesKit'; 1054 1055 class Data { 1056 reason: number = 0; 1057 } 1058 1059 try { 1060 dmInstance.on('discoverFailure', (data: Data) => { 1061 console.info('discoverFailure on:' + JSON.stringify(data)); 1062 }); 1063 } catch (err) { 1064 let e: BusinessError = err as BusinessError; 1065 console.error('discoverFailure errCode:' + e.code + ',errMessage:' + e.message); 1066 } 1067 ``` 1068 1069### off('discoverFailure') 1070 1071off(type: 'discoverFailure', callback?: Callback<{ reason: number; }>): void; 1072 1073取消注册设备发现失败回调。 1074 1075**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 1076 1077**系统能力**：SystemCapability.DistributedHardware.DeviceManager 1078 1079**参数：** 1080 1081 | 参数名 | 类型 | 必填 | 说明 | 1082 | -------- | ---------------------------------------- | ---- | ----------------- | 1083 | type | string | 是 | 取消注册设备发现失败回调，固定为discoverFailure。 | 1084 | callback | Callback<{ reason: number; }> | 否 | 指示要取消注册的设备发现失败回调。 | 1085 1086**错误码：** 1087 1088以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 1089 1090| 错误码ID | 错误信息 | 1091| -------- | --------------------------------------------------------------- | 1092| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1093| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 1094 1095**示例：** 1096 1097示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 1098 ```ts 1099 import { BusinessError } from '@kit.BasicServicesKit'; 1100 1101 class Data { 1102 reason: number = 0; 1103 } 1104 1105 try { 1106 dmInstance.off('discoverFailure', (data: Data) => { 1107 console.info('discoverFailure' + JSON.stringify(data)); 1108 }); 1109 } catch (err) { 1110 let e: BusinessError = err as BusinessError; 1111 console.error('discoverFailure errCode:' + e.code + ',errMessage:' + e.message); 1112 } 1113 ``` 1114 1115### on('serviceDie') 1116 1117on(type: 'serviceDie', callback?: Callback<{}>): void; 1118 1119注册设备管理服务死亡回调，以便在服务死亡时通知应用程序。 1120 1121**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 1122 1123**系统能力**：SystemCapability.DistributedHardware.DeviceManager 1124 1125**参数：** 1126 1127 | 参数名 | 类型 | 必填 | 说明 | 1128 | -------- | ----------------------- | ---- | ---------------------------------------- | 1129 | type | string | 是 | 注册serviceDie回调，以便在devicemanager服务异常终止时通知应用程序，固定为serviceDie。 | 1130 | callback | Callback<{}> | 否 | 注册serviceDie的回调方法。 | 1131 1132**错误码：** 1133 1134以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 1135 1136| 错误码ID | 错误信息 | 1137| -------- | --------------------------------------------------------------- | 1138| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1139| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 1140 1141**示例：** 1142 1143示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 1144 ```ts 1145 import { BusinessError } from '@kit.BasicServicesKit'; 1146 1147 try { 1148 dmInstance.on('serviceDie', () => { 1149 console.info('serviceDie on'); 1150 }); 1151 } catch (err) { 1152 let e: BusinessError = err as BusinessError; 1153 console.error('serviceDie errCode:' + e.code + ',errMessage:' + e.message); 1154 } 1155 ``` 1156 1157### off('serviceDie') 1158 1159off(type: 'serviceDie', callback?: Callback<{}>): void; 1160 1161取消注册设备管理服务死亡回调。 1162 1163**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 1164 1165**系统能力**：SystemCapability.DistributedHardware.DeviceManager 1166 1167**参数：** 1168 1169 | 参数名 | 类型 | 必填 | 说明 | 1170 | -------- | ----------------------- | ---- | ---------------------------------------- | 1171 | type | string | 是 | 取消注册serviceDie回调，以便在devicemanager服务异常终止时通知应用程序，固定为serviceDie。 | 1172 | callback | Callback<{}> | 否 | 取消注册serviceDie的回调方法。 | 1173 1174**错误码：** 1175 1176以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md) 1177 1178| 错误码ID | 错误信息 | 1179| -------- | --------------------------------------------------------------- | 1180| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1181| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified type is greater than 255. | 1182 1183**示例：** 1184 1185示例中`dmInstance`的初始化请参见[创建一个设备管理实例](#distributeddevicemanagercreatedevicemanager)。 1186 ```ts 1187 import { BusinessError } from '@kit.BasicServicesKit'; 1188 1189 try { 1190 dmInstance.off('serviceDie', () => { 1191 console.info('serviceDie off'); 1192 }); 1193 } catch (err) { 1194 let e: BusinessError = err as BusinessError; 1195 console.error('serviceDie errCode:' + e.code + ',errMessage:' + e.message); 1196 } 1197 ```