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**Required permissions**: ohos.permission.POWER_MANAGER 105 106For API version 9 to 17, no permission is required to use this API. Since API version 18, this permission is required. 107 108**System capability**: SystemCapability.PowerManager.PowerManager.Core 109 110**Parameters** 111 112| Name| Type | Mandatory| Description | 113| ------ | ------ | ---- | ---------- | 114| detail | string | Yes | Wakeup reason. The value must be a string.| 115 116**Error codes** 117 118For details about the error codes, see [Power Manager Error Codes](errorcode-power.md). 119 120| ID | Error Message | 121|---------|---------| 122| 4900101 | Failed to connect to the service. | 123| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 124| 201 | Permission verification failed. The application does not have the permission required to call the API. | 125| 202 | Permission verification failed. A non-system application calls a system API. | 126 127**Example:** 128 129```js 130try { 131 power.wakeup('wakeup_test'); 132} catch(err) { 133 console.error('wakeup failed, err: ' + err); 134} 135``` 136 137## power.suspend<sup>9+</sup> 138 139suspend(isImmediate?: boolean): void 140 141Hibernates a device. 142 143**System API**: This is a system API. 144 145**Required permissions**: ohos.permission.POWER_MANAGER 146 147For API version 9 to 17, no permission is required to use this API. Since API version 18, this permission is required. 148 149**System capability**: SystemCapability.PowerManager.PowerManager.Core 150 151**Parameters** 152 153| Name| Type | Mandatory| Description | 154| ------ | ------ | ---- | ---------- | 155| 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.| 156 157 158**Error codes** 159 160For details about the error codes, see [Power Manager Error Codes](errorcode-power.md). 161 162| ID | Error Message | 163|---------|---------| 164| 4900101 | Failed to connect to the service. | 165| 201 | Permission verification failed. The application does not have the permission required to call the API. | 166| 202 | Permission verification failed. A non-system application calls a system API. | 167| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 168 169**Example:** 170 171```js 172try { 173 power.suspend(); 174} catch(err) { 175 console.error('suspend failed, err: ' + err); 176} 177``` 178 179## power.setPowerMode<sup>9+</sup> 180 181setPowerMode(mode: DevicePowerMode, callback: AsyncCallback<void>): void 182 183Sets the power mode of this device. This API uses an asynchronous callback to return the result. 184 185**System API**: This is a system API. 186 187**Required permission**: ohos.permission.POWER_OPTIMIZATION 188 189**System capability**: SystemCapability.PowerManager.PowerManager.Core 190 191**Parameters** 192 193| Name | Type | Mandatory| Description | 194| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 195| mode | DevicePowerMode | Yes | Power mode. The value must be an enum. | 196| 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.| 197 198**Error codes** 199 200For details about the error codes, see [Power Manager Error Codes](errorcode-power.md). 201 202| ID | Error Message | 203|---------|---------| 204| 4900101 | Failed to connect to the service. | 205| 401 | Parameter error. Possible causes: 1.Parameter verification failed. | 206| 201 | Permission verification failed. The application does not have the permission required to call the API. | 207| 202 | Permission verification failed. A non-system application calls a system API. | 208 209**Example:** 210 211```js 212power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE, (err: Error) => { 213 if (typeof err === 'undefined') { 214 console.info('set power mode to MODE_PERFORMANCE'); 215 } else { 216 console.error('set power mode failed, err: ' + err); 217 } 218}); 219``` 220 221## power.setPowerMode<sup>9+</sup> 222 223setPowerMode(mode: DevicePowerMode): Promise<void> 224 225Sets the power mode of this device. This API uses a promise to return the result. 226 227**System API**: This is a system API. 228 229**Required permission**: ohos.permission.POWER_OPTIMIZATION 230 231**System capability**: SystemCapability.PowerManager.PowerManager.Core 232 233**Parameters** 234 235| Name| Type | Mandatory| Description | 236| ------ | ------------------------------------ | ---- | ---------- | 237| mode | DevicePowerMode | Yes | Power mode. The value must be an enum.| 238 239**Return value** 240 241| Type | Description | 242| ------------------- | -------------------------------------- | 243| Promise<void> | Promise that returns no value.| 244 245**Error codes** 246 247For details about the error codes, see [Power Manager Error Codes](errorcode-power.md). 248 249| ID | Error Message | 250|---------|---------| 251| 4900101 | Failed to connect to the service. | 252| 401 | Parameter error. Possible causes: 1.Parameter verification failed. | 253| 201 | Permission verification failed. The application does not have the permission required to call the API. | 254| 202 | Permission verification failed. A non-system application calls a system API. | 255 256**Example:** 257 258```js 259power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE) 260.then(() => { 261 console.info('set power mode to MODE_PERFORMANCE'); 262}) 263.catch((err : Error)=> { 264 console.error('set power mode failed, err: ' + err); 265}); 266``` 267 268## power.setScreenOffTime<sup>12+</sup> 269 270setScreenOffTime(timeout: number): void 271 272Set the screen-off timeout duration. 273 274**System API**: This is a system API. 275 276**Required permissions**: ohos.permission.POWER_MANAGER 277 278For API version 12 to 17, no permission is required to use this API. Since API version 18, this permission is required. 279 280**System capability**: SystemCapability.PowerManager.PowerManager.Core 281 282**Parameters** 283 284| Name | Type | Mandatory | Description | 285| ------ | ------ | ---- | ----- | 286| 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.| 287 288**Error codes** 289 290For details about the error codes, see [Power Manager Error Codes](errorcode-power.md). 291 292| ID | Error Message | 293|---------|---------| 294| 4900101 | Failed to connect to the service. | 295| 401 | Parameter error. Possible causes: 1. Parameter verification failed. | 296| 201 | Permission verification failed. The application does not have the permission required to call the API. | 297| 202 | Permission verification failed. A non-system application calls a system API. | 298 299**Example:** 300 301```js 302try { 303 power.setScreenOffTime(30000); 304} catch(err) { 305 console.error('set screen off time failed, err: ' + err); 306} 307``` 308 309## power.hibernate<sup>12+</sup> 310 311hibernate(clearMemory: boolean): void 312 313Hibernates a device. 314 315**System API**: This is a system API. 316 317**Required permissions**: ohos.permission.POWER_MANAGER 318 319For API version 12 to 17, no permission is required to use this API. Since API version 18, this permission is required. 320 321**System capability**: SystemCapability.PowerManager.PowerManager.Core 322 323**Parameters** 324 325| Name | Type | Mandatory | Description | 326| ------ | ------ | ---- | ----- | 327| 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.| 328 329**Error codes** 330 331For details about the error codes, see [Power Manager Error Codes](errorcode-power.md). 332 333| ID | Error Message | 334|---------|---------| 335| 4900101 | Failed to connect to the service. | 336| 201 | Permission verification failed. The application does not have the permission required to call the API. | 337| 202 | Permission verification failed. A non-system application calls a system API. | 338| 401 | Parameter error. Possible causes: 1.Incorrect parameter types. | 339 340**Example:** 341 342```js 343try { 344 power.hibernate(true); 345} catch(err) { 346 console.error('hibernate failed, err: ' + err); 347} 348``` 349