1# @ohos.distributedDeviceManager (设备管理)(系统接口) 2 3本模块提供分布式设备管理能力。 4 5应用可调用接口实现如下功能： 6 7- 注册和解除注册设备上下线变化监听。 8- 发现周边不可信设备。 9- 认证和取消认证设备。 10- 查询可信设备列表。 11- 查询本地设备信息，包括设备名称，设备类型和设备标识等。 12 13> **说明：** 14> 15> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.distributedDeviceManager (设备管理)](js-apis-distributedDeviceManager.md)。 16 17## 导入模块 18 19```ts 20import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 21``` 22 23## StrategyForHeartbeat<sup>15+</sup> 24 25表示心跳广播策略。 26 27**系统能力**：SystemCapability.DistributedHardware.DeviceManager 28 29**系统API**： 此接口为系统接口。 30 31| 名称 | 值 | 说明 | 32| ----------- | ---- | --------------- | 33| TEMP_STOP_HEARTBEAT | 100 | 临时停止心跳广播，超时后自动恢复。 | 34| START_HEARTBEAT | 101 | 开始心跳广播。 | 35 36## DeviceProfileInfoFilterOptions<sup>15+</sup> 37 38设备信息过滤器选项。 39 40**系统能力**：SystemCapability.DistributedHardware.DeviceManager 41 42**系统API**： 此接口为系统接口。 43 44| 名称 | 类型 | 只读 | 可选 | 说明 | 45| ----------- | ---- | -- | --- |--------------- | 46| isCloud | boolean | 否 | 否 | 表示是否需要实时从云端获取设备列表。<br />- false：表示从设备获取。<br />- true：表示从云端获取。 | 47| deviceIdList | Array<string> | 否 | 是 | 表示获取指定deviceId的设备信息，deviceId一般为设备的UDID，如设备无UDID，则取其MAC或SN作为deviceId。默认为空。 | 48 49 50## ServiceProfileInfo<sup>15+</sup> 51 52服务配置信息。根据云端返回的数据填充。 53 54**系统能力**：SystemCapability.DistributedHardware.DeviceManager 55 56**系统API**： 此接口为系统接口。 57 58| 名称 | 类型 | 只读| 可选 | 说明 | 59| -------------- | ---- | --------| ------- | --------| 60| deviceId | string | 否 | 否 | 设备ID。 | 61| serviceId | string | 否 |否 | 服务ID。 | 62| serviceType | string | 否 | 否 | 服务类型。 | 63| data | string | 否 | 是 | 服务数据。字符长度不超过1000个字符。默认为空。 | 64 65## DeviceProfileInfo<sup>15+</sup> 66 67设备信息。 68 69**系统能力**：SystemCapability.DistributedHardware.DeviceManager 70 71**系统API**： 此接口为系统接口。 72 73| 名称 | 类型 | 只读 |可选 | 说明 | 74| -------------- | ---- | ---| --------------- | --------| 75| deviceId | string | 否 | 否 | 设备ID。 | 76| deviceSn | string | 否 | 否 | 设备序列号。 | 77| mac | string | 否 | 否 | MAC地址。 | 78| model | string | 否 | 否 | 设备型号。 | 79| deviceType | string | 否 | 否 | 设备类型。 | 80| manufacturer | string | 否 | 否 | 制造商。 | 81| deviceName | string | 否 | 否 | 设备名称。 | 82| productId | string | 否 | 否 | 设备所属产品ID。 | 83| subProductId | string | 否 | 是 | 设备所属产品子ID。默认为空。 | 84| sdkVersion | string | 否 | 否 | SDK版本。 | 85| bleMac | string | 否 | 否 | 蓝牙BLE的MAC地址。 | 86| brMac | string | 否 | 否 | 蓝牙BR的MAC地址。 | 87| sleMac | string | 否 | 否 | Starflash的MAC地址。 | 88| firmwareVersion | string | 否 | 否 | 固件版本。 | 89| hardwareVersion | string | 否 | 否 | 硬件版本。 | 90| softwareVersion | string | 否 | 否 | 软件版本。 | 91| protocolType | number | 否 | 否 | 协议类型。 | 92| setupType | number | 否 | 否 | 设备类型。 | 93| wiseDeviceId | string | 否 | 否 | 已注册设备标识。 | 94| wiseUserId | string | 否 | 否 | 已注册用户标识。 | 95| registerTime | string | 否 | 否 | 注册时间。 | 96| modifyTime | string | 否 | 否 | 修改时间。 | 97| shareTime | string | 否 | 否 | 分享时间。 | 98| isLocalDevice | boolean | 否 | 否 | 是否为本地设备。<br />- false：表示非本地设备，即被查询的其他设备。<br />- true：表示本地设备，即当前正在使用该接口的设备。 | 99| services | Array<[ServiceProfileInfo](#serviceprofileinfo15)> | 否 | 是 | 服务配置信息列表。默认为空。 | 100| productName<sup>18+</sup> | string | 否 | 是 | 设备所属的产品名称。默认为空。 | 101| internalModel<sup>18+</sup> | string | 否 | 是 | 设备所属产品的内部型号。默认为空。 | 102 103 104## DeviceIconInfoFilterOptions<sup>18+</sup> 105 106设备图标信息过滤选项。 107 108**系统能力**：SystemCapability.DistributedHardware.DeviceManager 109 110**系统API**： 此接口为系统接口。 111 112| 名称 | 类型 | 只读 | 可选 | 说明 | 113| -------------- | ---- | -------| -------- | --------| 114| productId | string | 否 | 否 | 设备所属产品ID。 | 115| subProductId | string | 否 | 是 | 设备所属产品子ID。默认为空。 | 116| imageType | string | 否 | 否 | 图片类型。固定值为"ID"，表示产品实物图。 | 117| specName | string | 否 | 否 | 图片规格名称。取值范围：<br />- lg：大图，尺寸为1016064px。<br />- sm：小图，尺寸为65536px。 | 118| internalModel | string | 否 | 是 | 设备所属产品的内部型号。默认为空。 | 119 120## DeviceIconInfo<sup>18+</sup> 121 122设备图标信息。 123 124**系统能力**：SystemCapability.DistributedHardware.DeviceManager 125 126**系统API**： 此接口为系统接口。 127 128| 名称 | 类型 | 只读 |可选 | 说明 | 129| -------------- | ---- | ------| --------- | --------| 130| productId | string | 否 | 否 | 设备所属产品ID。 | 131| subProductId | string | 否 | 是 | 设备所属产品子ID。默认为空字符。 | 132| imageType | string | 否 | 否 | 图片类型。固定值为"ID"，表示产品实物图。 | 133| specName | string | 否 | 否 | 图片规格名称。取值范围：<br />- lg：大图，尺寸为1016064px。<br />- sm：小图，尺寸为65536px。 | 134| url | string | 否 | 否 | URL。 | 135| icon | ArrayBuffer | 否| 否 | 图标。 | 136| internalModel | string | 否 | 是 | 设备所属产品的内部型号。默认为空。 | 137 138## NetworkIdQueryFilter<sup>18+</sup> 139 140设备网络ID过滤器选项。 141 142**系统能力**：SystemCapability.DistributedHardware.DeviceManager 143 144**系统API**： 此接口为系统接口。 145 146| 名称 | 类型 | 只读 | 可选 | 说明 | 147| -------------- | ---- | ------ | --------- | --------| 148| wiseDeviceId | string | 否 | 否 | 已注册设备标识。 | 149| onlineStatus | number | 否 | 否 | 设备在线状态，包括<br />- 0：表示设备处于离线状态。<br />- 1：表示设备处于在线状态。 | 150 151## DeviceManager 152 153设备管理实例，用于获取可信设备和本地设备的相关信息。在调用DeviceManager的方法前，需要先通过createDeviceManager构建一个DeviceManager实例dmInstance。 154 155### replyUiAction 156 157replyUiAction(action: number, actionResult: string): void 158 159回复用户UI操作行为。此接口只能被devicemanager的PIN码hap使用。 160 161**需要权限**：ohos.permission.ACCESS_SERVICE_DM 162 163**系统能力**：SystemCapability.DistributedHardware.DeviceManager 164 165**系统API**： 此接口为系统接口。 166 167**参数：** 168 169 | 参数名 | 类型 | 必填 | 说明 | 170 | ------------- | --------------- | ---- | ------------------- | 171 | action | number | 是 | 用户操作动作。<br />- 0：允许授权。<br />- 1：取消授权。<br />- 2：授权框用户操作超时。<br />- 3：取消pin码框展示。<br />- 4：取消pin码输入框展示。<br />- 5：pin码输入框确定操作。 | 172 | actionResult | string | 是 | 表示用户操作结果，长度范围1~255字符。 | 173 174**错误码：** 175 176以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 177 178| 错误码ID | 错误信息 | 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**示例：** 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 - 允许授权 194 action = 1 - 取消授权 195 action = 2 - 授权框用户操作超时 196 action = 3 - 取消pin码框展示 197 action = 4 - 取消pin码输入框展示 198 action = 5 - pin码输入框确定操作 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 213回复UI操作结果回调。 214 215**需要权限**：ohos.permission.ACCESS_SERVICE_DM 216 217**系统能力**：SystemCapability.DistributedHardware.DeviceManager 218 219**系统API**： 此接口为系统接口。 220 221**参数：** 222 223 | 参数名 | 类型 | 必填 | 说明 | 224 | -------- | ------------------------------------ | ---- | ------------------------------ | 225 | type | string | 是 | 注册的设备管理器 UI 状态回调，以便在状态改变时通知应用，固定为replyResult。 | 226 | callback | Callback<{ param: string;}> | 是 | 指示要注册的设备管理器 UI 状态回调，返回UI状态。 | 227 228**错误码：** 229 230以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 231 232| 错误码ID | 错误信息 | 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**示例：** 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 270取消回复UI操作结果回调。 271 272**需要权限**：ohos.permission.ACCESS_SERVICE_DM 273 274**系统能力**：SystemCapability.DistributedHardware.DeviceManager 275 276**系统API**： 此接口为系统接口。 277 278**参数：** 279 280 | 参数名 | 类型 | 必填 | 说明 | 281 | -------- | ------------------------------------- | ---- | ------------------------------ | 282 | type | string | 是 | 取消注册的设备管理器 UI 状态回调，固定为replyResult。 | 283 | callback | Callback<{ param: string;}> | 否 | 指示要取消注册的设备管理器 UI 状态，返回UI状态。 | 284 285**错误码：** 286 287以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 288 289| 错误码ID | 错误信息 | 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**示例：** 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 314设置心跳广播策略。 315 316**需要权限**：ohos.permission.ACCESS_SERVICE_DM 317 318**系统能力**：SystemCapability.DistributedHardware.DeviceManager 319 320**系统API**： 此接口为系统接口。 321 322**参数：** 323 324 | 参数名 | 类型 | 必填 | 说明 | 325 | ------------- | --------------- | ---- | ------------------- | 326 | policy | [StrategyForHeartbeat](#strategyforheartbeat15) | 是 | 心跳广播策略。 | 327 | delayTime | number | 是 | 临时关闭心跳广播的时长，单位为：ms，取值范围1000ms到15000ms。 | 328 329**错误码：** 330 331以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md)。 332 333| 错误码ID | 错误信息 | 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**示例：** 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 362获取同账号下全部的设备列表，使用Promise异步回调。 363 364**需要权限**：ohos.permission.ACCESS_SERVICE_DM 365 366**系统能力**：SystemCapability.DistributedHardware.DeviceManager 367 368**系统API**： 此接口为系统接口。 369 370**参数：** 371 372 | 参数名 | 类型 | 必填 | 说明 | 373 | ------------- | --------------- | ---- | ------------------- | 374 | filterOptions | [DeviceProfileInfoFilterOptions](#deviceprofileinfofilteroptions15) | 是 | 查询过程中使用的过滤条件。 | 375 376**返回值：** 377 378 | 类型 | 说明 | 379 | ---------------------------------------------------------- | ---------------------------------- | 380 | Promise<Array<[DeviceProfileInfo](#deviceprofileinfo15)>> | Promise实例，返回设备列表。 | 381 382**错误码：** 383 384以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md)。 385 386| 错误码ID | 错误信息 | 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**示例：** 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 418业务调用更新设备列表，使用Promise异步回调。 419 420**需要权限**：ohos.permission.ACCESS_SERVICE_DM 421 422**系统能力**：SystemCapability.DistributedHardware.DeviceManager 423 424**系统API**： 此接口为系统接口。 425 426**参数：** 427 428 | 参数名 | 类型 | 必填 | 说明 | 429 | ------------- | --------------- | ---- | ------------------- | 430 | deviceProfileInfoList | Array<[DeviceProfileInfo](#deviceprofileinfo15)> | 是 | 需要更新的设备列表。 | 431 432**返回值：** 433 434 | 类型 | 说明 | 435 | ---------------------------------------------------------- | ---------------------------------- | 436 | number | 操作结果，0表示本次调用成功。 | 437 438**错误码：** 439 440以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md)。 441 442| 错误码ID | 错误信息 | 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**示例：** 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 473获取设备图标，使用Promise异步回调。 474 475**需要权限**：ohos.permission.ACCESS_SERVICE_DM 476 477**系统能力**：SystemCapability.DistributedHardware.DeviceManager 478 479**系统API**： 此接口为系统接口。 480 481**参数：** 482 483 | 参数名 | 类型 | 必填 | 说明 | 484 | ------------- | --------------- | ---- | ------------------- | 485 | filterOptions | [DeviceIconInfoFilterOptions](#deviceiconinfofilteroptions18) | 是 | 查询过程中使用的过滤条件。 | 486 487**返回值：** 488 489 | 类型 | 说明 | 490 | ---------------------------------------------------------- | ---------------------------------- | 491 | Promise<[DeviceIconInfo](#deviceiconinfo18)> | Promise实例，返回设备图标信息。 | 492 493**错误码：** 494 495以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md)。 496 497| 错误码ID | 错误信息 | 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**示例：** 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 539获取本机指定长度（字节数）的显示名，使用Promise异步回调。 540 541**需要权限**：ohos.permission.ACCESS_SERVICE_DM 542 543**系统能力**：SystemCapability.DistributedHardware.DeviceManager 544 545**系统API**： 此接口为系统接口。 546 547**参数：** 548 549 | 参数名 | 类型 | 必填 | 说明 | 550 | ------------- | --------------- | ---- | ------------------- | 551 | maxNameLength | number | 是 | 可显示的设备名称长度（字节数），取值范围为[18，100]，为0时表示不限制。 | 552 553**返回值：** 554 555 | 类型 | 说明 | 556 | ---------------------------------------------------------- | ---------------------------------- | 557 | string | 指定名称长度最大字节数的本机设备显示名。 | 558 559**错误码：** 560 561以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md)。 562 563| 错误码ID | 错误信息 | 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**示例：** 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 594修改本机设备名称，使用Promise异步回调。 595 596**需要权限**：ohos.permission.ACCESS_SERVICE_DM 597 598**系统能力**：SystemCapability.DistributedHardware.DeviceManager 599 600**系统API**： 此接口为系统接口。 601 602**参数：** 603 604 | 参数名 | 类型 | 必填 | 说明 | 605 | ------------- | --------------- | ---- | ------------------- | 606 | deviceName | string | 是 | 自定义设备名称。字符串长度范围1~255。 | 607 608**返回值：** 609 610 | 类型 | 说明 | 611 | ---------------------------------------------------------- | ---------------------------------- | 612 | number | 操作结果，0表示本次调用成功。 | 613 614**错误码：** 615 616以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md)。 617 618| 错误码ID | 错误信息 | 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**示例：** 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 652设置配件设备名称，使用Promise异步回调。 653 654**需要权限**：ohos.permission.ACCESS_SERVICE_DM 655 656**系统能力**：SystemCapability.DistributedHardware.DeviceManager 657 658**系统API**： 此接口为系统接口。 659 660**参数：** 661 662 | 参数名 | 类型 | 必填 | 说明 | 663 | ------------- | --------------- | ---- | ------------------- | 664 | deviceId | string | 是 | 配件设备的UDID，没有UDID的设备取MAC或SN，优先取SN。 | 665 | deviceName | string | 是 | 自定义设备名称。字符串长度范围1~255。 | 666 667**返回值：** 668 669 | 类型 | 说明 | 670 | ---------------------------------------------------------- | ---------------------------------- | 671 | number | 操作结果，0表示本次调用成功。 | 672 673**错误码：** 674 675以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md)。 676 677| 错误码ID | 错误信息 | 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**示例：** 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 712系统重置还原网络设置时，还原本机设备名。 713 714**需要权限**：ohos.permission.ACCESS_SERVICE_DM 715 716**系统能力**：SystemCapability.DistributedHardware.DeviceManager 717 718**系统API**： 此接口为系统接口。 719 720**错误码：** 721 722以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md)。 723 724| 错误码ID | 错误信息 | 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**示例：** 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 749获取符合条件的网络设备ID列表。 750 751**需要权限**：ohos.permission.ACCESS_SERVICE_DM 752 753**系统能力**：SystemCapability.DistributedHardware.DeviceManager 754 755**系统API**： 此接口为系统接口。 756 757**参数：** 758 759 | 参数名 | 类型 | 必填 | 说明 | 760 | ------------- | --------------- | ---- | ------------------- | 761 | filterOptions | [NetworkIdQueryFilter](#networkidqueryfilter18) | 是 | 查询过程中使用的过滤条件。 | 762 763**返回值：** 764 765 | 类型 | 说明 | 766 | ---------------------------------------------------------- | ---------------------------------- | 767 | Promise<Array<string>> | Promise实例，返回设备网络ID的列表。| 768 769**错误码：** 770 771以下的错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[设备管理错误码](errorcode-device-manager.md)。 772 773| 错误码ID | 错误信息 | 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**示例：** 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