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