1# @ohos.distributedDeviceManager (Device Management) 2 3The **distributedDeviceManager** module provides APIs for distributed device management. 4 5Applications can call the APIs to: 6 7- Subscribe to or unsubscribe from device state changes. 8- Discover devices nearby. 9- Authenticate or deauthenticate a device. 10- Query the trusted device list. 11- Query local device information, including the device name, type, and ID. 12 13> **NOTE** 14> 15> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 16 17## Modules to Import 18 19```ts 20import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 21``` 22 23## distributedDeviceManager.createDeviceManager 24 25createDeviceManager(bundleName: string): DeviceManager; 26 27Creates a **DeviceManager** instance. The **DeviceManager** instance is the entry for invoking the APIs for distributed device management. It can be used to obtain information about trusted devices and local devices. 28 29**System capability**: SystemCapability.DistributedHardware.DeviceManager 30 31**Parameters** 32 33| Name | Type | Mandatory| Description | 34| ---------- | ---------------------------------------------------- | ---- | ----------------------------------------------------------- | 35| bundleName | string | Yes | Bundle name of the application. The value is a string of 1 to 255 characters. | 36 37**Return value** 38 39 | Type | Description | 40 | ------------------------------------------- | --------- | 41 | [DeviceManager](#devicemanager) | **DeviceManager** instance created.| 42 43**Error codes** 44 45For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 46 47| ID| Error Message | 48| -------- | --------------------------------------------------------------- | 49| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed. | 50 51**Example** 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 69Releases a **DeviceManager** instance that is no longer used. 70 71**System capability**: SystemCapability.DistributedHardware.DeviceManager 72 73**Parameters** 74 75| Name | Type | Mandatory| Description | 76| ---------- | ---------------------------------------------------- | ---- | --------------------------------- | 77| deviceManager | [DeviceManager](#devicemanager) | Yes | **DeviceManager** instance to release. | 78 79**Error codes** 80 81For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 82 83| ID| Error Message | 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**Example** 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 105Represents the basic information about a distributed device. 106 107**System capability**: SystemCapability.DistributedHardware.DeviceManager 108 109| Name | Type | Mandatory | Description | 110| ---------------------- | ------------------------- | ---- | -------- | 111| deviceId | string | Yes | Device ID. The value is the result of obfuscating the udid-hash (hash value of the UDID), **appid**, and salt using the SHA-256 algorithm.| 112| deviceName | string | Yes | Device name. | 113| deviceType | string | Yes | [Device type](#getdevicetype). | 114| networkId | string | No | Network ID of the device. | 115 116## DeviceStateChange 117 118Enumerates the device states. 119 120**System capability**: SystemCapability.DistributedHardware.DeviceManager 121 122| Name | Value | Description | 123| ----------- | ---- | --------------- | 124| UNKNOWN | 0 | The device state is unknown after the device goes online. Before the device state changes to available, distributed services cannot be used. | 125| AVAILABLE | 1 | The information between devices has been synchronized in the Distributed Data Service (DDS) module, and the device is ready for running distributed services.| 126| UNAVAILABLE | 2 | The device goes offline, and the device state is unknown. | 127 128## DeviceManager 129 130Provides APIs to obtain information about trusted devices and local devices. Before calling any API in **DeviceManager**, you must use **createDeviceManager** to create a **DeviceManager** instance, for example, **dmInstance**. 131 132### getAvailableDeviceListSync 133 134getAvailableDeviceListSync(): Array<DeviceBasicInfo>; 135 136Obtains all trusted devices synchronously. 137 138**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 139 140**System capability**: SystemCapability.DistributedHardware.DeviceManager 141 142**Return value** 143 144 | Type | Description | 145 | ------------------------------------------- | --------- | 146 | Array<[DeviceBasicInfo](#devicebasicinfo)> | List of trusted devices obtained.| 147 148**Error codes** 149 150For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 151 152| ID| Error Message | 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**Example** 158 159For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 177Obtains all trusted devices. This API uses an asynchronous callback to return the result. 178 179**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 180 181**System capability**: SystemCapability.DistributedHardware.DeviceManager 182 183**Parameters** 184 185 | Name | Type | Mandatory | Description | 186 | -------- | ---------------------------------------- | ---- | --------------------- | 187 | callback | AsyncCallback<Array<[DeviceBasicInfo](#devicebasicinfo)>> | Yes | Callback used to return the list of trusted devices.| 188 189**Error codes** 190 191For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 192 193| ID| Error Message | 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**Example** 199 200For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 224Obtains all trusted devices. This API uses a promise to return the result. 225 226**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 227 228**System capability**: SystemCapability.DistributedHardware.DeviceManager 229 230**Return value** 231 232 | Type | Description | 233 | ---------------------------------------------------------- | ---------------------------------- | 234 | Promise<Array<[DeviceBasicInfo](#devicebasicinfo)>> | Promise used to return the result.| 235 236**Error codes** 237 238For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 239 240| ID| Error Message | 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**Example** 246 247For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 264Obtains the network ID of the local device. 265 266**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 267 268**System capability**: SystemCapability.DistributedHardware.DeviceManager 269 270**Return value** 271 272 | Type | Description | 273 | ------------------------- | ---------------- | 274 | string | Network ID of the local device obtained.| 275 276**Error codes** 277 278For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 279 280| ID| Error Message | 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**Example** 286 287For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 305Obtains the local device name. 306 307**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 308 309**System capability**: SystemCapability.DistributedHardware.DeviceManager 310 311**Return value** 312 313 | Type | Description | 314 | ------------------------- | ---------------- | 315 | string | Name of the local device obtained.| 316 317**Error codes** 318 319For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 320 321| ID| Error Message | 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**Example** 327 328For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 346Obtains the local device type. 347 348**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 349 350**System capability**: SystemCapability.DistributedHardware.DeviceManager 351 352**Return value** 353 354 | Type | Description | 355 | ------------------------- | ---------------- | 356 | number | <!--RP1-->Local device type obtained.<!--RP1End--> | 357 358**Error codes** 359 360For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 361 362| ID| Error Message | 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**Example** 368 369For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 387Obtains the local device ID. The value is the result of obfuscating the udid-hash (hash value of the UDID), **appid**, and salt using the SHA-256 algorithm. 388 389**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 390 391**System capability**: SystemCapability.DistributedHardware.DeviceManager 392 393**Return value** 394 395 | Type | Description | 396 | ------------------------- | ---------------- | 397 | string | Local device ID obtained.| 398 399**Error codes** 400 401For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 402 403| ID| Error Message | 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**Example** 409 410For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 428Obtains the device name based on the network ID of the specified device. 429 430**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 431 432**System capability**: SystemCapability.DistributedHardware.DeviceManager 433 434**Parameters** 435 436 | Name | Type | Mandatory | Description | 437 | -------- | ---------------------------------------- | ---- | --------- | 438 | networkId| string | Yes | Network ID of the device. The value is a string of 1 to 255 characters.| 439 440**Return value** 441 442 | Type | Description | 443 | ------------------------- | ---------------- | 444 | string | Device name obtained.| 445 446**Error codes** 447 448For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 449 450| ID| Error Message | 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**Example** 457 458For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#distributeddevicemanagercreatedevicemanager). 459 460 ```ts 461 import { BusinessError } from '@kit.BasicServicesKit'; 462 463 try { 464 // Network ID of the device, which can be obtained from the trusted device list. 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 478Obtains the device type based on the network ID of the specified device. 479 480**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 481 482**System capability**: SystemCapability.DistributedHardware.DeviceManager 483 484**Parameters** 485 486 | Name | Type | Mandatory | Description | 487 | -------- | ---------------------------------------- | ---- | --------- | 488 | networkId| string | Yes | Network ID of the device. The value is a string of 1 to 255 characters.| 489 490**Return value** 491 492 | Type | Description | 493 | ------------------------- | ---------------- | 494 | number | <!--RP2-->Device type obtained.<!--RP2End--> | 495 496**Error codes** 497 498For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 499 500| ID| Error Message | 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**Example** 507 508For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#distributeddevicemanagercreatedevicemanager). 509 510 ```ts 511 import { BusinessError } from '@kit.BasicServicesKit'; 512 513 try { 514 // Network ID of the device, which can be obtained from the trusted device list. 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 528Starts to discover devices nearby. The discovery process takes 2 minutes. A maximum of 99 devices can be discovered. In Wi-Fi scenarios, only the devices in the same LAN can be discovered. 529 530**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 531 532**System capability**: SystemCapability.DistributedHardware.DeviceManager 533 534**Parameters** 535 536 | Name | Type | Mandatory | Description | 537 | ------------- | ------------------------------- | ---- | ----- | 538 | discoverParam | {[key: string]: Object;} | Yes | Identifier of the device to discover. It specifies the type of the target to discover.<br>**discoverTargetType**: The default discovery target is device. The value is **1**.| 539 | filterOptions | {[key: string]: Object;} | No | Options for filtering the devices to discover. The default value is **undefined**, which means to discover offline devices. The options include the following:<br>- **availableStatus(0-1)**: status of the device to discover. The value **0** means the device is untrusted.<br>- **0**: The device is offline. The client needs to call **bindTarget** to bind the device.<br>- **1**: The device is online and can be connected.<br>**discoverDistance(0-100)**: distance of the device to discover, in cm. This parameter is not used in Wi-Fi scenarios.<br>**authenticationStatus(0-1)**: authentication status of the device to discover.<br>- **0**: The device is not authenticated.<br>The value **1** means the device has been authenticated.<br>- **authorizationType(0-2)**: authorization type of the device to discover.<br>- **0**: The device is authenticated by a temporarily agreed session key.<br>- **1**: The device is authenticated by a key of the same account.<br>- **2**: The device is authenticated by a credential key of different accounts.| 540 541**Error codes** 542 543For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 544 545| ID| Error Message | 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**Example** 553 554For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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); // When devices are discovered, discoverSuccess is called to notify the application. 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 589Stops device discovery. 590 591**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 592 593**System capability**: SystemCapability.DistributedHardware.DeviceManager 594 595**Error codes** 596 597For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 598 599| ID| Error Message | 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**Example** 605 606For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 623Binds a device. 624 625**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 626 627**System capability**: SystemCapability.DistributedHardware.DeviceManager 628 629**Parameters** 630 631 | Name | Type | Mandatory | Description | 632 | ---------- | --------------------------------------------------- | ----- | ------------ | 633 | deviceId | string | Yes | Device ID. The value is a string of 1 to 255 characters. | 634 | bindParam | {[key: string]: Object;} | Yes | Authentication parameters. You can determine the key-value pair to be passed in. By default, the following keys are carried:<br>**bindType**: binding type, which is mandatory.<br>The value **1** means PIN authentication.<br>**targetPkgName**: bundle name of the target to bind.<br>**appName**: application that attempts to bind the target.<br>**appOperation**: reason for the application to bind the target.<br>**customDescription**: detailed description of the operation. | 635 | callback | AsyncCallback<{deviceId: string; }> | Yes | Callback used to return the authentication result.| 636 637**Error codes** 638 639For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 640 641| ID| Error Message | 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**Example** 649 650For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#distributeddevicemanagercreatedevicemanager). 651 652 ```ts 653 import { BusinessError } from '@kit.BasicServicesKit'; 654 655 class Data { 656 deviceId: string = ''; 657 } 658 659 // Information about the device to authenticate. The information can be obtained from the device discovery result. 660 let deviceId = 'XXXXXXXX'; 661 let bindParam: Record<string, string | number> = { 662 'bindType': 1, // Authentication type. The value 1 means PIN authentication. 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 687Unbinds a device. 688 689**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 690 691**System capability**: SystemCapability.DistributedHardware.DeviceManager 692 693**Parameters** 694 695 | Name | Type | Mandatory| Description | 696 | -------- | ------------------------- | ---- | ---------- | 697 | deviceId | string | Yes | Device ID. The value is a string of 1 to 255 characters.| 698 699**Error codes** 700 701For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 702 703| ID| Error Message | 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**Example** 710 711For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 729Subscribes to the device state changes. The application (identified by the bundle name) will be notified when the device state changes. 730 731**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 732 733**System capability**: SystemCapability.DistributedHardware.DeviceManager 734 735**Parameters** 736 737 | Name | Type | Mandatory | Description | 738 | -------- | ---------------------------------------- | ---- | ------------------------------ | 739 | type | string | Yes | Event type. The value **'deviceStateChange'** indicates device state changes.| 740 | callback | Callback<{ action: [DeviceStateChange](#devicestatechange); device: [DeviceBasicInfo](#devicebasicinfo); }> | Yes | Callback used to return the device information and state. | 741 742**Error codes** 743 744For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 745 746| ID| Error Message | 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**Example** 752 753For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 783Unsubscribes from the device state changes. 784 785**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 786 787**System capability**: SystemCapability.DistributedHardware.DeviceManager 788 789**Parameters** 790 791 | Name | Type | Mandatory | Description | 792 | -------- | ---------------------------------------- | ---- | --------------------------- | 793 | type | string | Yes | Event type. The value **'deviceStateChange'** indicates device state changes. | 794 | callback | Callback<{ action: [deviceStateChange](#devicestatechange); device: [DeviceBasicInfo](#devicebasicinfo); }> | No | Callback to unregister.| 795 796**Error codes** 797 798For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 799 800| ID| Error Message | 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**Example** 806 807For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 837Subscribes to the **'discoverSuccess'** event. The application will be notified when a device is successfully discovered. 838 839**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 840 841**System capability**: SystemCapability.DistributedHardware.DeviceManager 842 843**Parameters** 844 845 | Name | Type | Mandatory | Description | 846 | -------- | ---------------------------------------- | ---- | -------------------------- | 847 | type | string | Yes | Event type, which has a fixed value of **'discoverSuccess'**.| 848 | callback | Callback<{ device: [DeviceBasicInfo](#devicebasicinfo); }> | Yes | Callback invoked when a device is successfully discovered. | 849 850**Error codes** 851 852For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 853 854| ID| Error Message | 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**Example** 860 861For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 890Unsubscribes from the **'discoverSuccess'** event. 891 892**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 893 894**System capability**: SystemCapability.DistributedHardware.DeviceManager 895 896**Parameters** 897 898 | Name | Type | Mandatory | Description | 899 | -------- | ---------------------------------------- | ---- | --------------------------- | 900 | type | string | Yes | Event type, which has a fixed value of **'discoverSuccess'**. | 901 | callback | Callback<{ device: [DeviceBasicInfo](#devicebasicinfo); }> | No | Callback to unregister.| 902 903**Error codes** 904 905For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 906 907| ID| Error Message | 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**Example** 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 941Subscribes to device name changes. The application will be notified when the name of a device is changed. 942 943**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 944 945**System capability**: SystemCapability.DistributedHardware.DeviceManager 946 947**Parameters** 948 949 | Name | Type | Mandatory | Description | 950 | -------- | ---------------------------------------- | ---- | ------------------------------ | 951 | type | string | Yes | Event type, which has a fixed value of **deviceNameChange**.| 952 | callback | Callback<{ deviceName: string;}> | Yes | Callback used to return the device name change. | 953 954**Error codes** 955 956For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 957 958| ID| Error Message | 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**Example** 964 965For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 988Unsubscribes from the device name changes. 989 990**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 991 992**System capability**: SystemCapability.DistributedHardware.DeviceManager 993 994**Parameters** 995 996 | Name | Type | Mandatory | Description | 997 | -------- | ---------------------------------------- | ---- | ------------------------------ | 998 | type | string | Yes | Event type, which has a fixed value of **deviceNameChange**.| 999 | callback | Callback<{ deviceName: string;}> | No | Callback to unregister. | 1000 1001**Error codes** 1002 1003For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1004 1005| ID| Error Message | 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**Example** 1011 1012For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 1035Subscribes to the **'discoverFailure'** event. The application will be notified when a device fails to be discovered. 1036 1037**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 1038 1039**System capability**: SystemCapability.DistributedHardware.DeviceManager 1040 1041**Parameters** 1042 1043 | Name | Type | Mandatory | Description | 1044 | -------- | ---------------------------------------- | ---- | ------------------------------ | 1045 | type | string | Yes | Event type, which has a fixed value of **'discoverFailure'**.| 1046 | callback | Callback<{ reason: number; }> | Yes | Callback invoked when a device fails to be discovered. | 1047 1048**Error codes** 1049 1050For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1051 1052| ID| Error Message | 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**Example** 1058 1059For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 1082Unsubscribes from the **'discoverFailure'** event. 1083 1084**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 1085 1086**System capability**: SystemCapability.DistributedHardware.DeviceManager 1087 1088**Parameters** 1089 1090 | Name | Type | Mandatory | Description | 1091 | -------- | ---------------------------------------- | ---- | ----------------- | 1092 | type | string | Yes | Event type, which has a fixed value of **'discoverFailure'**. | 1093 | callback | Callback<{ reason: number; }> | No | Callback to unregister.| 1094 1095**Error codes** 1096 1097For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1098 1099| ID| Error Message | 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**Example** 1105 1106For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 1129Subscribes to the dead events of the **DeviceManager** service. The application will be notified when the **DeviceManager** service is terminated unexpectedly. 1130 1131**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 1132 1133**System capability**: SystemCapability.DistributedHardware.DeviceManager 1134 1135**Parameters** 1136 1137 | Name | Type | Mandatory | Description | 1138 | -------- | ----------------------- | ---- | ---------------------------------------- | 1139 | type | string | Yes | Event type, which has a fixed value of **'serviceDie'**.| 1140 | callback | Callback<{}> | No | Callback invoked when the **DeviceManager** service is terminated unexpectedly. | 1141 1142**Error codes** 1143 1144For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1145 1146| ID| Error Message | 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**Example** 1152 1153For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 1172Unsubscribes from the dead events of the **DeviceManager** service. 1173 1174**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 1175 1176**System capability**: SystemCapability.DistributedHardware.DeviceManager 1177 1178**Parameters** 1179 1180 | Name | Type | Mandatory | Description | 1181 | -------- | ----------------------- | ---- | ---------------------------------------- | 1182 | type | string | Yes | Event type, which has a fixed value of **'serviceDie'**.| 1183 | callback | Callback<{}> | No | Callback to unregister. | 1184 1185**Error codes** 1186 1187For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1188 1189| ID| Error Message | 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**Example** 1195 1196For details about how to initialize `dmInstance` in the example, see [Creating a DeviceManager Instance](#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 ``` 1210