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