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