• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.power (Power Management)
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## Modules to Import
10
11```js
12import power from '@ohos.power';
13```
14
15## power.shutdown
16
17shutdown(reason: string): void
18
19Shuts down the system.
20
21**System API**: This is a system API.
22
23**Required permission**: ohos.permission.REBOOT
24
25**System capability:** SystemCapability.PowerManager.PowerManager.Core
26
27**Parameters**
28
29| Name   | Type    | Mandatory  | Description   |
30| ------ | ------ | ---- | ----- |
31| reason | string | Yes   | Reason for system shutdown.|
32
33**Error codes**
34
35For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
36
37| ID  | Error Message   |
38|---------|---------|
39| 4900101 | Operation failed. Cannot connect to service.|
40
41**Example**
42
43```js
44try {
45    power.shutdown('shutdown_test');
46} catch(err) {
47    console.error('shutdown failed, err: ' + err);
48}
49```
50
51## power.reboot<sup>9+</sup>
52
53reboot(reason: string): void
54
55Reboots the system.
56
57**System API**: This is a system API.
58
59**Required permission**: ohos.permission.REBOOT
60
61**System capability:** SystemCapability.PowerManager.PowerManager.Core
62
63**Parameters**
64
65| Name| Type  | Mandatory| Description      |
66| ------ | ------ | ---- | ---------- |
67| reason | string | Yes  | Reason for system reboot.|
68
69**Error codes**
70
71For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
72
73| ID  | Error Message   |
74|---------|---------|
75| 4900101 | Operation failed. Cannot connect to service.|
76
77**Example**
78
79```js
80try {
81    power.reboot('reboot_test');
82} catch(err) {
83    console.error('reboot failed, err: ' + err);
84}
85```
86
87## power.isActive<sup>9+</sup>
88
89isActive(): boolean
90
91Checks whether the current device is active.
92
93**System capability:** SystemCapability.PowerManager.PowerManager.Core
94
95**Error codes**
96
97For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
98
99| ID  | Error Message   |
100|---------|---------|
101| 4900101 | Operation failed. Cannot connect to service.|
102
103**Example**
104
105```js
106try {
107    var isActive = power.isActive();
108    console.info('power is active: ' + isActive);
109} catch(err) {
110    console.error('check active status failed, err: ' + err);
111}
112```
113
114## power.wakeup<sup>9+</sup>
115
116wakeup(detail: string): void
117
118Wakes up a device.
119
120**System API**: This is a system API.
121
122**System capability:** SystemCapability.PowerManager.PowerManager.Core
123
124**Parameters**
125
126| Name| Type  | Mandatory| Description      |
127| ------ | ------ | ---- | ---------- |
128| detail | string | Yes  | Reason for wakeup.|
129
130**Error codes**
131
132For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
133
134| ID  | Error Message   |
135|---------|---------|
136| 4900101 | Operation failed. Cannot connect to service.|
137
138**Example**
139
140```js
141try {
142    power.wakeup('wakeup_test');
143} catch(err) {
144    console.error('wakeup failed, err: ' + err);
145}
146```
147
148## power.suspend<sup>9+</sup>
149
150suspend(): void
151
152Hibernates a device.
153
154**System API**: This is a system API.
155
156**System capability:** SystemCapability.PowerManager.PowerManager.Core
157
158**Error codes**
159
160For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
161
162| ID  | Error Message   |
163|---------|---------|
164| 4900101 | Operation failed. Cannot connect to service.|
165
166**Example**
167
168```js
169try {
170    power.suspend();
171} catch(err) {
172    console.error('suspend failed, err: ' + err);
173}
174```
175
176## power.getPowerMode<sup>9+</sup>
177
178getPowerMode(): DevicePowerMode
179
180Obtains the power mode of this device.
181
182**System capability:** SystemCapability.PowerManager.PowerManager.Core
183
184**Return value**
185
186| Type                                | Description      |
187| ------------------------------------ | ---------- |
188| [DevicePowerMode](#devicepowermode9) | Power mode.|
189
190**Error codes**
191
192For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
193
194| ID  | Error Message   |
195|---------|---------|
196| 4900101 | Operation failed. Cannot connect to service.|
197
198**Example**
199
200```js
201try {
202    var mode = power.getPowerMode();
203    console.info('power mode: ' + mode);
204} catch(err) {
205    console.error('get power mode failed, err: ' + err);
206}
207```
208
209## power.setPowerMode<sup>9+</sup>
210
211setPowerMode(mode: DevicePowerMode, callback: AsyncCallback&lt;void&gt;): void
212
213Sets the power mode of this device. This API uses an asynchronous callback to return the result.
214
215**System API**: This is a system API.
216
217**Required permission**: ohos.permission.POWER_OPTIMIZATION
218
219**System capability:** SystemCapability.PowerManager.PowerManager.Core
220
221**Parameters**
222
223| Name  | Type                                | Mandatory| Description                                                        |
224| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
225| mode     | [DevicePowerMode](#devicepowermode9) | Yes  | Power mode.                                                  |
226| callback | AsyncCallback&lt;void&gt;            | Yes  | Callback used to return the result. If the power mode is successfully set, **err** is **undefined**; otherwise, **err** is an error object.|
227
228**Error codes**
229
230For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
231
232| ID  | Error Message   |
233|---------|---------|
234| 4900101 | Operation failed. Cannot connect to service.|
235
236**Example**
237
238```js
239power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE, err => {
240    if (typeof err === 'undefined') {
241        console.info('set power mode to MODE_PERFORMANCE');
242    } else {
243        console.error('set power mode failed, err: ' + err);
244    }
245});
246```
247
248## power.setPowerMode<sup>9+</sup>
249
250setPowerMode(mode: DevicePowerMode): Promise&lt;void&gt;
251
252Sets the power mode of this device. This API uses a promise to return the result.
253
254**System API**: This is a system API.
255
256**Required permission**: ohos.permission.POWER_OPTIMIZATION
257
258**System capability:** SystemCapability.PowerManager.PowerManager.Core
259
260**Parameters**
261
262| Name| Type                                | Mandatory| Description      |
263| ------ | ------------------------------------ | ---- | ---------- |
264| mode   | [DevicePowerMode](#devicepowermode9) | Yes  | Power mode.|
265
266**Return value**
267
268| Type               | Description                                  |
269| ------------------- | -------------------------------------- |
270| Promise&lt;void&gt; | Promise that returns no value.|
271
272**Error codes**
273
274For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
275
276| ID  | Error Message   |
277|---------|---------|
278| 4900101 | Operation failed. Cannot connect to service.|
279
280**Example**
281
282```js
283power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE)
284.then(() => {
285    console.info('set power mode to MODE_PERFORMANCE');
286})
287.catch(err => {
288    console.error('set power mode failed, err: ' + err);
289});
290```
291
292## power.rebootDevice<sup>(deprecated)</sup>
293
294rebootDevice(reason: string): void
295
296> **NOTE**<br>This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [power.reboot](#powerreboot9). The substitute API is available only for system applications.
297
298Reboots the system.
299
300**Required permission**: ohos.permission.REBOOT
301
302**System capability:** SystemCapability.PowerManager.PowerManager.Core
303
304**Parameters**
305
306| Name   | Type    | Mandatory  | Description   |
307| ------ | ------ | ---- | ----- |
308| reason | string | Yes   | Reason for system reboot.|
309
310**Example**
311
312```js
313power.rebootDevice('reboot_test');
314```
315
316## power.isScreenOn<sup>(deprecated)</sup>
317
318isScreenOn(callback: AsyncCallback&lt;boolean&gt;): void
319
320> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [power.isActive](#powerisactive9).
321
322Checks the screen status of the current device. This API uses an asynchronous callback to return the result.
323
324**System capability:** SystemCapability.PowerManager.PowerManager.Core
325
326**Parameters**
327
328| Name  | Type                        | Mandatory| Description                                                        |
329| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
330| callback | AsyncCallback&lt;boolean&gt; | Yes  | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the screen status obtained, where the value **true** indicates on and the value **false** indicates off. Otherwise, **err** is an error object.|
331
332**Example**
333
334```js
335power.isScreenOn((err, data) => {
336    if (typeof err === 'undefined') {
337        console.info('screen on status is ' + data);
338    } else {
339        console.error('check screen status failed, err: ' + err);
340    }
341})
342```
343
344## power.isScreenOn<sup>(deprecated)</sup>
345
346isScreenOn(): Promise&lt;boolean&gt;
347
348> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [power.isActive](#powerisactive9).
349
350Checks the screen status of the current device. This API uses a promise to return the result.
351
352**System capability:** SystemCapability.PowerManager.PowerManager.Core
353
354**Return value**
355| Type                  | Description                                              |
356| ---------------------- | -------------------------------------------------- |
357| Promise&lt;boolean&gt; | Promise used to return the result. The value **true** indicates that the screen is on, and the value **false** indicates the opposite.|
358
359**Example**
360
361```js
362power.isScreenOn()
363.then(data => {
364    console.info('screen on status is ' + data);
365})
366.catch(err => {
367    console.error('check screen status failed, err: ' + err);
368})
369```
370
371## DevicePowerMode<sup>9+</sup>
372
373Enumerates power modes.
374
375**System capability:** SystemCapability.PowerManager.PowerManager.Core
376
377| Name                   | Value  | Description                  |
378| ----------------------- | ---- | ---------------------- |
379| MODE_NORMAL             | 600  | Standard mode. It is the default value.|
380| MODE_POWER_SAVE         | 601  | Power saving mode.        |
381| MODE_PERFORMANCE        | 602  | Performance mode.        |
382| MODE_EXTREME_POWER_SAVE | 603  | Ultra power saving mode.    |
383