1# @ohos.enterprise.deviceSettings (Device Settings) 2 3The **deviceSettings** module provides APIs for setting enterprise devices, including setting and obtaining the screen-off time of a device. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 12. 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 that is enabled. For details, see [MDM Kit Development](../../mdm/mdm-kit-guide.md). 12 13## Modules to Import 14 15```ts 16import { deviceSettings } from '@kit.MDMKit'; 17``` 18 19## deviceSettings.setValue 20 21setValue(admin: Want, item: string, value: string): void 22 23Sets a device setting policy. 24 25**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SETTINGS 26 27**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 28 29**Parameters** 30 31| Name| Type | Mandatory| Description | 32| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 33| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 34| item | string | Yes | Type of the policy to set.<br>- **screenOff**: screen-off policy. For 2-in-1 devices, only the screen-off policy in battery mode can be set.<br>- **dateTime**: system time settings.<br>- **powerPolicy**: device power policy. For 2-in-1 devices, only the power policy in battery mode can be set.| 35| value | string | Yes | Policy to set.<br>If **item** is **screenOff**, **value** is the screen-off time, in ms.<br>If **item** is **dateTime**, **value** is the system time to set, in ms.<br>If **item** is **powerPolicy**, **value** is a JSON string in {"powerScene":xx,"powerPolicy":{"powerPolicyAction":xx,"delayTime":xx}} format. **powerScene** specifies the power policy scenario; **delayTime** specifies the delay time in ms (it cannot be set to 30000 ms); **powerPolicyAction** specifies the sleep policy.<br>The value of **powerScene** can be:<br>- **0**: timeout.<br>The value of **powerPolicyAction** can be:<br>- **0**: No action is performed.<br>- **1**: enter sleep mode automatically.<br>- **2**: forcibly enter sleep mode.<br>- **3**: enter sleep mode (not supported by the power subsystem currently).<br>- **4**: power off.| 36 37**Error codes** 38 39For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 40 41| ID| Error Message | 42| -------- | ------------------------------------------------------------ | 43| 9200001 | The application is not an administrator application of the device. | 44| 9200002 | The administrator application does not have permission to manage the device. | 45| 201 | Permission verification failed. The application does not have the permission required to call the API. | 46| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 47 48**Example** 49 50```ts 51import { Want } from '@kit.AbilityKit'; 52 53let wantTemp: Want = { 54 bundleName: 'com.example.myapplication', 55 abilityName: 'EntryAbility', 56}; 57 58try { 59 deviceSettings.setValue(wantTemp, 'screenOff', '3000'); 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.getValue 67 68getValue(admin: Want, item: string): string 69 70Obtains a device setting policy. 71 72**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_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 | EnterpriseAdminExtensionAbility. | 81| item | string | Yes | Type of the policy to set.<br>- **screenOff**: screen-off policy of a device. For a 2-in-1 device, only the screen-off policy in battery mode can be obtained.<br>- **dateTime**: system time settings.<br>- **powerPolicy**: device power policy. For 2-in-1 devices, only the power policy in battery mode can be obtained.| 82 83**Return value** 84 85| Type | Description | 86| ------ | ------------------------------------------------------------ | 87| string | Policy obtained.<br>If **item** is **screenOff**, the device screen-off time (in ms) is returned. For a 2-in-1 device, the device screen-off time (in ms) in battery mode is returned.<br>If **item** is **dateTime**, the system time (in ms) is returned.<br>If **item** is **powerPolicy**, the power policy is returned. For a 2-in-1 device, the power policy in battery mode is returned. The power policy a JSON string in {"powerScene":xx,"powerPolicy":{"powerPolicyAction":xx,"delayTime":xx}} format. **powerScene** indicates the power policy scenario, **delayTime** indicates the delay time (in ms), and **powerPolicyAction** indicates the sleep policy.<br>The value of **powerScene** can be:<br>- **0**: timeout.<br>The value of **powerPolicyAction** can be:<br>- **0**: No action is performed.<br>- **1**: enter sleep mode automatically.<br>- **2**: forcibly enter sleep mode.<br>- **3**: enter sleep mode (not supported by the power subsystem currently).<br>- **4**: power off.| 88 89**Error codes** 90 91For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 92 93| ID| Error Message | 94| -------- | ------------------------------------------------------------ | 95| 9200001 | The application is not an administrator application of the device. | 96| 9200002 | The administrator application does not have permission to manage the device. | 97| 201 | Permission verification failed. The application does not have the permission required to call the API. | 98| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 99 100**Example** 101 102```ts 103import { Want } from '@kit.AbilityKit'; 104 105let wantTemp: Want = { 106 bundleName: 'com.example.myapplication', 107 abilityName: 'EntryAbility', 108}; 109 110try { 111 let result: string = deviceSettings.getValue(wantTemp, 'screenOff'); 112 console.info(`Succeeded in getting screen off time, result : ${result}`); 113} catch (err) { 114 console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`); 115} 116``` 117