1# @ohos.enterprise.deviceSettings (Device Settings) (System API) 2 3The **deviceSettings** module provides APIs for setting enterprise devices, including obtaining the screen-off time of a device. 4 5> **NOTE** 6> 7> 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. 8> 9> The APIs of this module can be used only in the stage model. 10> 11> The APIs of this module can be called only by a [device administrator application](../../mdm/mdm-kit-guide.md#introduction) that is [enabled](js-apis-enterprise-adminManager-sys.md#adminmanagerenableadmin). 12> 13> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.enterprise.deviceSettings](js-apis-enterprise-deviceSettings.md). 14 15## Modules to Import 16 17```ts 18import { deviceSettings } from '@kit.MDMKit'; 19``` 20 21## deviceSettings.setScreenOffTime<sup>11+</sup> 22 23setScreenOffTime(admin: Want, time: number): void 24 25Sets the device screen-off time through the specified device administrator application. This API returns the result synchronously. If the operation is successful, **null** is returned. If the operation fails, an exception will be thrown. 26 27**Required permissions**: ohos.permission.ENTERPRISE_SET_SCREENOFF_TIME 28 29**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 30 31**Parameters** 32 33| Name | Type | Mandatory | Description | 34| -------- | ---------------------------------------- | ---- | ------------------------------- | 35| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application. | 36| time | number | Yes | Screen-off time to set, in milliseconds. You are advised to set this parameter to the device's optional screen-off time. | 37 38**Error codes** 39 40For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 41 42| ID| Error Message | 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**Example** 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 70Obtains the device screen-off time through the specified device administrator application. This API uses an asynchronous callback to return the result. 71 72**Required permissions**: ohos.permission.ENTERPRISE_GET_SETTINGS 73 74**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 75 76**Parameters** 77 78| Name | Type | Mandatory | Description | 79| -------- | ---------------------------------------- | ---- | ------------------------------- | 80| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application. | 81| callback | AsyncCallback<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is the screen-off time in ms. If the operation fails, **err** is an error object. | 82 83**Error codes** 84 85For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 86 87| ID| Error Message | 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**Example** 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 117Obtains the device screen-off time through the specified device administrator application. This API uses a promise to return the result. 118 119**Required permissions**: ohos.permission.ENTERPRISE_GET_SETTINGS 120 121**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 122 123**Parameters** 124 125| Name | Type | Mandatory | Description | 126| ----- | ----------------------------------- | ---- | ------- | 127| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application.| 128 129**Return value** 130 131| Type | Description | 132| --------------------- | ------------------------- | 133| Promise<number> | Promise used to return the screen-off time, in ms. | 134 135**Error codes** 136 137For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 138 139| ID| Error Message | 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**Example** 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 168Installs a user certificate through the specified device administrator application. This API uses an asynchronous callback to return the result. 169 170**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 171 172**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 173 174**Parameters** 175 176| Name | Type | Mandatory | Description | 177| -------- | ---------------------------------------- | ---- | ------------------------------- | 178| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application. | 179| certificate | [CertBlob](#certblob) | Yes | Information about the certificate to install. | 180| callback | AsyncCallback<string> | Yes | Callback used to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | 181 182**Error codes** 183 184For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 185 186| ID| Error Message | 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**Example** 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 226Installs a user certificate through the specified device administrator application. This API uses a promise to return the result. 227 228**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 229 230**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 231 232**Parameters** 233 234| Name | Type | Mandatory | Description | 235| ----- | ----------------------------------- | ---- | ------- | 236| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application.| 237| certificate | [CertBlob](#certblob) | Yes | Information about the certificate to install. | 238 239**Return value** 240 241| Type | Description | 242| --------------------- | ------------------------- | 243| Promise<string> | Promise used to return the URI of the installed certificate. This URI can be used to uninstall the certificate.| 244 245**Error codes** 246 247For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 248 249| ID| Error Message | 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**Example** 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 286Represents the certificate information. 287 288**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 289 290| Name | Type | Mandatory| Description | 291| ----------- | --------| ----- | ------------------------------- | 292| inData | Uint8Array | Yes| Binary content of the certificate.| 293| alias | string | Yes| Certificate alias.| 294 295## deviceSettings.uninstallUserCertificate 296 297uninstallUserCertificate(admin: Want, certUri: string, callback: AsyncCallback<void>): void 298 299Uninstalls a user certificate through the specified device administrator application. This API uses an asynchronous callback to return the result. 300 301**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 302 303**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 304 305**Parameters** 306 307| Name | Type | Mandatory | Description | 308| -------- | ---------------------------------------- | ---- | ------------------------------- | 309| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application. | 310| certUri | string | Yes | Certificate URI, which is returned by **installUserCertificate()**. | 311| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | 312 313**Error codes** 314 315For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 316 317| ID| Error Message | 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**Example** 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 348Uninstalls a user certificate through the specified device administrator application. This API uses a promise to return the result. 349 350**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 351 352**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 353 354**Parameters** 355 356| Name | Type | Mandatory | Description | 357| ----- | ----------------------------------- | ---- | ------- | 358| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application.| 359| certUri | string | Yes | Certificate URI, which is returned by **installUserCertificate()**. | 360 361**Return value** 362 363| Type | Description | 364| --------------------- | ------------------------- | 365| Promise<void> | Promise that returns no value. An error object will be thrown if the operation fails.| 366 367**Error codes** 368 369For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 370 371| ID| Error Message | 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**Example** 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 401Sets the device power policy through the specified device administrator application. This API returns the result synchronously. If the operation is successful, **null** is returned. If the operation fails, an exception will be thrown. 402 403**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SETTINGS 404 405**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 406 407**Parameters** 408 409| Name | Type | Mandatory | Description | 410| -------- | ---------------------------------------- | ---- | ------------------------------- | 411| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application. | 412| powerScene | [PowerScene](#powerscene11) | Yes | Scenario to which the power policy applies. Currently, only the timeout scenario is supported. | 413| powerPolicy | [PowerPolicy](#powerpolicy11) | Yes | Power policy to set. | 414 415**Error codes** 416 417For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 418 419| ID| Error Message | 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**Example** 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 451Obtains the device power policy through the specified device administrator application. This API returns the result synchronously. If the operation is successful, the power policy obtained is returned. If the operation fails, an exception will be thrown. 452 453**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SETTINGS 454 455**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 456 457**Parameters** 458 459| Name | Type | Mandatory | Description | 460| -------- | ---------------------------------------- | ---- | ------------------------------- | 461| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application. | 462| powerScene | [PowerScene](#powerscene11) | Yes | Scenario to which the power policy applies. Currently, only the timeout scenario is supported. | 463 464**Return value** 465 466| Type | Description | Description | 467| ----- | ----------------------------------- |------------------------------- | 468| PowerPolicy | [PowerPolicy](#powerpolicy11) | Power policy obtained. | 469 470**Error codes** 471 472For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 473 474| ID| Error Message | 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**Example** 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 501Represents the power policy. 502 503**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 504 505| Name | Type | Mandatory| Description | 506| ----------- | --------| ----- | ------------------------------- | 507| powerPolicyAction | [PowerPolicyAction](#powerpolicyaction11) | Yes| Action to apply the power policy.| 508| delayTime | number | Yes| Delay time allowed.| 509 510## PowerScene<sup>11+</sup> 511 512Defines the scenario to which the power policy applies. 513 514**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 515 516| Name| Value| Description| 517| -------- | -------- | -------- | 518| TIME_OUT | 0 | Timeout scenario.| 519 520## PowerPolicyAction<sup>11+</sup> 521 522Enumerates the actions that can be performed to apply the power policy. 523 524**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 525 526| Name| Value| Description| 527| -------- | -------- | -------- | 528| NONE | 0 | No action is performed.| 529| AUTO_SUSPEND | 1 | Automatically enter the sleep mode.| 530| FORCE_SUSPEND | 2 | Forcibly enter the sleep mode.| 531| HIBERNATE | 3 | Enter the hibernation state. Currently, the power subsystem does not support this action.| 532| SHUTDOWN | 4 | Shut down the system.| 533