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