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 untrusted 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 14> **NOTE** 15> 16> 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. 17 18 19## Modules to Import 20 21```ts 22import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 23``` 24 25 26## distributedDeviceManager.createDeviceManager 27 28createDeviceManager(bundleName: string): DeviceManager; 29 30Creates 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. 31 32**System capability**: SystemCapability.DistributedHardware.DeviceManager 33 34**Parameters** 35 36| Name | Type | Mandatory| Description | 37| ---------- | ---------------------------------------------------- | ---- | ----------------------------------------------------------- | 38| bundleName | string | Yes | Bundle name of the application. | 39 40**Return value** 41 42| Type | Description | 43| ------------------------------------------- | --------- | 44| [DeviceManager](#devicemanager) | **DeviceManager** instance created.| 45 46**Error codes** 47 48For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 49 50| ID| Error Message | 51| -------- | --------------------------------------------------------------- | 52| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed. | 53 54**Example** 55 56 ```ts 57 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 58 import { BusinessError } from '@kit.BasicServicesKit'; 59 60 try { 61 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 62 } catch(err) { 63 let e: BusinessError = err as BusinessError; 64 console.error('createDeviceManager errCode:' + e.code + ',errMessage:' + e.message); 65 } 66 ``` 67 68## distributedDeviceManager.releaseDeviceManager 69 70releaseDeviceManager(deviceManager: DeviceManager): void; 71 72Releases a **DeviceManager** instance that is no longer used. 73 74**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 75 76**System capability**: SystemCapability.DistributedHardware.DeviceManager 77 78**Parameters** 79 80| Name | Type | Mandatory| Description | 81| ---------- | ---------------------------------------------------- | ---- | --------------------------------- | 82| deviceManager | [DeviceManager](#devicemanager) | Yes | **DeviceManager** instance to release. | 83 84**Error codes** 85 86For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 87 88| ID| Error Message | 89| -------- | --------------------------------------------------------------- | 90| 201 | Permission verification failed. The application does not have the permission required to call the API. | 91| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 92| 11600101 | Failed to execute the function. | 93 94**Example** 95 96 ```ts 97 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 98 import { BusinessError } from '@kit.BasicServicesKit'; 99 100 try { 101 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 102 distributedDeviceManager.releaseDeviceManager(dmInstance); 103 } catch (err) { 104 let e: BusinessError = err as BusinessError; 105 console.error('release device manager errCode:' + e.code + ',errMessage:' + e.message); 106 } 107 ``` 108 109## DeviceBasicInfo 110 111Represents the basic information about a distributed device. 112 113**System capability**: SystemCapability.DistributedHardware.DeviceManager 114 115**Parameters** 116 117| Name | Type | Mandatory | Description | 118| ---------------------- | ------------------------- | ---- | -------- | 119| deviceId | string | Yes | Unique ID of the device. The value is the udid-hash (hash value of the UDID) and **appid** encrypted using SHA-256.| 120| deviceName | string | Yes | Device name. | 121| deviceType | string | Yes | [Device type](#getdevicetype). | 122| networkId | string | No | Network ID of the device. | 123 124## DeviceStateChange 125 126Enumerates the device states. 127 128**System capability**: SystemCapability.DistributedHardware.DeviceManager 129 130**Parameters** 131 132| Name | Value | Description | 133| ----------- | ---- | --------------- | 134| UNKNOWN | 0 | The device state is unknown after the device goes online. Before the device state changes to available, distributed services cannot be used. | 135| 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.| 136| UNAVAILABLE | 2 | The device goes offline, and the device state is unknown. | 137 138 139## DeviceManager 140 141Provides 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**. 142 143### getAvailableDeviceListSync 144 145getAvailableDeviceListSync(): Array<DeviceBasicInfo>; 146 147Obtains all trusted devices synchronously. 148 149**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 150 151**System capability**: SystemCapability.DistributedHardware.DeviceManager 152 153**Return value** 154 155| Type | Description | 156| ------------------------------------------- | --------- | 157| Array<[DeviceBasicInfo](#devicebasicinfo)> | List of trusted devices obtained.| 158 159**Error codes** 160 161For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 162 163| ID| Error Message | 164| -------- | --------------------------------------------------------------- | 165| 201 | Permission verification failed. The application does not have the permission required to call the API. | 166| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 167| 11600101 | Failed to execute the function. | 168 169**Example** 170 171For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 172 ```ts 173 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 174 import { BusinessError } from '@kit.BasicServicesKit'; 175 176 try { 177 let deviceInfoList: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync(); 178 } catch (err) { 179 let e: BusinessError = err as BusinessError; 180 console.error('getAvailableDeviceListSync errCode:' + e.code + ',errMessage:' + e.message); 181 } 182 ``` 183 184### getAvailableDeviceList 185 186getAvailableDeviceList(callback:AsyncCallback<Array<DeviceBasicInfo>>): void; 187 188Obtains all trusted devices. This API uses an asynchronous callback to return the result. 189 190**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 191 192**System capability**: SystemCapability.DistributedHardware.DeviceManager 193 194**Parameters** 195 196| Name | Type | Mandatory | Description | 197| -------- | ---------------------------------------- | ---- | --------------------- | 198| callback | AsyncCallback<Array<[DeviceBasicInfo](#devicebasicinfo)>> | Yes | Callback used to return the list of trusted devices.| 199 200**Error codes** 201 202For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 203 204| ID| Error Message | 205| -------- | --------------------------------------------------------------- | 206| 201 | Permission verification failed. The application does not have the permission required to call the API. | 207| 11600101 | Failed to execute the function. | 208 209**Example** 210 211For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 212 ```ts 213 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 214 import { BusinessError } from '@kit.BasicServicesKit'; 215 216 try { 217 dmInstance.getAvailableDeviceList((err: BusinessError, data: Array<distributedDeviceManager.DeviceBasicInfo>) => { 218 if (err) { 219 console.error('getAvailableDeviceList errCode:' + err.code + ',errMessage:' + err.message); 220 return; 221 } 222 console.log('get available device info: ' + JSON.stringify(data)); 223 }); 224 } catch (err) { 225 let e: BusinessError = err as BusinessError; 226 console.error('getAvailableDeviceList errCode:' + e.code + ',errMessage:' + e.message); 227 } 228 ``` 229 230### getAvailableDeviceList 231 232getAvailableDeviceList(): Promise<Array<DeviceBasicInfo>>; 233 234Obtains all trusted devices. This API uses a promise to return the result. 235 236**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 237 238**System capability**: SystemCapability.DistributedHardware.DeviceManager 239 240**Return value** 241 242| Type | Description | 243| ---------------------------------------------------------- | ---------------------------------- | 244| Promise<Array<[DeviceBasicInfo](#devicebasicinfo)>> | Promise used to return the result.| 245 246**Error codes** 247 248For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 249 250| ID| Error Message | 251| -------- | --------------------------------------------------------------- | 252| 201 | Permission verification failed. The application does not have the permission required to call the API. | 253| 11600101 | Failed to execute the function. | 254 255**Example** 256 257For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 258 ```ts 259 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 260 import { BusinessError } from '@kit.BasicServicesKit'; 261 262 dmInstance.getAvailableDeviceList().then((data: Array<distributedDeviceManager.DeviceBasicInfo>) => { 263 console.log('get available device info: ' + JSON.stringify(data)); 264 }).catch((err: BusinessError) => { 265 console.error('getAvailableDeviceList errCode:' + err.code + ',errMessage:' + err.message); 266 }); 267 ``` 268 269### getLocalDeviceNetworkId 270 271getLocalDeviceNetworkId(): string; 272 273Obtains the network ID of the local device. 274 275**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 276 277**System capability**: SystemCapability.DistributedHardware.DeviceManager 278 279**Return value** 280 281| Type | Description | 282| ------------------------- | ---------------- | 283| string | Network ID of the local device obtained.| 284 285**Error codes** 286 287For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 288 289| ID| Error Message | 290| -------- | --------------------------------------------------------------- | 291| 201 | Permission verification failed. The application does not have the permission required to call the API. | 292| 11600101 | Failed to execute the function. | 293 294**Example** 295 296For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 297 ```ts 298 import { BusinessError } from '@kit.BasicServicesKit'; 299 300 try { 301 let deviceNetworkId: string = dmInstance.getLocalDeviceNetworkId(); 302 console.log('local device networkId: ' + JSON.stringify(deviceNetworkId)); 303 } catch (err) { 304 let e: BusinessError = err as BusinessError; 305 console.error('getLocalDeviceNetworkId errCode:' + e.code + ',errMessage:' + e.message); 306 } 307 ``` 308 309### getLocalDeviceName 310 311getLocalDeviceName(): string; 312 313Obtains the local device name. 314 315**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 316 317**System capability**: SystemCapability.DistributedHardware.DeviceManager 318 319**Return value** 320 321| Type | Description | 322| ------------------------- | ---------------- | 323| string | Name of the local device obtained.| 324 325**Error codes** 326 327For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 328 329| ID| Error Message | 330| -------- | --------------------------------------------------------------- | 331| 201 | Permission verification failed. The application does not have the permission required to call the API. | 332| 11600101 | Failed to execute the function. | 333 334**Example** 335 336For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 337 ```ts 338 import { BusinessError } from '@kit.BasicServicesKit'; 339 340 try { 341 let deviceName: string = dmInstance.getLocalDeviceName(); 342 console.log('local device name: ' + JSON.stringify(deviceName)); 343 } catch (err) { 344 let e: BusinessError = err as BusinessError; 345 console.error('getLocalDeviceName errCode:' + e.code + ',errMessage:' + e.message); 346 } 347 ``` 348 349### getLocalDeviceType 350 351getLocalDeviceType(): number; 352 353Obtains the local device type. 354 355**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 356 357**System capability**: SystemCapability.DistributedHardware.DeviceManager 358 359**Return value** 360 361| Type | Description | 362| ------------------------- | ---------------- | 363| number | <!--RP1-->Local device type obtained.<!--RP1End--> | 364 365**Error codes** 366 367For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 368 369| ID| Error Message | 370| -------- | --------------------------------------------------------------- | 371| 201 | Permission verification failed. The application does not have the permission required to call the API. | 372| 11600101 | Failed to execute the function. | 373 374**Example** 375 376For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 377 ```ts 378 import { BusinessError } from '@kit.BasicServicesKit'; 379 380 try { 381 let deviceType: number = dmInstance.getLocalDeviceType(); 382 console.log('local device type: ' + JSON.stringify(deviceType)); 383 } catch (err) { 384 let e: BusinessError = err as BusinessError; 385 console.error('getLocalDeviceType errCode:' + e.code + ',errMessage:' + e.message); 386 } 387 ``` 388 389### getLocalDeviceId 390 391getLocalDeviceId(): string; 392 393Obtains the local device ID. 394 395**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 396 397**System capability**: SystemCapability.DistributedHardware.DeviceManager 398 399**Return value** 400 401| Type | Description | 402| ------------------------- | ---------------- | 403| string | Local device ID obtained.| 404 405**Error codes** 406 407For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 408 409| ID| Error Message | 410| -------- | --------------------------------------------------------------- | 411| 201 | Permission verification failed. The application does not have the permission required to call the API. | 412| 11600101 | Failed to execute the function. | 413 414**Example** 415 416For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 417 ```ts 418 import { BusinessError } from '@kit.BasicServicesKit'; 419 420 try { 421 let deviceId: string = dmInstance.getLocalDeviceId(); 422 console.log('local device id: ' + JSON.stringify(deviceId)); 423 } catch (err) { 424 let e: BusinessError = err as BusinessError; 425 console.error('getLocalDeviceId errCode:' + e.code + ',errMessage:' + e.message); 426 } 427 ``` 428 429### getDeviceName 430 431getDeviceName(networkId: string): string; 432 433Obtains the device name based on the network ID of the specified device. 434 435**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 436 437**System capability**: SystemCapability.DistributedHardware.DeviceManager 438 439**Parameters** 440 441| Name | Type | Mandatory | Description | 442| -------- | ---------------------------------------- | ---- | --------- | 443| networkId| string | Yes | Network ID of the device.| 444 445**Return value** 446 447| Type | Description | 448| ------------------------- | ---------------- | 449| string | Device name obtained.| 450 451**Error codes** 452 453For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 454 455| ID| Error Message | 456| -------- | --------------------------------------------------------------- | 457| 201 | Permission verification failed. The application does not have the permission required to call the API. | 458| 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. | 459| 11600101 | Failed to execute the function. | 460 461**Example** 462 463For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 464 ```ts 465 import { BusinessError } from '@kit.BasicServicesKit'; 466 467 try { 468 // Network ID of the device, which can be obtained from the trusted device list. 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 482Obtains the device type based on the network ID of the specified device. 483 484**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 485 486**System capability**: SystemCapability.DistributedHardware.DeviceManager 487 488**Parameters** 489 490| Name | Type | Mandatory | Description | 491| -------- | ---------------------------------------- | ---- | --------- | 492| networkId| string | Yes | Network ID of the device.| 493 494**Return value** 495 496| Type | Description | 497| ------------------------- | ---------------- | 498| number | <!--RP2-->Device type obtained.<!--RP2End--> | 499 500**Error codes** 501 502For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 503 504| ID| Error Message | 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**Example** 511 512For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 513 ```ts 514 import { BusinessError } from '@kit.BasicServicesKit'; 515 516 try { 517 // Network ID of the device, which can be obtained from the trusted device list. 518 let networkId = 'xxxxxxx'; 519 let deviceType: number = dmInstance.getDeviceType(networkId); 520 console.log('device type: ' + JSON.stringify(deviceType)); 521 } catch (err) { 522 let e: BusinessError = err as BusinessError; 523 console.error('getDeviceType errCode:' + e.code + ',errMessage:' + e.message); 524 } 525 ``` 526 527### startDiscovering 528 529startDiscovering(discoverParam: {[key: string]: Object;} , filterOptions?: {[key: string]: Object;} ): void; 530 531Starts to discover devices nearby. The discovery process lasts 2 minutes. A maximum of 99 devices can be discovered. In Wi-Fi scenarios, only the devices in the same LAN can be discovered. 532 533**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 534 535**System capability**: SystemCapability.DistributedHardware.DeviceManager 536 537**Parameters** 538 539| Name | Type | Mandatory | Description | 540| ------------- | ------------------------------- | ---- | ----- | 541| 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**.| 542| 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.| 543 544**Error codes** 545 546For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 547 548| ID| Error Message | 549| -------- | --------------------------------------------------------------- | 550| 201 | Permission verification failed. The application does not have the permission required to call the API. | 551| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed. | 552| 11600101 | Failed to execute the function. | 553| 11600104 | Discovery unavailable. | 554 555**Example** 556 557For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 558 ```ts 559 import { BusinessError } from '@kit.BasicServicesKit'; 560 561 interface DiscoverParam { 562 discoverTargetType: number; 563 } 564 565 interface FilterOptions { 566 availableStatus: number; 567 discoverDistance: number; 568 authenticationStatus: number; 569 authorizationType: number; 570 } 571 572 let discoverParam: Record<string, number> = { 573 'discoverTargetType': 1 574 }; 575 let filterOptions: Record<string, number> = { 576 'availableStatus': 0 577 }; 578 579 try { 580 dmInstance.startDiscovering(discoverParam, filterOptions); // When devices are discovered, discoverSuccess is called to notify the application. 581 } catch (err) { 582 let e: BusinessError = err as BusinessError; 583 console.error('startDiscovering errCode:' + e.code + ',errMessage:' + e.message); 584 } 585 ``` 586 587### stopDiscovering 588 589stopDiscovering(): void; 590 591Stops device discovery. 592 593**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 594 595**System capability**: SystemCapability.DistributedHardware.DeviceManager 596 597**Error codes** 598 599For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 600 601| ID| Error Message | 602| -------- | --------------------------------------------------------------- | 603| 201 | Permission verification failed. The application does not have the permission required to call the API. | 604| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed. | 605| 11600101 | Failed to execute the function. | 606| 11600104 | Discovery unavailable. | 607 608**Example** 609 610For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 611 ```ts 612 import { BusinessError } from '@kit.BasicServicesKit'; 613 614 try { 615 dmInstance.stopDiscovering(); 616 } catch (err) { 617 let e: BusinessError = err as BusinessError; 618 console.error('stopDiscovering errCode:' + e.code + ',errMessage:' + e.message); 619 } 620 ``` 621 622### bindTarget 623 624bindTarget(deviceId: string, bindParam: {[key: string]: Object;} , callback: AsyncCallback<{deviceId: string;}>): void; 625 626Binds a device. 627 628**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 629 630**System capability**: SystemCapability.DistributedHardware.DeviceManager 631 632**Parameters** 633 634| Name | Type | Mandatory | Description | 635| ---------- | --------------------------------------------------- | ----- | ------------ | 636| deviceId | string | Yes | ID of the device to bind. | 637| 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. 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. | 638| callback | AsyncCallback<{deviceId: string; }> | Yes | Callback used to return the authentication result.| 639 640**Error codes** 641 642For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 643 644| ID| Error Message | 645| -------- | --------------------------------------------------------------- | 646| 201 | Permission verification failed. The application does not have the permission required to call the API. | 647| 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. | 648| 11600101 | Failed to execute the function. | 649| 11600103 | Authentication unavailable. | 650 651**Example** 652 653For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 654 ```ts 655 import { BusinessError } from '@kit.BasicServicesKit'; 656 657 class Data { 658 deviceId: string = ''; 659 } 660 661 // Information about the device to authenticate. The information can be obtained from the device discovery result. 662 let deviceId = 'XXXXXXXX'; 663 let bindParam: Record<string, string | number> = { 664 'bindType': 1, // Authentication type. The value 1 means PIN authentication. 665 'targetPkgName': 'xxxx', 666 'appName': 'xxxx', 667 'appOperation': 'xxxx', 668 'customDescription': 'xxxx' 669 }; 670 671 try { 672 dmInstance.bindTarget(deviceId, bindParam, (err: BusinessError, data: Data) => { 673 if (err) { 674 console.error('bindTarget errCode:' + err.code + ',errMessage:' + err.message); 675 return; 676 } 677 console.info('bindTarget result:' + JSON.stringify(data)); 678 }); 679 } catch (err) { 680 let e: BusinessError = err as BusinessError; 681 console.error('bindTarget errCode:' + e.code + ',errMessage:' + e.message); 682 } 683 ``` 684 685### unbindTarget 686 687unbindTarget(deviceId: string): void; 688 689Unbinds a device. 690 691**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 692 693**System capability**: SystemCapability.DistributedHardware.DeviceManager 694 695**Parameters** 696 697| Name | Type | Mandatory| Description | 698| -------- | ------------------------- | ---- | ---------- | 699| deviceId | string | Yes | Device ID.| 700 701**Error codes** 702 703For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 704 705| ID| Error Message | 706| -------- | --------------------------------------------------------------- | 707| 201 | Permission verification failed. The application does not have the permission required to call the API. | 708| 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. | 709| 11600101 | Failed to execute the function. | 710 711**Example** 712 713For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 714 ```ts 715 import { BusinessError } from '@kit.BasicServicesKit'; 716 717 try { 718 let deviceId = 'XXXXXXXX'; 719 dmInstance.unbindTarget(deviceId); 720 } catch (err) { 721 let e: BusinessError = err as BusinessError; 722 console.error('unbindTarget errCode:' + e.code + ',errMessage:' + e.message); 723 } 724 ``` 725 726### on('deviceStateChange') 727 728on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChange; device: DeviceBasicInfo; }>): void; 729 730Subscribes to the device state changes. The application (identified by the bundle name) will be notified when the device state changes. 731 732**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 733 734**System capability**: SystemCapability.DistributedHardware.DeviceManager 735 736**Parameters** 737 738| Name | Type | Mandatory | Description | 739| -------- | ---------------------------------------- | ---- | ------------------------------ | 740| type | string | Yes | Event type. The value **'deviceStateChange'** indicates device state changes.| 741| callback | Callback<{ action: [DeviceStateChange](#devicestatechange); device: [DeviceBasicInfo](#devicebasicinfo); }> | Yes | Callback used to return the device information and state. | 742 743**Error codes** 744 745For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 746 747| ID| Error Message | 748| -------- | --------------------------------------------------------------- | 749| 201 | Permission verification failed. The application does not have the permission required to call the API. | 750| 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. | 751 752**Example** 753 754For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 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 [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 808 ```ts 809 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 810 import { BusinessError } from '@kit.BasicServicesKit'; 811 812 class Data { 813 action: distributedDeviceManager.DeviceStateChange = 0; 814 device: distributedDeviceManager.DeviceBasicInfo = { 815 deviceId: '', 816 deviceName: '', 817 deviceType: '', 818 networkId: '' 819 }; 820 } 821 822 try { 823 dmInstance.off('deviceStateChange', (data: Data) => { 824 console.info('deviceStateChange' + JSON.stringify(data)); 825 }); 826 } catch (err) { 827 let e: BusinessError = err as BusinessError; 828 console.error('deviceStateChange errCode:' + e.code + ',errMessage:' + e.message); 829 } 830 ``` 831 832### on('discoverSuccess') 833 834on(type: 'discoverSuccess', callback: Callback<{ device: DeviceBasicInfo; }>): void; 835 836Subscribes to the **'discoverSuccess'** event. The application will be notified when a device is successfully discovered. 837 838**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 839 840**System capability**: SystemCapability.DistributedHardware.DeviceManager 841 842**Parameters** 843 844| Name | Type | Mandatory | Description | 845| -------- | ---------------------------------------- | ---- | -------------------------- | 846| type | string | Yes | Event type, which has a fixed value of **'discoverSuccess'**.| 847| callback | Callback<{ device: [DeviceBasicInfo](#devicebasicinfo); }> | Yes | Callback invoked when a device is successfully discovered. | 848 849**Error codes** 850 851For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 852 853| ID| Error Message | 854| -------- | --------------------------------------------------------------- | 855| 201 | Permission verification failed. The application does not have the permission required to call the API. | 856| 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. | 857 858**Example** 859 860For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 861 ```ts 862 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 863 import { BusinessError } from '@kit.BasicServicesKit'; 864 865 class Data { 866 device: distributedDeviceManager.DeviceBasicInfo = { 867 deviceId: '', 868 deviceName: '', 869 deviceType: '', 870 networkId: '' 871 }; 872 } 873 874 try { 875 dmInstance.on('discoverSuccess', (data: Data) => { 876 console.info('discoverSuccess:' + JSON.stringify(data)); 877 }); 878 } catch (err) { 879 let e: BusinessError = err as BusinessError; 880 console.error('discoverSuccess errCode:' + e.code + ',errMessage:' + e.message); 881 } 882 ``` 883 884### off('discoverSuccess') 885 886off(type: 'discoverSuccess', callback?: Callback<{ device: DeviceBasicInfo; }>): void; 887 888Unsubscribes from the **'discoverSuccess'** event. 889 890**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 891 892**System capability**: SystemCapability.DistributedHardware.DeviceManager 893 894**Parameters** 895 896| Name | Type | Mandatory | Description | 897| -------- | ---------------------------------------- | ---- | --------------------------- | 898| type | string | Yes | Event type, which has a fixed value of **'discoverSuccess'**. | 899| callback | Callback<{ device: [DeviceBasicInfo](#devicebasicinfo); }> | No | Callback to unregister.| 900 901**Error codes** 902 903For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 904 905| ID| Error Message | 906| -------- | --------------------------------------------------------------- | 907| 201 | Permission verification failed. The application does not have the permission required to call the API. | 908| 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. | 909 910**Example** 911 912 ```ts 913 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 914 import { BusinessError } from '@kit.BasicServicesKit'; 915 916 class Data { 917 device: distributedDeviceManager.DeviceBasicInfo = { 918 deviceId: '', 919 deviceName: '', 920 deviceType: '', 921 networkId: '' 922 }; 923 } 924 925 try { 926 dmInstance.off('discoverSuccess', (data: Data) => { 927 console.info('discoverSuccess' + JSON.stringify(data)); 928 }); 929 } catch (err) { 930 let e: BusinessError = err as BusinessError; 931 console.error('discoverSuccess errCode:' + e.code + ',errMessage:' + e.message); 932 } 933 ``` 934 935### on('deviceNameChange') 936 937on(type: 'deviceNameChange', callback: Callback<{ deviceName: string; }>): void; 938 939Subscribes to device name changes. The application will be notified when the name of a device is changed. 940 941**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 942 943**System capability**: SystemCapability.DistributedHardware.DeviceManager 944 945**Parameters** 946 947| Name | Type | Mandatory | Description | 948| -------- | ---------------------------------------- | ---- | ------------------------------ | 949| type | string | Yes | Event type, which has a fixed value of **deviceNameChange**.| 950| callback | Callback<{ deviceName: string;}> | Yes | Callback used to return the device name change. | 951 952**Error codes** 953 954For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 955 956| ID| Error Message | 957| -------- | --------------------------------------------------------------- | 958| 201 | Permission verification failed. The application does not have the permission required to call the API. | 959| 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. | 960 961**Example** 962 963For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 964 ```ts 965 import { BusinessError } from '@kit.BasicServicesKit'; 966 967 class Data { 968 deviceName: string = ''; 969 } 970 971 try { 972 dmInstance.on('deviceNameChange', (data: Data) => { 973 console.info('deviceNameChange on:' + JSON.stringify(data)); 974 }); 975 } catch (err) { 976 let e: BusinessError = err as BusinessError; 977 console.error('deviceNameChange errCode:' + e.code + ',errMessage:' + e.message); 978 } 979 ``` 980 981### off('deviceNameChange') 982 983off(type: 'deviceNameChange', callback?: Callback<{ deviceName: string; }>): void; 984 985Unsubscribes from the device name changes. 986 987**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 988 989**System capability**: SystemCapability.DistributedHardware.DeviceManager 990 991**Parameters** 992 993| Name | Type | Mandatory | Description | 994| -------- | ---------------------------------------- | ---- | ------------------------------ | 995| type | string | Yes | Event type, which has a fixed value of **deviceNameChange**.| 996| callback | Callback<{ deviceName: string;}> | No | Callback to unregister. | 997 998**Error codes** 999 1000For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1001 1002| ID| Error Message | 1003| -------- | --------------------------------------------------------------- | 1004| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1005| 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. | 1006 1007**Example** 1008 1009For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 1010 ```ts 1011 import { BusinessError } from '@kit.BasicServicesKit'; 1012 1013 class Data { 1014 deviceName: string = ''; 1015 } 1016 1017 try { 1018 dmInstance.off('deviceNameChange', (data: Data) => { 1019 console.info('deviceNameChange' + JSON.stringify(data)); 1020 }); 1021 } catch (err) { 1022 let e: BusinessError = err as BusinessError; 1023 console.error('deviceNameChange errCode:' + e.code + ',errMessage:' + e.message); 1024 } 1025 ``` 1026 1027### on('discoverFailure') 1028 1029on(type: 'discoverFailure', callback: Callback<{ reason: number; }>): void; 1030 1031Subscribes to the **'discoverFailure'** event. The application will be notified when a device fails to be discovered. 1032 1033**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 1034 1035**System capability**: SystemCapability.DistributedHardware.DeviceManager 1036 1037**Parameters** 1038 1039| Name | Type | Mandatory | Description | 1040| -------- | ---------------------------------------- | ---- | ------------------------------ | 1041| type | string | Yes | Event type, which has a fixed value of **'discoverFailure'**.| 1042| callback | Callback<{ reason: number; }> | Yes | Callback invoked when a device fails to be discovered. | 1043 1044**Error codes** 1045 1046For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1047 1048| ID| Error Message | 1049| -------- | --------------------------------------------------------------- | 1050| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1051| 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. | 1052 1053**Example** 1054 1055For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 1056 ```ts 1057 import { BusinessError } from '@kit.BasicServicesKit'; 1058 1059 class Data { 1060 reason: number = 0; 1061 } 1062 1063 try { 1064 dmInstance.on('discoverFailure', (data: Data) => { 1065 console.info('discoverFailure on:' + JSON.stringify(data)); 1066 }); 1067 } catch (err) { 1068 let e: BusinessError = err as BusinessError; 1069 console.error('discoverFailure errCode:' + e.code + ',errMessage:' + e.message); 1070 } 1071 ``` 1072 1073### off('discoverFailure') 1074 1075off(type: 'discoverFailure', callback?: Callback<{ reason: number; }>): void; 1076 1077Unsubscribes from the **'discoverFailure'** event. 1078 1079**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 1080 1081**System capability**: SystemCapability.DistributedHardware.DeviceManager 1082 1083**Parameters** 1084 1085| Name | Type | Mandatory | Description | 1086| -------- | ---------------------------------------- | ---- | ----------------- | 1087| type | string | Yes | Event type, which has a fixed value of **'discoverFailure'**. | 1088| callback | Callback<{ reason: number; }> | No | Callback to unregister.| 1089 1090**Error codes** 1091 1092For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1093 1094| ID| Error Message | 1095| -------- | --------------------------------------------------------------- | 1096| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1097| 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. | 1098 1099**Example** 1100 1101For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 1102 ```ts 1103 import { BusinessError } from '@kit.BasicServicesKit'; 1104 1105 class Data { 1106 reason: number = 0; 1107 } 1108 1109 try { 1110 dmInstance.off('discoverFailure', (data: Data) => { 1111 console.info('discoverFailure' + JSON.stringify(data)); 1112 }); 1113 } catch (err) { 1114 let e: BusinessError = err as BusinessError; 1115 console.error('discoverFailure errCode:' + e.code + ',errMessage:' + e.message); 1116 } 1117 ``` 1118 1119### on('serviceDie') 1120 1121on(type: 'serviceDie', callback?: Callback<{}>): void; 1122 1123Subscribes to the dead events of the **DeviceManager** service. The application will be notified when the **DeviceManager** service is terminated unexpectedly. 1124 1125**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 1126 1127**System capability**: SystemCapability.DistributedHardware.DeviceManager 1128 1129**Parameters** 1130 1131| Name | Type | Mandatory | Description | 1132| -------- | ----------------------- | ---- | ---------------------------------------- | 1133| type | string | Yes | Event type, which has a fixed value of **'serviceDie'**.| 1134| callback | Callback<{}> | No | Callback invoked when the **DeviceManager** service is terminated unexpectedly. | 1135 1136**Error codes** 1137 1138For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1139 1140| ID| Error Message | 1141| -------- | --------------------------------------------------------------- | 1142| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1143| 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. | 1144 1145**Example** 1146 1147For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 1148 ```ts 1149 import { BusinessError } from '@kit.BasicServicesKit'; 1150 1151 try { 1152 dmInstance.on('serviceDie', () => { 1153 console.info('serviceDie on'); 1154 }); 1155 } catch (err) { 1156 let e: BusinessError = err as BusinessError; 1157 console.error('serviceDie errCode:' + e.code + ',errMessage:' + e.message); 1158 } 1159 ``` 1160 1161### off('serviceDie') 1162 1163off(type: 'serviceDie', callback?: Callback<{}>): void; 1164 1165Unsubscribes from the dead events of the **DeviceManager** service. 1166 1167**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 1168 1169**System capability**: SystemCapability.DistributedHardware.DeviceManager 1170 1171**Parameters** 1172 1173| Name | Type | Mandatory | Description | 1174| -------- | ----------------------- | ---- | ---------------------------------------- | 1175| type | string | Yes | Event type, which has a fixed value of **'serviceDie'**.| 1176| callback | Callback<{}> | No | Callback to unregister. | 1177 1178**Error codes** 1179 1180For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1181 1182| ID| Error Message | 1183| -------- | --------------------------------------------------------------- | 1184| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1185| 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. | 1186 1187**Example** 1188 1189For details about how to initialize **dmInstance** in the example, see [distributedDeviceManager.createDeviceManager](#distributeddevicemanagercreatedevicemanager). 1190 ```ts 1191 import { BusinessError } from '@kit.BasicServicesKit'; 1192 1193 try { 1194 dmInstance.off('serviceDie', () => { 1195 console.info('serviceDie off'); 1196 }); 1197 } catch (err) { 1198 let e: BusinessError = err as BusinessError; 1199 console.error('serviceDie errCode:' + e.code + ',errMessage:' + e.message); 1200 } 1201 ``` 1202