1# @ohos.power (Power Management) (System API)
2
3The **power** module provides APIs for rebooting and shutting down the system, as well as querying the screen status.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.power (Power Management)](js-apis-power.md).
10
11## Modules to Import
12
13```js
14import {power} from '@kit.BasicServicesKit';
15```
16
17## power.shutdown
18
19shutdown(reason: string): void
20
21Shuts down the system.
22
23**System API**: This is a system API.
24
25**Required permission**: ohos.permission.REBOOT
26
27**System capability:** SystemCapability.PowerManager.PowerManager.Core
28
29**Parameters**
30
31| Name   | Type    | Mandatory  | Description   |
32| ------ | ------ | ---- | ----- |
33| reason | string | Yes   | Shutdown reason. The value must be a string.|
34
35**Error codes**
36
37For details about the error codes, see [Power Manager Error Codes](errorcode-power.md).
38
39| ID  | Error Message   |
40|---------|---------|
41| 4900101 | Failed to connect to the service. |
42| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
43| 201     | Permission verification failed. The application does not have the permission required to call the API. |
44| 202     | Permission verification failed. A non-system application calls a system API.  |
45
46
47**Example:**
48
49```js
50try {
51    power.shutdown('shutdown_test');
52} catch(err) {
53    console.error('shutdown failed, err: ' + err);
54}
55```
56
57## power.reboot<sup>9+</sup>
58
59reboot(reason: string): void
60
61The device is restarted.
62
63**System API**: This is a system API.
64
65**Required permission**: ohos.permission.REBOOT
66
67**System capability:** SystemCapability.PowerManager.PowerManager.Core
68
69**Parameters**
70
71| Name| Type  | Mandatory| Description      |
72| ------ | ------ | ---- | ---------- |
73| reason | string | Yes  | Restart reason. The value must be a string.|
74
75**Error codes**
76
77For details about the error codes, see [Power Manager Error Codes](errorcode-power.md).
78
79| ID  | Error Message   |
80|---------|---------|
81| 4900101 | Failed to connect to the service. |
82| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
83| 201     | Permission verification failed. The application does not have the permission required to call the API. |
84| 202     | Permission verification failed. A non-system application calls a system API.  |
85
86**Example:**
87
88```js
89try {
90    power.reboot('reboot_test');
91} catch(err) {
92    console.error('reboot failed, err: ' + err);
93}
94```
95
96## power.wakeup<sup>9+</sup>
97
98wakeup(detail: string): void
99
100Wakes up a device.
101
102**System API**: This is a system API.
103
104**System capability:** SystemCapability.PowerManager.PowerManager.Core
105
106**Parameters**
107
108| Name| Type  | Mandatory| Description      |
109| ------ | ------ | ---- | ---------- |
110| detail | string | Yes  | Wakeup reason. The value must be a string.|
111
112**Error codes**
113
114For details about the error codes, see [Power Manager Error Codes](errorcode-power.md).
115
116| ID  | Error Message   |
117|---------|---------|
118| 4900101 | Failed to connect to the service. |
119| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
120| 202     | Permission verification failed. A non-system application calls a system API.  |
121
122**Example:**
123
124```js
125try {
126    power.wakeup('wakeup_test');
127} catch(err) {
128    console.error('wakeup failed, err: ' + err);
129}
130```
131
132## power.suspend<sup>9+</sup>
133
134suspend(isImmediate?: boolean): void
135
136Hibernates a device.
137
138**System API**: This is a system API.
139
140**System capability:** SystemCapability.PowerManager.PowerManager.Core
141
142**Parameters**
143
144| Name| Type  | Mandatory| Description      |
145| ------ | ------ | ---- | ---------- |
146| isImmediate<sup>10+</sup> | boolean |  No | Whether to hibernate a device immediately. If this parameter is not specified, the default value **false** is used. The system automatically determines when to enter the hibernation state.<br>**NOTE**: This parameter is supported since API version 10.|
147
148
149**Error codes**
150
151For details about the error codes, see [Power Manager Error Codes](errorcode-power.md).
152
153| ID  | Error Message   |
154|---------|---------|
155| 4900101 | Failed to connect to the service. |
156| 202     | Permission verification failed. A non-system application calls a system API.  |
157| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
158
159**Example:**
160
161```js
162try {
163    power.suspend();
164} catch(err) {
165    console.error('suspend failed, err: ' + err);
166}
167```
168
169## power.setPowerMode<sup>9+</sup>
170
171setPowerMode(mode: DevicePowerMode, callback: AsyncCallback&lt;void&gt;): void
172
173Sets the power mode of this device. This API uses an asynchronous callback to return the result.
174
175**System API**: This is a system API.
176
177**Required permission**: ohos.permission.POWER_OPTIMIZATION
178
179**System capability:** SystemCapability.PowerManager.PowerManager.Core
180
181**Parameters**
182
183| Name  | Type                                | Mandatory| Description                                                        |
184| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
185| mode     | DevicePowerMode | Yes  | Power mode. The value must be an enum.                                                  |
186| callback | AsyncCallback&lt;void&gt;            | Yes  | Callback invoked to return the result.<br> If the power mode is successfully set, **err** is **undefined**; otherwise, **err** is an error object.|
187
188**Error codes**
189
190For details about the error codes, see [Power Manager Error Codes](errorcode-power.md).
191
192| ID  | Error Message   |
193|---------|---------|
194| 4900101 | Failed to connect to the service. |
195| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
196| 201     | Permission verification failed. The application does not have the permission required to call the API. |
197| 202     | Permission verification failed. A non-system application calls a system API.  |
198
199**Example:**
200
201```js
202power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE, (err: Error) => {
203    if (typeof err === 'undefined') {
204        console.info('set power mode to MODE_PERFORMANCE');
205    } else {
206        console.error('set power mode failed, err: ' + err);
207    }
208});
209```
210
211## power.setPowerMode<sup>9+</sup>
212
213setPowerMode(mode: DevicePowerMode): Promise&lt;void&gt;
214
215Sets the power mode of this device. This API uses a promise to return the result.
216
217**System API**: This is a system API.
218
219**Required permission**: ohos.permission.POWER_OPTIMIZATION
220
221**System capability:** SystemCapability.PowerManager.PowerManager.Core
222
223**Parameters**
224
225| Name| Type                                | Mandatory| Description      |
226| ------ | ------------------------------------ | ---- | ---------- |
227| mode   | DevicePowerMode | Yes  | Power mode. The value must be an enum.|
228
229**Return value**
230
231| Type               | Description                                  |
232| ------------------- | -------------------------------------- |
233| Promise&lt;void&gt; | Promise that returns no value.|
234
235**Error codes**
236
237For details about the error codes, see [Power Manager Error Codes](errorcode-power.md).
238
239| ID  | Error Message   |
240|---------|---------|
241| 4900101 | Failed to connect to the service. |
242| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
243| 201     | Permission verification failed. The application does not have the permission required to call the API. |
244| 202     | Permission verification failed. A non-system application calls a system API.  |
245
246**Example:**
247
248```js
249power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE)
250.then(() => {
251    console.info('set power mode to MODE_PERFORMANCE');
252})
253.catch((err : Error)=> {
254    console.error('set power mode failed, err: ' + err);
255});
256```
257
258## power.setScreenOffTime<sup>12+</sup>
259
260setScreenOffTime(timeout: number): void
261
262Set the screen-off timeout duration.
263
264**System API**: This is a system API.
265
266**System capability:** SystemCapability.PowerManager.PowerManager.Core
267
268**Parameters**
269
270| Name   | Type    | Mandatory  | Description   |
271| ------ | ------ | ---- | ----- |
272| timeout | number | Yes   | Screen-off timeout duration, in milliseconds. A value greater than **0** indicates the specified timeout duration is used, and the value **-1** indicates that the default timeout duration is used. Other values are invalid.|
273
274**Error codes**
275
276For details about the error codes, see [Power Manager Error Codes](errorcode-power.md).
277
278| ID  | Error Message   |
279|---------|---------|
280| 4900101 | Failed to connect to the service. |
281| 401     | Parameter error. Possible causes: 1. Parameter verification failed. |
282| 202     | Permission verification failed. A non-system application calls a system API.  |
283
284**Example:**
285
286```js
287try {
288    power.setScreenOffTime(30000);
289} catch(err) {
290    console.error('set screen off time failed, err: ' + err);
291}
292```
293
294## power.hibernate<sup>12+</sup>
295
296hibernate(clearMemory: boolean): void
297
298Hibernates a device.
299
300**System API**: This is a system API.
301
302**System capability:** SystemCapability.PowerManager.PowerManager.Core
303
304**Parameters**
305
306| Name   | Type    | Mandatory  | Description   |
307| ------ | ------ | ---- | ----- |
308| clearMemory | boolean | Yes   | Whether to clear the memory. The value **true** means to clear the memory before the system enters the hibernation state, and the value **false** means the opposite.|
309
310**Error codes**
311
312For details about the error codes, see [Power Manager Error Codes](errorcode-power.md).
313
314| ID  | Error Message   |
315|---------|---------|
316| 4900101 | Failed to connect to the service. |
317| 202     | Permission verification failed. A non-system application calls a system API.  |
318| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
319
320**Example:**
321
322```js
323try {
324    power.hibernate(true);
325} catch(err) {
326    console.error('hibernate failed, err: ' + err);
327}
328```
329