1# @ohos.power (Power Management) (System API) 2 3<!--Kit: Basic Services Kit--> 4<!--Subsystem: PowerManager--> 5<!--Owner: @zhang-yinglie; @volcano_wang--> 6<!--Designer: @wangyantian0--> 7<!--Tester: @alien0208--> 8<!--Adviser: @w_Machine_cc--> 9 10The **power** module provides APIs for rebooting and shutting down the system, as well as querying the screen status. 11 12> **NOTE** 13> 14> 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. 15> 16> 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). 17 18## Modules to Import 19 20```js 21import {power} from '@kit.BasicServicesKit'; 22``` 23 24## power.shutdown 25 26shutdown(reason: string): void 27 28Shuts down the system. 29 30**System API**: This is a system API. 31 32**Required permission**: ohos.permission.REBOOT 33 34**System capability**: SystemCapability.PowerManager.PowerManager.Core 35 36**Parameters** 37 38| Name | Type | Mandatory | Description | 39| ------ | ------ | ---- | ----- | 40| reason | string | Yes | Shutdown reason. The value must be a string.| 41 42**Error codes** 43 44For details about the error codes, see [Power Manager Error Codes]errorcode-power.md) and [Universal Error Codes](../errorcode-universal.md). 45 46| ID | Error Message | 47|---------|---------| 48| 4900101 | Failed to connect to the service. | 49| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 50| 201 | Permission verification failed. The application does not have the permission required to call the API. | 51| 202 | Permission verification failed. A non-system application calls a system API. | 52 53 54**Example:** 55 56```js 57try { 58 power.shutdown('shutdown_test'); 59} catch(err) { 60 console.error('shutdown failed, err: ' + err); 61} 62``` 63 64## power.reboot<sup>9+</sup> 65 66reboot(reason: string): void 67 68The device is restarted. 69 70**System API**: This is a system API. 71 72**Required permission**: ohos.permission.REBOOT 73 74**System capability**: SystemCapability.PowerManager.PowerManager.Core 75 76**Parameters** 77 78| Name| Type | Mandatory| Description | 79| ------ | ------ | ---- | ---------- | 80| reason | string | Yes | Restart reason. The value must be a string.| 81 82**Error codes** 83 84For details about the error codes, see [Power Manager Error Codes]errorcode-power.md) and [Universal Error Codes](../errorcode-universal.md). 85 86| ID | Error Message | 87|---------|---------| 88| 4900101 | Failed to connect to the service. | 89| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 90| 201 | Permission verification failed. The application does not have the permission required to call the API. | 91| 202 | Permission verification failed. A non-system application calls a system API. | 92 93**Example:** 94 95```js 96try { 97 power.reboot('reboot_test'); 98} catch(err) { 99 console.error('reboot failed, err: ' + err); 100} 101``` 102 103## power.wakeup<sup>9+</sup> 104 105wakeup(detail: string): void 106 107Wakes up a device. 108 109**System API**: This is a system API. 110 111**Required permissions**: ohos.permission.POWER_MANAGER 112 113For API version 9 to 18, no permission is required; since API version 19, this permission is required. 114 115**System capability**: SystemCapability.PowerManager.PowerManager.Core 116 117**Parameters** 118 119| Name| Type | Mandatory| Description | 120| ------ | ------ | ---- | ---------- | 121| detail | string | Yes | Wakeup reason. The value must be a string.| 122 123**Error codes** 124 125For details about the error codes, see [Power Manager Error Codes]errorcode-power.md) and [Universal Error Codes](../errorcode-universal.md). 126 127| ID | Error Message | 128|---------|---------| 129| 4900101 | Failed to connect to the service. | 130| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 131| 201 | Permission verification failed. The application does not have the permission required to call the API. | 132| 202 | Permission verification failed. A non-system application calls a system API. | 133 134**Example:** 135 136```js 137try { 138 power.wakeup('wakeup_test'); 139} catch(err) { 140 console.error('wakeup failed, err: ' + err); 141} 142``` 143 144## power.suspend<sup>9+</sup> 145 146suspend(isImmediate?: boolean): void 147 148Hibernates a device. 149 150**System API**: This is a system API. 151 152**Required permissions**: ohos.permission.POWER_MANAGER 153 154For API version 9 to 18, no permission is required; since API version 19, this permission is required. 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 after the screen is turned off. The value **true** indicates that the device is hibernated immediately; **false** indicates that the system controls when the device is hibernated. If this parameter is not set, the default value **false** is used. If you only want to turn off the screen, you are advised not to set this parameter.<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]errorcode-power.md) and [Universal Error Codes](../errorcode-universal.md). 168 169| ID | Error Message | 170|---------|---------| 171| 4900101 | Failed to connect to the service. | 172| 201 | Permission verification failed. The application does not have the permission required to call the API. | 173| 202 | Permission verification failed. A non-system application calls a system API. | 174| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 175 176**Example:** 177 178```js 179try { 180 power.suspend(); 181} catch(err) { 182 console.error('suspend failed, err: ' + err); 183} 184``` 185 186## power.setPowerMode<sup>9+</sup> 187 188setPowerMode(mode: DevicePowerMode, callback: AsyncCallback<void>): void 189 190Sets the power mode of this device. This API uses an asynchronous callback to return the result. 191 192**System API**: This is a system API. 193 194**Required permission**: ohos.permission.POWER_OPTIMIZATION 195 196**System capability**: SystemCapability.PowerManager.PowerManager.Core 197 198**Parameters** 199 200| Name | Type | Mandatory| Description | 201| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 202| mode | DevicePowerMode | Yes | Power mode. The value must be an enum. | 203| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.<br> If the power mode is successfully set, **err** is **undefined**; otherwise, **err** is an error object.| 204 205**Error codes** 206 207For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 208 209| ID | Error Message | 210|---------|---------| 211| 401 | Parameter error. Possible causes: 1.Parameter verification failed. | 212| 201 | Permission verification failed. The application does not have the permission required to call the API. | 213| 202 | Permission verification failed. A non-system application calls a system API. | 214 215**Example:** 216 217```js 218power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE, (err: Error) => { 219 if (typeof err === 'undefined') { 220 console.info('set power mode to MODE_PERFORMANCE'); 221 } else { 222 console.error('set power mode failed, err: ' + err); 223 } 224}); 225``` 226 227## power.setPowerMode<sup>9+</sup> 228 229setPowerMode(mode: DevicePowerMode): Promise<void> 230 231Sets the power mode of this device. This API uses a promise to return the result. 232 233**System API**: This is a system API. 234 235**Required permission**: ohos.permission.POWER_OPTIMIZATION 236 237**System capability**: SystemCapability.PowerManager.PowerManager.Core 238 239**Parameters** 240 241| Name| Type | Mandatory| Description | 242| ------ | ------------------------------------ | ---- | ---------- | 243| mode | DevicePowerMode | Yes | Power mode. The value must be an enum.| 244 245**Return value** 246 247| Type | Description | 248| ------------------- | -------------------------------------- | 249| Promise<void> | Promise that returns no value.| 250 251**Error codes** 252 253For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 254 255| ID | Error Message | 256|---------|---------| 257| 401 | Parameter error. Possible causes: 1.Parameter verification failed. | 258| 201 | Permission verification failed. The application does not have the permission required to call the API. | 259| 202 | Permission verification failed. A non-system application calls a system API. | 260 261**Example:** 262 263```js 264power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE) 265.then(() => { 266 console.info('set power mode to MODE_PERFORMANCE'); 267}) 268.catch((err : Error)=> { 269 console.error('set power mode failed, err: ' + err); 270}); 271``` 272 273## power.setScreenOffTime<sup>12+</sup> 274 275setScreenOffTime(timeout: number): void 276 277Set the screen-off timeout duration. 278 279**System API**: This is a system API. 280 281**Required permissions**: ohos.permission.POWER_MANAGER 282 283For API version 12 to 18, no permission is required; since API version 19, this permission is required. 284 285**System capability**: SystemCapability.PowerManager.PowerManager.Core 286 287**Parameters** 288 289| Name | Type | Mandatory | Description | 290| ------ | ------ | ---- | ----- | 291| 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.| 292 293**Error codes** 294 295For details about the error codes, see [Power Manager Error Codes]errorcode-power.md) and [Universal Error Codes](../errorcode-universal.md). 296 297| ID | Error Message | 298|---------|---------| 299| 4900101 | Failed to connect to the service. | 300| 401 | Parameter error. Possible causes: 1. Parameter verification failed. | 301| 201 | Permission verification failed. The application does not have the permission required to call the API. | 302| 202 | Permission verification failed. A non-system application calls a system API. | 303 304**Example:** 305 306```js 307try { 308 power.setScreenOffTime(30000); 309} catch(err) { 310 console.error('set screen off time failed, err: ' + err); 311} 312``` 313 314## power.hibernate<sup>12+</sup> 315 316hibernate(clearMemory: boolean): void 317 318Hibernates a device. 319 320**System API**: This is a system API. 321 322**Required permissions**: ohos.permission.POWER_MANAGER 323 324For API version 12 to 18, no permission is required; since API version 19, this permission is required. 325 326**System capability**: SystemCapability.PowerManager.PowerManager.Core 327 328**Parameters** 329 330| Name | Type | Mandatory | Description | 331| ------ | ------ | ---- | ----- | 332| 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.| 333 334**Error codes** 335 336For details about the error codes, see [Power Manager Error Codes]errorcode-power.md) and [Universal Error Codes](../errorcode-universal.md). 337 338| ID | Error Message | 339|---------|---------| 340| 4900101 | Failed to connect to the service. | 341| 201 | Permission verification failed. The application does not have the permission required to call the API. | 342| 202 | Permission verification failed. A non-system application calls a system API. | 343| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 344 345**Example:** 346 347```js 348try { 349 power.hibernate(true); 350} catch(err) { 351 console.error('hibernate failed, err: ' + err); 352} 353``` 354 355## power.refreshActivity<sup>20+</sup> 356 357refreshActivity(reason: string): void 358 359Refreshes the device activity status (for example, resetting the screen-off time). 360This API takes effect only when the device is active. For details about the device activity status, see [power.isActive](js-apis-power.md#powerisactive9). 361 362**System API**: This is a system API. 363 364**Required permissions**: ohos.permission.REFRESH_USER_ACTION 365 366**System capability**: SystemCapability.PowerManager.PowerManager.Core 367 368**Parameters** 369 370| Name | Type | Mandatory | Description | 371| ------ | ------ | ---- | ----- | 372| reason | string | Yes | Reason for refreshing the device activity status. The value must be a string.| 373 374**Error codes** 375 376For details about the error codes, see [Power Manager Error Codes]errorcode-power.md) and [Universal Error Codes](../errorcode-universal.md). 377 378| ID | Error Message | 379|---------|---------| 380| 4900101 | Failed to connect to the service. | 381| 4900201 |The device activity is being refreshed too frequently; the minimum time interval is 100 ms. | 382| 201 | Permission verification failed. The application does not have the permission required to call the API. | 383| 202 | Permission verification failed. A non-system application calls a system API. | 384 385**Example:** 386 387```js 388try { 389 power.refreshActivity('refreshActivity_test'); 390} catch(err) { 391 console.error('refreshActivity failed, err: ' + err); 392} 393``` 394