1# @ohos.distributedDeviceManager (Device Management) (System API) 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. This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.distributedDeviceManager](js-apis-distributedDeviceManager.md). 16 17## Modules to Import 18 19```ts 20import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 21``` 22 23## StrategyForHeartbeat<sup>15+</sup> 24 25Defines the heartbeat broadcast policy. 26 27**System capability**: SystemCapability.DistributedHardware.DeviceManager 28 29**System API**: This is a system API. 30 31| Name | Value | Description | 32| ----------- | ---- | --------------- | 33| TEMP_STOP_HEARTBEAT | 100 | Stops the heartbeat broadcast temporarily, and resumes it upon timeout expiration. | 34| START_HEARTBEAT | 101 | Starts heartbeat broadcast. | 35 36## DeviceProfileInfoFilterOptions<sup>15+</sup> 37 38Defines device profile information filter options. 39 40**System capability**: SystemCapability.DistributedHardware.DeviceManager 41 42**System API**: This is a system API. 43 44| Name | Type | Read-Only| Optional | Description | 45| ----------- | ---- | -- | --- |--------------- | 46| isCloud | boolean | No| No | Whether to obtain the device list from the cloud in real time.<br>- **false**: Obtain the device list from the device.<br>- **true**: Obtain the device list from the cloud. | 47| deviceIdList | Array<string> | No| Yes | Device ID. The device ID is usually the UDID of the device. If the device does not have a UDID, the MAC address or SN of the device is used as the device ID. This parameter is left unspecified by default. | 48 49 50## ServiceProfileInfo<sup>15+</sup> 51 52Defines the service profile information. It is populated based on the data returned from the cloud. 53 54**System capability**: SystemCapability.DistributedHardware.DeviceManager 55 56**System API**: This is a system API. 57 58| Name | Type | Read Only| Optional | Description | 59| -------------- | ---- | --------| ------- | --------| 60| deviceId | string | No| No | Device ID. | 61| serviceId | string | No|No | Service ID. | 62| serviceType | string | No| No | Service type. | 63| data | string | No| Yes | Service data. The value is a string of up to 1000 characters. This parameter is left unspecified by default. | 64 65## DeviceProfileInfo<sup>15+</sup> 66 67Defines the device profile information. 68 69**System capability**: SystemCapability.DistributedHardware.DeviceManager 70 71**System API**: This is a system API. 72 73| Name | Type | Read-Only |Optional | Description | 74| -------------- | ---- | ---| --------------- | --------| 75| deviceId | string | No | No | Device ID. | 76| deviceSn | string | No | No | Device SN. | 77| mac | string | No | No | MAC address. | 78| model | string | No | No | Device model. | 79| deviceType | string | No | No | Device type. | 80| manufacturer | string | No | No | Manufacturer. | 81| deviceName | string | No | No | Device name. | 82| productId | string | No | No | Product ID. | 83| subProductId | string | No | Yes | Sub-product ID. This parameter is left unspecified by default. | 84| sdkVersion | string | No | No | SDK version. | 85| bleMac | string | No | No | Bluetooth BLE MAC address. | 86| brMac | string | No | No | Bluetooth BR MAC address. | 87| sleMac | string | No | No | Starflash MAC address.| 88| firmwareVersion | string | No | No | Firmware version. | 89| hardwareVersion | string | No | No | Hardware version. | 90| softwareVersion | string | No | No | Software version. | 91| protocolType | number | No | No | Protocol type. | 92| setupType | number | No | No | Device type. | 93| wiseDeviceId | string | No | No | Registered device ID. | 94| wiseUserId | string | No | No | Registered user ID. | 95| registerTime | string | No | No | Registration time. | 96| modifyTime | string | No | No | Modification time. | 97| shareTime | string | No | No | Share time. | 98| isLocalDevice | boolean | No | No| Whether the device is a local device.<br>- **false**: non-local device.<br>- **true**: local device. | 99| services | Array<[ServiceProfileInfo](#serviceprofileinfo15)> | No | Yes | Service list. This parameter is left unspecified by default.| 100| productName<sup>18+</sup> | string | No | Yes| Product name. This parameter is left unspecified by default. | 101| internalModel<sup>18+</sup> | string | No | Yes| Internal product model. This parameter is left unspecified by default.| 102 103 104## DeviceIconInfoFilterOptions<sup>18+</sup> 105 106Defines the device icon information filter options. 107 108**System capability**: SystemCapability.DistributedHardware.DeviceManager 109 110**System API**: This is a system API. 111 112| Name | Type | Read-Only| Optional | Description | 113| -------------- | ---- | -------| -------- | --------| 114| productId | string | No| No | Product ID. | 115| subProductId | string | No| Yes | Sub-product ID. This parameter is left unspecified by default. | 116| imageType | string | No| No | Image type. This parameter has a fixed value of **ID**, indicating the product's physical image.| 117| specName | string | No| No | Image specification name. Value:<br>- **lg**: large image (size: 1016064 pixels)<br>- **sm**: small image (size: 65536 pixels) | 118| internalModel | string | No| Yes | Internal product model. This parameter is left unspecified by default. | 119 120## DeviceIconInfo<sup>18+</sup> 121 122Defines the device icon information. 123 124**System capability**: SystemCapability.DistributedHardware.DeviceManager 125 126**System API**: This is a system API. 127 128| Name | Type | Read-Only |Optional | Description | 129| -------------- | ---- | ------| --------- | --------| 130| productId | string | No| No | Product ID. | 131| subProductId | string | No| Yes | Sub-product ID. This parameter is left unspecified by default. | 132| imageType | string | No| No | Image type. This parameter has a fixed value of **ID**, indicating the product's physical image. | 133| specName | string | No| No | Image specification name. Value:<br>- **lg**: large image (size: 1016 x 64 pixels)<br>- **sm**: small image (size: 655 x 36 pixels) | 134| url | string | No| No | URL. | 135| icon | ArrayBuffer | No| No| Icon. | 136| internalModel | string | No| Yes | Internal product model. This parameter is left unspecified by default. | 137 138## NetworkIdQueryFilter<sup>18+</sup> 139 140Defines the network ID filter options. 141 142**System capability**: SystemCapability.DistributedHardware.DeviceManager 143 144**System API**: This is a system API. 145 146| Name | Type | Read-Only| Optional | Description | 147| -------------- | ---- | ------ | --------- | --------| 148| wiseDeviceId | string | No| No | Registered device ID. | 149| onlineStatus | number | No| No | Device online status.<br>- **0**: The device is offline.<br>- **1**: The device is online. | 150 151## DeviceManager 152 153Provides 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**. 154 155### replyUiAction 156 157replyUiAction(action: number, actionResult: string): void 158 159Replies to the user's UI operation. This API can be used only by the PIN HAP of the **deviceManager**. 160 161**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 162 163**System capability**: SystemCapability.DistributedHardware.DeviceManager 164 165**System API**: This is a system API. 166 167**Parameters** 168 169 | Name | Type | Mandatory | Description | 170 | ------------- | --------------- | ---- | ------------------- | 171 | action | number | Yes | User operation.<br>- **0**: Grant the permission.<br>- **1**. Remove the permission.<br>- **2**: Time out the user operation in the permission request dialog.<br>- **3**: Cancel the display of the PIN box.<br>- **4**: Cancel the display of the PIN input box.<br>- **5**: Confirm the input in the PIN input box. | 172 | actionResult | string | Yes | User operation result. The value is a string of 1 to 255 characters.| 173 174**Error codes** 175 176For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 177 178| ID| Error Message | 179| -------- | --------------------------------------------------------------- | 180| 201 | Permission verification failed. The application does not have the permission required to call the API. | 181| 202 | Permission verification failed. A non-system application calls a system API. | 182| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; 4. The size of specified actionResult is greater than 255. | 183 184**Example** 185 186<!--code_no_check--> 187 ```ts 188 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 189 import { BusinessError } from '@kit.BasicServicesKit'; 190 191 try { 192 /* 193 action = 0 - Grant the permission. 194 action = 1 - Revoke the permission. 195 action = 2 - Time out the user operation in the permission request dialog. 196 action = 3 - Cancel the display of the PIN box. 197 action = 4 - Cancel the display of the PIN input box. 198 action = 5 - Confirm the input in the PIN input box. 199 */ 200 let operation = 0; 201 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 202 dmInstance.replyUiAction(operation, 'extra'); 203 } catch (err) { 204 let e: BusinessError = err as BusinessError; 205 console.error('replyUiAction errCode:' + e.code + ',errMessage:' + e.message); 206 } 207 ``` 208 209### on('replyResult') 210 211on(type: 'replyResult', callback: Callback<{ param: string;}>): void 212 213Subscribes to the reply to the UI operation result. 214 215**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 216 217**System capability**: SystemCapability.DistributedHardware.DeviceManager 218 219**System API**: This is a system API. 220 221**Parameters** 222 223 | Name | Type | Mandatory| Description | 224 | -------- | ------------------------------------ | ---- | ------------------------------ | 225 | type | string | Yes | Event type, which has a fixed value of **replyResult**.| 226 | callback | Callback<{ param: string;}> | Yes | Callback invoked to return the UI status change. | 227 228**Error codes** 229 230For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 231 232| ID| Error Message | 233| -------- | --------------------------------------------------------------- | 234| 202 | Permission verification failed. A non-system application calls a system API. | 235| 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. | 236 237**Example** 238 239<!--code_no_check--> 240 ```ts 241 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 242 import { BusinessError } from '@kit.BasicServicesKit'; 243 244 class Data { 245 param: string = ''; 246 } 247 248 interface TmpStr { 249 verifyFailed: boolean; 250 } 251 252 try { 253 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 254 dmInstance.on('replyResult', (data: Data) => { 255 console.info('replyResult executed, dialog closed' + JSON.stringify(data)); 256 let tmpStr: TmpStr = JSON.parse(data.param); 257 let isShow = tmpStr.verifyFailed; 258 console.info('replyResult executed, dialog closed' + isShow); 259 }); 260 } catch (err) { 261 let e: BusinessError = err as BusinessError; 262 console.error('replyResult errCode:' + e.code + ',errMessage:' + e.message); 263 } 264 ``` 265 266### off('replyResult') 267 268off(type: 'replyResult', callback?: Callback<{ param: string;}>): void 269 270Unsubscribes from the reply to the UI operation result. 271 272**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 273 274**System capability**: SystemCapability.DistributedHardware.DeviceManager 275 276**System API**: This is a system API. 277 278**Parameters** 279 280 | Name | Type | Mandatory| Description | 281 | -------- | ------------------------------------- | ---- | ------------------------------ | 282 | type | string | Yes | Event type, which has a fixed value of **replyResult**.| 283 | callback | Callback<{ param: string;}> | No | Callback to unregister.| 284 285**Error codes** 286 287For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 288 289| ID| Error Message | 290| -------- | --------------------------------------------------------------- | 291| 202 | Permission verification failed. A non-system application calls a system API. | 292| 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. | 293 294**Example** 295 296<!--code_no_check--> 297 ```ts 298 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 299 import { BusinessError } from '@kit.BasicServicesKit'; 300 301 try { 302 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 303 dmInstance.off('replyResult'); 304 } catch (err) { 305 let e: BusinessError = err as BusinessError; 306 console.error('replyResult errCode:' + e.code + ',errMessage:' + e.message); 307 } 308 ``` 309 310### setHeartbeatPolicy<sup>15+</sup> 311 312setHeartbeatPolicy(policy: StrategyForHeartbeat, delayTime: number): void 313 314Sets the heartbeat broadcast policy. 315 316**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 317 318**System capability**: SystemCapability.DistributedHardware.DeviceManager 319 320**System API**: This is a system API. 321 322**Parameters** 323 324 | Name | Type | Mandatory | Description | 325 | ------------- | --------------- | ---- | ------------------- | 326 | policy | [StrategyForHeartbeat](#strategyforheartbeat15) | Yes | Heartbeat broadcast policy. | 327 | delayTime | number | Yes | Duration for temporarily disabling heartbeat broadcast. The value ranges from 1000 to 15000, in milliseconds. | 328 329**Error codes** 330 331For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 332 333| ID| Error Message | 334| -------- | --------------------------------------------------------------- | 335| 201 | Permission verification failed. The application does not have the permission required to call the API. | 336| 202 | Permission verification failed. A non-system application calls a system API. | 337| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 338| 11600102 | Failed to obtain service. | 339 340**Example** 341 342<!--code_no_check--> 343 ```ts 344 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 345 import { BusinessError } from '@kit.BasicServicesKit'; 346 347 try { 348 let policy = distributedDeviceManager.StrategyForHeartbeat.TEMP_STOP_HEARTBEAT; 349 let delayTime = 1000; 350 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 351 dmInstance.setHeartbeatPolicy(policy, delayTime); 352 } catch (err) { 353 let e: BusinessError = err as BusinessError; 354 console.error('setHeartbeatPolicy errCode:' + e.code + ',errMessage:' + e.message); 355 } 356 ``` 357 358### getDeviceProfileInfoList<sup>15+</sup> 359 360getDeviceProfileInfoList(filterOptions: DeviceProfileInfoFilterOptions): Promise<Array<DeviceProfileInfo>> 361 362Obtains the list of devices under the same account. This API uses a promise to return the result. 363 364**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 365 366**System capability**: SystemCapability.DistributedHardware.DeviceManager 367 368**System API**: This is a system API. 369 370**Parameters** 371 372 | Name | Type | Mandatory | Description | 373 | ------------- | --------------- | ---- | ------------------- | 374 | filterOptions | [DeviceProfileInfoFilterOptions](#deviceprofileinfofilteroptions15) | Yes | Filter options. | 375 376**Returns** 377 378 | Type | Description | 379 | ---------------------------------------------------------- | ---------------------------------- | 380 | Promise<Array<[DeviceProfileInfo](#deviceprofileinfo15)>> | Promise used to return the device list.| 381 382**Error codes** 383 384For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 385 386| ID| Error Message | 387| -------- | --------------------------------------------------------------- | 388| 201 | Permission verification failed. The application does not have the permission required to call the API. | 389| 202 | Permission verification failed. A non-system application calls a system API. | 390| 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 500. | 391| 11600102 | Failed to obtain service. | 392| 11600106 | Get data from cloud fail. | 393| 11600107 | A login account is required. | 394 395**Example** 396 397 ```ts 398 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 399 import { BusinessError } from '@kit.BasicServicesKit'; 400 401 try { 402 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 403 dmInstance.getDeviceProfileInfoList({"isCloud": false}).then((data: Array<distributedDeviceManager.DeviceProfileInfo>) => { 404 console.info('getDeviceProfileInfoList' + JSON.stringify(data)); 405 }).catch((e: BusinessError) => { 406 console.error('getDeviceProfileInfoList errCode:' + e.code + ',errMessage:' + e.message); 407 }); 408 } catch (err) { 409 let e: BusinessError = err as BusinessError; 410 console.error('getDeviceProfileInfoList errCode:' + e.code + ',errMessage:' + e.message); 411 } 412 ``` 413 414### putDeviceProfileInfoList<sup>18+</sup> 415 416putDeviceProfileInfoList(deviceProfileInfoList: Array<DeviceProfileInfo>): Promise<number> 417 418Updates the device list. This API uses a promise to return the result. 419 420**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 421 422**System capability**: SystemCapability.DistributedHardware.DeviceManager 423 424**System API**: This is a system API. 425 426**Parameters** 427 428 | Name | Type | Mandatory | Description | 429 | ------------- | --------------- | ---- | ------------------- | 430 | deviceProfileInfoList | Array<[DeviceProfileInfo](#deviceprofileinfo15)> | Yes | Device list. | 431 432**Returns** 433 434 | Type | Description | 435 | ---------------------------------------------------------- | ---------------------------------- | 436 | number | Operation result. The value **0** indicates that the operation is successful. | 437 438**Error codes** 439 440For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 441 442| ID| Error Message | 443| -------- | --------------------------------------------------------------- | 444| 201 | Permission verification failed. The application does not have the permission required to call the API. | 445| 202 | Permission verification failed. A non-system application calls a system API. | 446| 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 500. | 447| 11600102 | Failed to obtain service. | 448 449**Example** 450 451 ```ts 452 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 453 import { BusinessError } from '@kit.BasicServicesKit'; 454 455 try { 456 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 457 let deviceProfileInfoList:Array<distributedDeviceManager.DeviceProfileInfo> = []; 458 dmInstance.putDeviceProfileInfoList(deviceProfileInfoList).then((data:number) => { 459 console.info('put device profile info:' + JSON.stringify(data)); 460 }).catch((e: BusinessError) => { 461 console.error('putDeviceProfileInfoList errCode:' + e.code + ',errMessage:' + e.message); 462 }); 463 } catch (err) { 464 let e: BusinessError = err as BusinessError; 465 console.error('putDeviceProfileInfoList errCode:' + e.code + ',errMessage:' + e.message); 466 } 467 ``` 468 469### getDeviceIconInfo<sup>18+</sup> 470 471getDeviceIconInfo(filterOptions: DeviceIconInfoFilterOptions): Promise<DeviceIconInfo> 472 473Obtains the device icon. This API uses a promise to return the result. 474 475**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 476 477**System capability**: SystemCapability.DistributedHardware.DeviceManager 478 479**System API**: This is a system API. 480 481**Parameters** 482 483 | Name | Type | Mandatory | Description | 484 | ------------- | --------------- | ---- | ------------------- | 485 | filterOptions | [DeviceIconInfoFilterOptions](#deviceiconinfofilteroptions18) | Yes | Filter options. | 486 487**Returns** 488 489 | Type | Description | 490 | ---------------------------------------------------------- | ---------------------------------- | 491 | Promise<[DeviceIconInfo](#deviceiconinfo18)> | Promise used to return the device icon information. | 492 493**Error codes** 494 495For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 496 497| ID| Error Message | 498| -------- | --------------------------------------------------------------- | 499| 201 | Permission verification failed. The application does not have the permission required to call the API. | 500| 202 | Permission verification failed. A non-system application calls a system API. | 501| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; | 502| 11600102 | Failed to obtain service. | 503| 11600106 | Get data from cloud fail. | 504 505**Example** 506 507 ```ts 508 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 509 import { BusinessError } from '@kit.BasicServicesKit'; 510 511 try { 512 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 513 let productIds:Array<string> = ['M0D2', 'M0D3', 'M0D5', 'M0AB', 'M0BD', 'M0E9', 'M0BC', 'M0EA']; 514 let options:distributedDeviceManager.DeviceIconInfoFilterOptions = { 515 productId: 'P14U', 516 imageType: 'ID', 517 specName: 'lg', 518 }; 519 if (productIds.indexOf(options.productId) != -1) { 520 options.internalModel = ''; 521 } else { 522 options.subProductId = ''; 523 } 524 dmInstance.getDeviceIconInfo(options).then((data: distributedDeviceManager.DeviceIconInfo) => { 525 console.info('getDeviceIconInfo' + JSON.stringify(data)); 526 }).catch((e : BusinessError) => { 527 console.error('getDeviceIconInfo errCode:' + e.code + ',errMessage:' + e.message); 528 }); 529 } catch (err) { 530 let e: BusinessError = err as BusinessError; 531 console.error('getDeviceIconInfo errCode:' + e.code + ',errMessage:' + e.message); 532 } 533 ``` 534 535### getLocalDisplayDeviceName<sup>18+</sup> 536 537getLocalDisplayDeviceName(maxNameLength: number): Promise<string> 538 539Obtains the local device's display name with the specified length. This API uses a promise to return the result. 540 541**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 542 543**System capability**: SystemCapability.DistributedHardware.DeviceManager 544 545**System API**: This is a system API. 546 547**Parameters** 548 549 | Name | Type | Mandatory | Description | 550 | ------------- | --------------- | ---- | ------------------- | 551 | maxNameLength | number | Yes | Length of the local device's display name, in bytes. The value range is [18, 100]. If the value is **0**, the length is not limited. | 552 553**Returns** 554 555 | Type | Description | 556 | ---------------------------------------------------------- | ---------------------------------- | 557 | string | Maximum number of bytes in the local device's display name.| 558 559**Error codes** 560 561For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 562 563| ID| Error Message | 564| -------- | --------------------------------------------------------------- | 565| 201 | Permission verification failed. The application does not have the permission required to call the API. | 566| 202 | Permission verification failed. A non-system application calls a system API. | 567| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; | 568| 11600102 | Failed to obtain service. | 569 570**Example** 571 572 ```ts 573 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 574 import { BusinessError } from '@kit.BasicServicesKit'; 575 576 try { 577 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 578 let maxNameLength:number = 21; 579 dmInstance.getLocalDisplayDeviceName(maxNameLength).then((data:string)=>{ 580 console.info('getLocalDisplayDeviceName name:' + JSON.stringify(data)); 581 }).catch((e: BusinessError)=>{ 582 console.error('getLocalDisplayDeviceName errCode:' + e.code + ',errMessage:' + e.message); 583 }); 584 } catch (err) { 585 let e: BusinessError = err as BusinessError; 586 console.error('getLocalDisplayDeviceName errCode:' + e.code + ',errMessage:' + e.message); 587 } 588 ``` 589 590### setLocalDeviceName<sup>18+</sup> 591 592setLocalDeviceName(deviceName: string): Promise<number> 593 594Sets the local device name. This API uses a promise to return the result. 595 596**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 597 598**System capability**: SystemCapability.DistributedHardware.DeviceManager 599 600**System API**: This is a system API. 601 602**Parameters** 603 604 | Name | Type | Mandatory | Description | 605 | ------------- | --------------- | ---- | ------------------- | 606 | deviceName | string | Yes | Device name to set. The value is a string of 1 to 255 characters. | 607 608**Returns** 609 610 | Type | Description | 611 | ---------------------------------------------------------- | ---------------------------------- | 612 | number | Operation result. The value **0** indicates that the operation is successful.| 613 614**Error codes** 615 616For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 617 618| ID| Error Message | 619| -------- | --------------------------------------------------------------- | 620| 201 | Permission verification failed. The application does not have the permission required to call the API. | 621| 202 | Permission verification failed. A non-system application calls a system API. | 622| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; | 623| 11600102 | Failed to obtain service. | 624| 11600106 | Failed to get data from the cloud. | 625| 11600107 | A login account is required. | 626| 11600108 | The device name contains non-compliant content. | 627 628**Example** 629 630 ```ts 631 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 632 import { BusinessError } from '@kit.BasicServicesKit'; 633 634 try { 635 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 636 let deviceName:string = 'xxx'; 637 dmInstance.setLocalDeviceName(deviceName).then((data:number)=>{ 638 console.info('setLocalDeviceName name:' + JSON.stringify(data)); 639 }).catch((e: BusinessError)=>{ 640 console.error('setLocalDeviceName errCode:' + e.code + ',errMessage:' + e.message); 641 }); 642 } catch (err) { 643 let e: BusinessError = err as BusinessError; 644 console.error('setLocalDeviceName errCode:' + e.code + ',errMessage:' + e.message); 645 } 646 ``` 647 648### setRemoteDeviceName<sup>18+</sup> 649 650setRemoteDeviceName(deviceId: string, deviceName: string): Promise<number> 651 652Sets the remote device name. This API uses a promise to return the result. 653 654**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 655 656**System capability**: SystemCapability.DistributedHardware.DeviceManager 657 658**System API**: This is a system API. 659 660**Parameters** 661 662 | Name | Type | Mandatory | Description | 663 | ------------- | --------------- | ---- | ------------------- | 664 | deviceId | string | Yes | UDID of the remote device. If the device does not have a UDID, the MAC address or SN of the device is used as the device ID. The SN is used preferentially. | 665 | deviceName | string | Yes | Device name to set. The value is a string of 1 to 255 characters. | 666 667**Returns** 668 669 | Type | Description | 670 | ---------------------------------------------------------- | ---------------------------------- | 671 | number | Operation result. The value **0** indicates that the operation is successful.| 672 673**Error codes** 674 675For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 676 677| ID| Error Message | 678| -------- | --------------------------------------------------------------- | 679| 201 | Permission verification failed. The application does not have the permission required to call the API. | 680| 202 | Permission verification failed. A non-system application calls a system API. | 681| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter type; 3. Parameter verification failed; | 682| 11600102 | Failed to obtain service. | 683| 11600106 | Failed to get data from the cloud. | 684| 11600107 | A login account is required. | 685| 11600108 | The device name contains non-compliant content. | 686 687**Example** 688 689 ```ts 690 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 691 import { BusinessError } from '@kit.BasicServicesKit'; 692 693 try { 694 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 695 let deviceId:string = 'xxx'; 696 let deviceName:string = 'xxx'; 697 dmInstance.setRemoteDeviceName(deviceId, deviceName).then((data:number)=>{ 698 console.info('setRemoteDeviceName name:' + JSON.stringify(data)); 699 }).catch((e: BusinessError)=>{ 700 console.error('setRemoteDeviceName errCode:' + e.code + ',errMessage:' + e.message); 701 }); 702 } catch (err) { 703 let e: BusinessError = err as BusinessError; 704 console.error('setRemoteDeviceName errCode:' + e.code + ',errMessage:' + e.message); 705 } 706 ``` 707 708### restoreLocalDeivceName<sup>18+</sup> 709 710restoreLocalDeivceName(): void 711 712Restores the local device name by resetting the network settings. 713 714**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 715 716**System capability**: SystemCapability.DistributedHardware.DeviceManager 717 718**System API**: This is a system API. 719 720**Error codes** 721 722For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 723 724| ID| Error Message | 725| -------- | --------------------------------------------------------------- | 726| 201 | Permission verification failed. The application does not have the permission required to call the API. | 727| 202 | Permission verification failed. A non-system application calls a system API. | 728| 11600102 | Failed to obtain the service. | 729 730**Example** 731 732 ```ts 733 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 734 import { BusinessError } from '@kit.BasicServicesKit'; 735 736 try { 737 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 738 dmInstance.restoreLocalDeivceName(); 739 } catch (err) { 740 let e: BusinessError = err as BusinessError; 741 console.error('restoreLocalDeivceName errCode:' + e.code + ',errMessage:' + e.message); 742 } 743 ``` 744 745### getDeviceNetworkIdList<sup>18+</sup> 746 747getDeviceNetworkIdList(filterOptions: NetworkIdQueryFilter): Promise<Array<string>> 748 749Obtains the list of network devices according to the specified filter options. 750 751**Required permissions**: ohos.permission.ACCESS_SERVICE_DM 752 753**System capability**: SystemCapability.DistributedHardware.DeviceManager 754 755**System API**: This is a system API. 756 757**Parameters** 758 759 | Name | Type | Mandatory | Description | 760 | ------------- | --------------- | ---- | ------------------- | 761 | filterOptions | [NetworkIdQueryFilter](#networkidqueryfilter18) | Yes | Filter options. | 762 763**Returns** 764 765 | Type | Description | 766 | ---------------------------------------------------------- | ---------------------------------- | 767 | Promise<Array<string>> | Promise used to return the device list.| 768 769**Error codes** 770 771For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Device Management Error Codes](errorcode-device-manager.md). 772 773| ID| Error Message | 774| -------- | --------------------------------------------------------------- | 775| 201 | Permission verification failed. The application does not have the permission required to call the API. | 776| 202 | Permission verification failed. A non-system application calls a system API. | 777| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed; | 778| 11600102 | Failed to obtain service. | 779| 11600107 | A login account is required. | 780 781**Example** 782 783 ```ts 784 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 785 import { BusinessError } from '@kit.BasicServicesKit'; 786 787 try { 788 let queryFiler: distributedDeviceManager.NetworkIdQueryFilter = { 789 wiseDeviceId: '', 790 onlineStatus: 1, 791 } 792 let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld'); 793 dmInstance.getDeviceNetworkIdList(queryFiler).then((data:Array<string>) => { 794 console.info('getDeviceNetworkIdList name:' + JSON.stringify(data)); 795 }).catch((e: BusinessError) => { 796 console.error('getDeviceNetworkIdList errCode:' + e.code + ',errMessage:' + e.message); 797 }) 798 } catch (err) { 799 let e: BusinessError = err as BusinessError; 800 console.error('getDeviceNetworkIdList errCode:' + e.code + ',errMessage:' + e.message); 801 } 802 ``` 803