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