1# @ohos.enterprise.deviceSettings (Device Settings) 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 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](../../mdm/mdm-kit-guide.md#introduction) that is enabled. 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 | Device administrator application. | 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 2in1 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'; 52let wantTemp: Want = { 53 bundleName: 'com.example.myapplication', 54 abilityName: 'EntryAbility', 55}; 56 57try { 58 deviceSettings.setValue(wantTemp, 'screenOff', '3000'); 59 console.info(`Succeeded in setting screen off time.`); 60} catch (err) { 61 console.error(`Failed to set screen off time. Code: ${err.code}, message: ${err.message}`); 62} 63``` 64 65## deviceSettings.getValue 66 67getValue(admin: Want, item: string): string 68 69Obtains a device setting policy. 70 71**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SETTINGS 72 73**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 74 75**Parameters** 76 77| Name| Type | Mandatory| Description | 78| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 79| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Device administrator application. | 80| item | string | Yes | Type of the device setting policy to obtain.<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.| 81 82**Return value** 83 84| Type | Description | 85| ------ | ------------------------------------------------------------ | 86| 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 sleep policy can be any of the following:<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.| 87 88**Error codes** 89 90For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 91 92| ID| Error Message | 93| -------- | ------------------------------------------------------------ | 94| 9200001 | The application is not an administrator application of the device. | 95| 9200002 | The administrator application does not have permission to manage the device. | 96| 201 | Permission verification failed. The application does not have the permission required to call the API. | 97| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 98 99**Example** 100 101```ts 102import { Want } from '@kit.AbilityKit'; 103let wantTemp: Want = { 104 bundleName: 'com.example.myapplication', 105 abilityName: 'EntryAbility', 106}; 107 108try { 109 let result: string = deviceSettings.getValue(wantTemp, 'screenOff'); 110 console.info(`Succeeded in getting screen off time, result : ${result}`); 111} catch (err) { 112 console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`); 113} 114``` 115