1# @ohos.enterprise.deviceSettings （设备设置管理）(系统接口) 2 3本模块提供企业设备设置能力，包括获取设备息屏时间等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 本模块接口仅可在Stage模型下使用。 10> 11> 本模块接口仅对[设备管理应用](../../mdm/mdm-kit-guide.md#功能介绍)开放，需将[设备管理应用激活](js-apis-enterprise-adminManager-sys.md#adminmanagerenableadmin)后调用，实现相应功能。 12> 13> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.enterprise.deviceSettings](js-apis-enterprise-deviceSettings.md)。 14 15## 导入模块 16 17```ts 18import { deviceSettings } from '@kit.MDMKit'; 19``` 20 21## deviceSettings.setScreenOffTime<sup>11+</sup> 22 23setScreenOffTime(admin: Want, time: number): void 24 25以同步方法指定设备管理应用设置设备息屏时间。成功返回null，失败抛出对应异常。 26 27**需要权限：** ohos.permission.ENTERPRISE_SET_SCREENOFF_TIME 28 29**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| -------- | ---------------------------------------- | ---- | ------------------------------- | 35| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 36| time | number | 是 | 设备息屏时间(单位：毫秒，建议参数与设备可选息屏时间保持一致) | 37 38**错误码**： 39 40以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。 41 42| 错误码ID | 错误信息 | 43| ------- | ---------------------------------------------------------------------------- | 44| 9200001 | The application is not an administrator application of the device. | 45| 9200002 | The administrator application does not have permission to manage the device. | 46| 201 | Permission verification failed. The application does not have the permission required to call the API. | 47| 202 | Permission verification failed. A non-system application calls a system API. | 48| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 49 50**示例：** 51 52```ts 53import { Want } from '@kit.AbilityKit'; 54let wantTemp: Want = { 55 bundleName: 'com.example.myapplication', 56 abilityName: 'EntryAbility', 57}; 58try { 59 deviceSettings.setScreenOffTime(wantTemp, 30000); 60 console.info(`Succeeded in setting screen off time`); 61} catch(err) { 62 console.error(`Failed to set screen off time. Code: ${err.code}, message: ${err.message}`); 63} 64``` 65 66## deviceSettings.getScreenOffTime 67 68getScreenOffTime(admin: Want, callback: AsyncCallback<number>): void 69 70指定设备管理应用获取设备息屏时间，使用callback异步回调。 71 72**需要权限：** ohos.permission.ENTERPRISE_GET_SETTINGS 73 74**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| -------- | ---------------------------------------- | ---- | ------------------------------- | 80| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 81| callback | AsyncCallback<number> | 是 | 回调函数。当接口调用成功，err为null，data为设备息屏时间（单位：毫秒），否则err为错误对象。 | 82 83**错误码**： 84 85以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。 86 87| 错误码ID | 错误信息 | 88| ------- | ---------------------------------------------------------------------------- | 89| 9200001 | The application is not an administrator application of the device. | 90| 9200002 | The administrator application does not have permission to manage the device. | 91| 201 | Permission verification failed. The application does not have the permission required to call the API. | 92| 202 | Permission verification failed. A non-system application calls a system API. | 93| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 94 95**示例：** 96 97```ts 98import { Want } from '@kit.AbilityKit'; 99let wantTemp: Want = { 100 bundleName: 'com.example.myapplication', 101 abilityName: 'EntryAbility', 102}; 103 104deviceSettings.getScreenOffTime(wantTemp, (err, result) => { 105 if (err) { 106 console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`); 107 return; 108 } 109 console.info(`Succeeded in getting screen off time, result : ${result}`); 110}); 111``` 112 113## deviceSettings.getScreenOffTime 114 115getScreenOffTime(admin: Want): Promise<number> 116 117指定设备管理应用获取设备息屏时间，使用Promise异步回调。 118 119**需要权限：** ohos.permission.ENTERPRISE_GET_SETTINGS 120 121**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 122 123**参数：** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| ----- | ----------------------------------- | ---- | ------- | 127| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 128 129**返回值：** 130 131| 类型 | 说明 | 132| --------------------- | ------------------------- | 133| Promise<number> | Promise对象，返回设备息屏时间（单位：毫秒）。 | 134 135**错误码**： 136 137以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。 138 139| 错误码ID | 错误信息 | 140| ------- | ---------------------------------------------------------------------------- | 141| 9200001 | The application is not an administrator application of the device. | 142| 9200002 | The administrator application does not have permission to manage the device. | 143| 201 | Permission verification failed. The application does not have the permission required to call the API. | 144| 202 | Permission verification failed. A non-system application calls a system API. | 145| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 146 147**示例：** 148 149```ts 150import { Want } from '@kit.AbilityKit'; 151import { BusinessError } from '@kit.BasicServicesKit'; 152let wantTemp: Want = { 153 bundleName: 'com.example.myapplication', 154 abilityName: 'EntryAbility', 155}; 156 157deviceSettings.getScreenOffTime(wantTemp).then((result) => { 158 console.info(`Succeeded in getting screen off time, result : ${result}`); 159}).catch((err: BusinessError) => { 160 console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`); 161}); 162``` 163 164## deviceSettings.installUserCertificate 165 166installUserCertificate(admin: Want, certificate: CertBlob, callback: AsyncCallback<string>): void 167 168指定设备管理应用安装用户证书，使用callback异步回调。 169 170**需要权限：** ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 171 172**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 173 174**参数：** 175 176| 参数名 | 类型 | 必填 | 说明 | 177| -------- | ---------------------------------------- | ---- | ------------------------------- | 178| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 179| certificate | [CertBlob](#certblob) | 是 | 证书信息。 | 180| callback | AsyncCallback<string> | 是 | 回调函数，当接口调用成功，err为null，否则为错误对象。 | 181 182**错误码**： 183 184以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。 185 186| 错误码ID | 错误信息 | 187| ------- | ---------------------------------------------------------------------------- | 188| 9200001 | The application is not an administrator application of the device. | 189| 9200002 | The administrator application does not have permission to manage the device. | 190| 9201001 | Failed to manage the certificate. | 191| 201 | Permission verification failed. The application does not have the permission required to call the API. | 192| 202 | Permission verification failed. A non-system application calls a system API. | 193| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 194 195**示例：** 196 197```ts 198import { Want } from '@kit.AbilityKit'; 199import { BusinessError } from '@kit.BasicServicesKit'; 200let wantTemp: Want = { 201 bundleName: 'com.example.myapplication', 202 abilityName: 'EntryAbility', 203}; 204let certFileArray: Uint8Array = new Uint8Array(); 205// The variable context needs to be initialized in MainAbility's onCreate callback function 206// test.cer needs to be placed in the rawfile directory 207getContext().resourceManager.getRawFileContent("test.cer").then((value) => { 208 certFileArray = value; 209 deviceSettings.installUserCertificate(wantTemp, { inData: certFileArray, alias: "cert_alias_xts" }, (err, result) => { 210 if (err) { 211 console.error(`Failed to install user certificate. Code: ${err.code}, message: ${err.message}`); 212 } else { 213 console.info(`Succeeded in installing user certificate, result : ${JSON.stringify(result)}`); 214 } 215 }); 216}).catch((error: BusinessError) => { 217 console.error(`Failed to get row file content. message: ${error.message}`); 218 return 219}); 220``` 221 222## deviceSettings.installUserCertificate 223 224installUserCertificate(admin: Want, certificate: CertBlob): Promise<string> 225 226指定设备管理应用安装用户证书，使用Promise异步回调。 227 228**需要权限：** ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 229 230**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 231 232**参数：** 233 234| 参数名 | 类型 | 必填 | 说明 | 235| ----- | ----------------------------------- | ---- | ------- | 236| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 237| certificate | [CertBlob](#certblob) | 是 | 证书信息。 | 238 239**返回值：** 240 241| 类型 | 说明 | 242| --------------------- | ------------------------- | 243| Promise<string> | Promise对象，返回当前证书安装后的uri，用于卸载证书。 | 244 245**错误码**： 246 247以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。 248 249| 错误码ID | 错误信息 | 250| ------- | ---------------------------------------------------------------------------- | 251| 9200001 | The application is not an administrator application of the device. | 252| 9200002 | The administrator application does not have permission to manage the device. | 253| 9201001 | Failed to manage the certificate. | 254| 201 | Permission verification failed. The application does not have the permission required to call the API. | 255| 202 | Permission verification failed. A non-system application calls a system API. | 256| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 257 258**示例：** 259 260```ts 261import { Want } from '@kit.AbilityKit'; 262import { BusinessError } from '@kit.BasicServicesKit'; 263let wantTemp: Want = { 264 bundleName: 'com.example.myapplication', 265 abilityName: 'EntryAbility', 266}; 267let certFileArray: Uint8Array = new Uint8Array(); 268// The variable context needs to be initialized in MainAbility's onCreate callback function 269// test.cer needs to be placed in the rawfile directory 270getContext().resourceManager.getRawFileContent("test.cer").then((value) => { 271 certFileArray = value 272 deviceSettings.installUserCertificate(wantTemp, { inData: certFileArray, alias: "cert_alias_xts" }) 273 .then((result) => { 274 console.info(`Succeeded in installing user certificate, result : ${JSON.stringify(result)}`); 275 }).catch((err: BusinessError) => { 276 console.error(`Failed to install user certificate. Code: ${err.code}, message: ${err.message}`); 277 }) 278}).catch((error: BusinessError) => { 279 console.error(`Failed to get row file content. message: ${error.message}`); 280 return 281}); 282``` 283 284## CertBlob 285 286证书信息。 287 288**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 289 290| 名称 | 类型 | 必填 | 说明 | 291| ----------- | --------| ----- | ------------------------------- | 292| inData | Uint8Array | 是 | 证书的二进制内容。 | 293| alias | string | 是 | 证书别名。 | 294 295## deviceSettings.uninstallUserCertificate 296 297uninstallUserCertificate(admin: Want, certUri: string, callback: AsyncCallback<void>): void 298 299指定设备管理应用卸载用户证书，使用callback异步回调。 300 301**需要权限：** ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 302 303**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 304 305**参数：** 306 307| 参数名 | 类型 | 必填 | 说明 | 308| -------- | ---------------------------------------- | ---- | ------------------------------- | 309| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 310| certUri | string | 是 | 证书uri，由安装用户证书接口返回。 | 311| callback | AsyncCallback<void> | 是 | 回调函数，当接口调用成功，err为null，否则为错误对象。 | 312 313**错误码**： 314 315以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。 316 317| 错误码ID | 错误信息 | 318| ------- | ---------------------------------------------------------------------------- | 319| 9200001 | The application is not an administrator application of the device. | 320| 9200002 | The administrator application does not have permission to manage the device. | 321| 9201001 | Failed to manage the certificate. | 322| 201 | Permission verification failed. The application does not have the permission required to call the API. | 323| 202 | Permission verification failed. A non-system application calls a system API. | 324| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 325 326**示例：** 327 328```ts 329import { Want } from '@kit.AbilityKit'; 330let wantTemp: Want = { 331 bundleName: 'com.example.myapplication', 332 abilityName: 'EntryAbility', 333}; 334let aliasStr = "certName" 335deviceSettings.uninstallUserCertificate(wantTemp, aliasStr, (err) => { 336 if (err) { 337 console.error(`Failed to uninstall user certificate. Code: ${err.code}, message: ${err.message}`); 338 return; 339 } 340 console.info(`Succeeded in uninstalling user certificate`); 341}); 342``` 343 344## deviceSettings.uninstallUserCertificate 345 346uninstallUserCertificate(admin: Want, certUri: string): Promise<void> 347 348指定设备管理应用卸载用户证书，使用Promise异步回调。 349 350**需要权限：** ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 351 352**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 353 354**参数：** 355 356| 参数名 | 类型 | 必填 | 说明 | 357| ----- | ----------------------------------- | ---- | ------- | 358| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 359| certUri | string | 是 | 证书uri，由安装用户证书接口返回。 | 360 361**返回值：** 362 363| 类型 | 说明 | 364| --------------------- | ------------------------- | 365| Promise<void> | 无返回结果的Promise对象。当指定设备管理应用卸载用户证书失败时会抛出错误对象。 | 366 367**错误码**： 368 369以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。 370 371| 错误码ID | 错误信息 | 372| ------- | ---------------------------------------------------------------------------- | 373| 9200001 | The application is not an administrator application of the device. | 374| 9200002 | The administrator application does not have permission to manage the device. | 375| 9201001 | Failed to manage the certificate. | 376| 201 | Permission verification failed. The application does not have the permission required to call the API. | 377| 202 | Permission verification failed. A non-system application calls a system API. | 378| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 379 380**示例：** 381 382```ts 383import { Want } from '@kit.AbilityKit'; 384import { BusinessError } from '@kit.BasicServicesKit'; 385let wantTemp: Want = { 386 bundleName: 'com.example.myapplication', 387 abilityName: 'EntryAbility', 388}; 389let aliasStr = "certName" 390deviceSettings.uninstallUserCertificate(wantTemp, aliasStr).then(() => { 391 console.info(`Succeeded in uninstalling user certificate`); 392}).catch((err: BusinessError) => { 393 console.error(`Failed to uninstall user certificate. Code is ${err.code}, message is ${err.message}`); 394}); 395``` 396 397## deviceSettings.setPowerPolicy<sup>11+</sup> 398 399setPowerPolicy(admin: Want, powerScene: PowerScene, powerPolicy: PowerPolicy): void 400 401以同步方法指定设备管理应用设置电源策略。成功返回null，失败抛出对应异常。 402 403**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SETTINGS 404 405**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 406 407**参数：** 408 409| 参数名 | 类型 | 必填 | 说明 | 410| -------- | ---------------------------------------- | ---- | ------------------------------- | 411| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 412| powerScene | [PowerScene](#powerscene11) | 是 | 电源策略场景，当前只支持超时场景。 | 413| powerPolicy | [PowerPolicy](#powerpolicy11) | 是 | 电源策略。 | 414 415**错误码**： 416 417以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。 418 419| 错误码ID | 错误信息 | 420| ------- | ---------------------------------------------------------------------------- | 421| 9200001 | The application is not an administrator application of the device. | 422| 9200002 | The administrator application does not have permission to manage the device. | 423| 201 | Permission verification failed. The application does not have the permission required to call the API. | 424| 202 | Permission verification failed. A non-system application calls a system API. | 425| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 426 427**示例：** 428 429```ts 430import { Want } from '@kit.AbilityKit'; 431let wantTemp: Want = { 432 bundleName: 'com.example.myapplication', 433 abilityName: 'EntryAbility', 434}; 435try { 436 let delayTime = 0; 437 let powerScene: deviceSettings.PowerScene = deviceSettings.PowerScene.TIME_OUT; 438 let powerPolicyAction: deviceSettings.PowerPolicyAction = deviceSettings.PowerPolicyAction.AUTO_SUSPEND; 439 let powerPolicy: deviceSettings.PowerPolicy = {powerPolicyAction, delayTime}; 440 deviceSettings.setPowerPolicy(wantTemp, powerScene, powerPolicy); 441 console.info(`Succeeded in setting power polilcy`); 442} catch (err) { 443 console.error(`Failed to set power policy. Code: ${err.code}, message: ${err.message}`); 444} 445``` 446 447## deviceSettings.getPowerPolicy<sup>11+</sup> 448 449getPowerPolicy(admin: Want, powerScene: PowerScene): PowerPolicy 450 451以同步方法指定设备管理应用获取电源策略。成功返回电源策略，失败抛出对应异常。 452 453**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SETTINGS 454 455**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 456 457**参数：** 458 459| 参数名 | 类型 | 必填 | 说明 | 460| -------- | ---------------------------------------- | ---- | ------------------------------- | 461| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 462| powerScene | [PowerScene](#powerscene11) | 是 | 电源策略场景，当前只支持超时场景。 | 463 464**返回值：** 465 466| 类型 | 说明 | 说明 | 467| ----- | ----------------------------------- |------------------------------- | 468| PowerPolicy | [PowerPolicy](#powerpolicy11) | 电源策略。 | 469 470**错误码**： 471 472以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。 473 474| 错误码ID | 错误信息 | 475| ------- | ---------------------------------------------------------------------------- | 476| 9200001 | The application is not an administrator application of the device. | 477| 9200002 | The administrator application does not have permission to manage the device. | 478| 201 | Permission verification failed. The application does not have the permission required to call the API. | 479| 202 | Permission verification failed. A non-system application calls a system API. | 480| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 481 482**示例：** 483 484```ts 485import { Want } from '@kit.AbilityKit'; 486let wantTemp: Want = { 487 bundleName: 'com.example.myapplication', 488 abilityName: 'EntryAbility', 489}; 490try { 491 let powerScene: deviceSettings.PowerScene = deviceSettings.PowerScene.TIME_OUT; 492 let powerPolicy: deviceSettings.PowerPolicy = deviceSettings.getPowerPolicy(wantTemp, powerScene); 493 console.info(`Succeeded in getting power polilcy ${JSON.stringify(powerPolicy)}`); 494} catch (err) { 495 console.error(`Failed to get power policy. Code: ${err.code}, message: ${err.message}`); 496} 497``` 498 499## PowerPolicy<sup>11+</sup> 500 501电源策略。 502 503**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 504 505| 名称 | 类型 | 必填 | 说明 | 506| ----------- | --------| ----- | ------------------------------- | 507| powerPolicyAction | [PowerPolicyAction](#powerpolicyaction11) | 是 | 执行电源策略的动作。 | 508| delayTime | number | 是 | 延迟时间。 | 509 510## PowerScene<sup>11+</sup> 511 512执行电源策略的场景。 513 514**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 515 516| 名称 | 值 | 说明 | 517| -------- | -------- | -------- | 518| TIME_OUT | 0 | 超时场景。 | 519 520## PowerPolicyAction<sup>11+</sup> 521 522执行电源策略的动作。 523 524**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 525 526| 名称 | 值 | 说明 | 527| -------- | -------- | -------- | 528| NONE | 0 | 不执行动作。 | 529| AUTO_SUSPEND | 1 | 自动进入睡眠。 | 530| FORCE_SUSPEND | 2 | 强制进入睡眠。 | 531| HIBERNATE | 3 | 进入休眠。（当前电源子系统暂不支持） | 532| SHUTDOWN | 4 | 关机。 | 533