• 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 | If connecting to the service failed. |
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 | If connecting to the service failed. |
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. In the active state, the screen is on if the device has a screen and the device is not in sleep state if the device does not have a screen.
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 | If connecting to the service failed. |
102
103**Example**
104
105```js
106try {
107    let 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 | If connecting to the service failed. |
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(isImmediate?: boolean): void
151
152Hibernates a device.
153
154**System API**: This is a system API.
155
156**System capability:** SystemCapability.PowerManager.PowerManager.Core
157
158**Parameters**
159
160| Name| Type  | Mandatory| Description      |
161| ------ | ------ | ---- | ---------- |
162| 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.|
163
164
165**Error codes**
166
167For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
168
169| ID  | Error Message   |
170|---------|---------|
171| 4900101 | If connecting to the service failed. |
172
173**Example**
174
175```js
176try {
177    power.suspend();
178} catch(err) {
179    console.error('suspend failed, err: ' + err);
180}
181```
182
183## power.getPowerMode<sup>9+</sup>
184
185getPowerMode(): DevicePowerMode
186
187Obtains the power mode of this device.
188
189**System capability:** SystemCapability.PowerManager.PowerManager.Core
190
191**Return value**
192
193| Type                                | Description      |
194| ------------------------------------ | ---------- |
195| [DevicePowerMode](#devicepowermode9) | Power mode.|
196
197**Error codes**
198
199For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
200
201| ID  | Error Message   |
202|---------|---------|
203| 4900101 | If connecting to the service failed. |
204
205**Example**
206
207```js
208try {
209    let mode = power.getPowerMode();
210    console.info('power mode: ' + mode);
211} catch(err) {
212    console.error('get power mode failed, err: ' + err);
213}
214```
215
216## power.setPowerMode<sup>9+</sup>
217
218setPowerMode(mode: DevicePowerMode, callback: AsyncCallback&lt;void&gt;): void
219
220Sets the power mode of this device. This API uses an asynchronous callback to return the result.
221
222**System API**: This is a system API.
223
224**Required permission**: ohos.permission.POWER_OPTIMIZATION
225
226**System capability:** SystemCapability.PowerManager.PowerManager.Core
227
228**Parameters**
229
230| Name  | Type                                | Mandatory| Description                                                        |
231| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
232| mode     | [DevicePowerMode](#devicepowermode9) | Yes  | Power mode.                                                  |
233| 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.|
234
235**Error codes**
236
237For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
238
239| ID  | Error Message   |
240|---------|---------|
241| 4900101 | If connecting to the service failed. |
242
243**Example**
244
245```js
246power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE, (err: Error) => {
247    if (typeof err === 'undefined') {
248        console.info('set power mode to MODE_PERFORMANCE');
249    } else {
250        console.error('set power mode failed, err: ' + err);
251    }
252});
253```
254
255## power.setPowerMode<sup>9+</sup>
256
257setPowerMode(mode: DevicePowerMode): Promise&lt;void&gt;
258
259Sets the power mode of this device. This API uses a promise to return the result.
260
261**System API**: This is a system API.
262
263**Required permission**: ohos.permission.POWER_OPTIMIZATION
264
265**System capability:** SystemCapability.PowerManager.PowerManager.Core
266
267**Parameters**
268
269| Name| Type                                | Mandatory| Description      |
270| ------ | ------------------------------------ | ---- | ---------- |
271| mode   | [DevicePowerMode](#devicepowermode9) | Yes  | Power mode.|
272
273**Return value**
274
275| Type               | Description                                  |
276| ------------------- | -------------------------------------- |
277| Promise&lt;void&gt; | Promise that returns no value.|
278
279**Error codes**
280
281For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
282
283| ID  | Error Message   |
284|---------|---------|
285| 4900101 | If connecting to the service failed. |
286
287**Example**
288
289```js
290power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE)
291.then(() => {
292    console.info('set power mode to MODE_PERFORMANCE');
293})
294.catch((err : Error)=> {
295    console.error('set power mode failed, err: ' + err);
296});
297```
298
299## power.isStandby<sup>10+</sup>
300
301isStandby(): boolean
302
303Checks whether the device is in standby mode.
304
305**System capability:** SystemCapability.PowerManager.PowerManager.Core
306
307**Return value**
308
309| Type               | Description                                  |
310| ------------------- | -------------------------------------- |
311| boolean | The value **true** indicates that the device is in standby mode, and the value **false** indicates the opposite.|
312
313**Error codes**
314
315For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
316
317| ID  | Error Message   |
318|---------|---------|
319| 4900101 | If connecting to the service failed. |
320
321**Example**
322
323```js
324try {
325    let isStandby = power.isStandby();
326    console.info('device is in standby: ' + isStandby);
327} catch(err) {
328    console.error('check isStandby failed, err: ' + err);
329}
330```
331
332## power.rebootDevice<sup>(deprecated)</sup>
333
334rebootDevice(reason: string): void
335
336> **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.
337
338Reboots the system.
339
340**Required permission**: ohos.permission.REBOOT
341
342**System capability:** SystemCapability.PowerManager.PowerManager.Core
343
344**Parameters**
345
346| Name   | Type    | Mandatory  | Description   |
347| ------ | ------ | ---- | ----- |
348| reason | string | Yes   | Reason for system reboot.|
349
350**Example**
351
352```js
353power.rebootDevice('reboot_test');
354```
355
356## power.isScreenOn<sup>(deprecated)</sup>
357
358isScreenOn(callback: AsyncCallback&lt;boolean&gt;): void
359
360> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [power.isActive](#powerisactive9).
361
362Checks the screen status of the current device. This API uses an asynchronous callback to return the result.
363
364**System capability:** SystemCapability.PowerManager.PowerManager.Core
365
366**Parameters**
367
368| Name  | Type                        | Mandatory| Description                                                        |
369| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
370| 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.|
371
372**Example**
373
374```js
375power.isScreenOn((err: Error, data: boolean) => {
376    if (typeof err === 'undefined') {
377        console.info('screen on status is ' + data);
378    } else {
379        console.error('check screen status failed, err: ' + err);
380    }
381})
382```
383
384## power.isScreenOn<sup>(deprecated)</sup>
385
386isScreenOn(): Promise&lt;boolean&gt;
387
388> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [power.isActive](#powerisactive9).
389
390Checks the screen status of the current device. This API uses a promise to return the result.
391
392**System capability:** SystemCapability.PowerManager.PowerManager.Core
393
394**Return value**
395| Type                  | Description                                              |
396| ---------------------- | -------------------------------------------------- |
397| 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.|
398
399**Example**
400
401```js
402power.isScreenOn()
403.then((data: boolean) => {
404    console.info('screen on status is ' + data);
405})
406.catch((err: { code: number, message: string }) => {
407    console.error('check screen status failed, err: ' + err);
408})
409```
410
411## DevicePowerMode<sup>9+</sup>
412
413Enumerates power modes.
414
415**System capability:** SystemCapability.PowerManager.PowerManager.Core
416
417| Name                   | Value  | Description                  |
418| ----------------------- | ---- | ---------------------- |
419| MODE_NORMAL             | 600  | Standard mode. It is the default value.|
420| MODE_POWER_SAVE         | 601  | Power saving mode.        |
421| MODE_PERFORMANCE        | 602  | Performance mode.        |
422| MODE_EXTREME_POWER_SAVE | 603  | Ultra power saving mode.    |
423