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