@ohos.power (Power Management) (System API)

The power module provides APIs for rebooting and shutting down the system, as well as querying the screen status.

NOTE

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.

This topic describes only the system APIs provided by the module. For details about its public APIs, see @ohos.power (Power Management).

Modules to Import

import {power} from '@kit.BasicServicesKit';

power.shutdown

shutdown(reason: string): void

Shuts down the system.

System API: This is a system API.

Required permissions: ohos.permission.REBOOT

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
reason	string	Yes	Shutdown reason. The value must be a string.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
401	Parameter error. Possible causes: 1.Incorrect parameter types.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

try {
    power.shutdown('shutdown_test');
} catch(err) {
    console.error('shutdown failed, err: ' + err);
}

power.reboot⁹⁺

reboot(reason: string): void

Reboots a device.

System API: This is a system API.

Required permissions: ohos.permission.REBOOT

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
reason	string	Yes	Restart reason. For example, "updater" indicates entering the updater mode after the restart. If the parameter is not specified, the system enters the normal mode after the restart.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
401	Parameter error. Possible causes: 1.Incorrect parameter types.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

try {
    power.reboot('reboot_test');
} catch(err) {
    console.error('reboot failed, err: ' + err);
}

power.wakeup⁹⁺

wakeup(detail: string): void

Wakes up a device.

System API: This is a system API.

Required permissions: ohos.permission.POWER_MANAGER

For API version 9 to 18, no permission is required; since API version 19, this permission is required.

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
detail	string	Yes	Wakeup reason. The value must be a string.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
401	Parameter error. Possible causes: 1.Incorrect parameter types.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

try {
    power.wakeup('wakeup_test');
} catch(err) {
    console.error('wakeup failed, err: ' + err);
}

power.suspend⁹⁺

suspend(isImmediate?: boolean): void

Enables a device to enter the sleep state.

System API: This is a system API.

Required permissions: ohos.permission.POWER_MANAGER

For API version 9 to 18, no permission is required; since API version 19, this permission is required.

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
isImmediate10+	boolean	No	Whether the device enters the sleep state immediately. The value true indicates that the device enters the sleep state immediately after the screen is turned off; false indicates that the system controls when the device enters the sleep state. 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. NOTE: This parameter is supported since API version 10.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Parameter verification failed.

Example

try {
    power.suspend();
} catch(err) {
    console.error('suspend failed, err: ' + err);
}

power.setPowerMode⁹⁺

setPowerMode(mode: DevicePowerMode, callback: AsyncCallback<void>): void

Sets the power mode of a device. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.POWER_OPTIMIZATION

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
mode	DevicePowerMode	Yes	Power mode. The value must be an enum.
callback	AsyncCallback<void>	Yes	Callback invoked to return the result. If the power mode is successfully set, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900301	Setting the power mode failed.
401	Parameter error. Possible causes: 1.Parameter verification failed.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE, (err: Error) => {
    if (typeof err === 'undefined') {
        console.info('set power mode to MODE_PERFORMANCE');
    } else {
        console.error('set power mode failed, err: ' + err);
    }
});

power.setPowerMode⁹⁺

setPowerMode(mode: DevicePowerMode): Promise<void>

Sets the power mode of a device. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.POWER_OPTIMIZATION

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
mode	DevicePowerMode	Yes	Power mode. The value must be an enum.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900301	Setting the power mode failed.
401	Parameter error. Possible causes: 1.Parameter verification failed.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE)
.then(() => {
    console.info('set power mode to MODE_PERFORMANCE');
})
.catch((err : Error)=> {
    console.error('set power mode failed, err: ' + err);
});

power.setScreenOffTime¹²⁺

setScreenOffTime(timeout: number): void

Sets the screen-off timeout duration.

System API: This is a system API.

Required permissions: ohos.permission.POWER_MANAGER

For API version 12 to 18, no permission is required; since API version 19, this permission is required.

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
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.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
401	Parameter error. Possible causes: 1. Parameter verification failed.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

try {
    power.setScreenOffTime(30000);
} catch(err) {
    console.error('set screen off time failed, err: ' + err);
}

power.hibernate¹²⁺

hibernate(clearMemory: boolean): void

Hibernates a device.

System API: This is a system API.

Required permissions: ohos.permission.POWER_MANAGER

For API version 12 to 18, no permission is required; since API version 19, this permission is required.

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
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.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Parameter verification failed.

Example

try {
    power.hibernate(true);
} catch(err) {
    console.error('hibernate failed, err: ' + err);
}

power.refreshActivity²⁰⁺

refreshActivity(reason: string): void

Refreshes the device activity status (for example, resetting the screen-off time).

This API takes effect only when the device is active. For details about the device activity status, see power.isActive.

System API: This is a system API.

Required permissions: ohos.permission.REFRESH_USER_ACTION

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
reason	string	Yes	Reason for refreshing the device activity status. The value must be a string.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
4900201	The device activity is being refreshed too frequently; the minimum time interval is 100 ms.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

try {
    power.refreshActivity('refreshActivity_test');
} catch(err) {
    console.error('refreshActivity failed, err: ' + err);
}

power.setPowerKeyFilteringStrategy²¹⁺

setPowerKeyFilteringStrategy(strategy: PowerKeyFilteringStrategy): void

Sets the power key filtering strategy. After the power service subscribes to the power key event, this API is used to configure the processing mode of this event.

For details about the power key filtering strategy, see power.PowerKeyFilteringStrategy.

System API: This is a system API.

Required permissions: ohos.permission.POWER_MANAGER

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
strategy	PowerKeyFilteringStrategy	Yes	Power key filtering strategy. The value must be of the enum type.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

try {
    power.setPowerKeyFilteringStrategy(power.PowerKeyFilteringStrategy.LONG_PRESS_FILTERING_ONCE);
} catch(err) {
    console.error('setPowerKeyFilteringStrategy failed, err: ' + err);
}

power.registerShutdownCallback²³⁺

registerShutdownCallback(callback: Callback<boolean>): void

Registers a callback to be invoked when the device is shut down or rebooted. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.REBOOT

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<boolean>	Yes	Callback used to return the result. The value true indicates that the device is rebooted, and false indicates that the device is shut down.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

try {
    power.registerShutdownCallback((isReboot: boolean) => {
        console.info('device shutdown is: ' + isReboot);
    });
    console.info('register shutdown callback success.');
} catch(err) {
    console.error('register shutdown callback failed, err: ' + err);
}

power.unregisterShutdownCallback²³⁺

unregisterShutdownCallback(callback?: Callback<void>): void

Unregisters the callback to be invoked when the device is shut down or rebooted. This API uses a callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.REBOOT

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<void>	No	Callback that returns no value.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

try {
    power.unregisterShutdownCallback(() => {
        console.info('unsubscribe shutdown success.');
    });
    console.info('unregister shutdown callback success.');
} catch(err) {
    console.error('unregister shutdown callback failed, err: ' + err);
}

power.getPowerConfig

getPowerConfig(sceneName: string): string

Query the power configuration value for a given scene name.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Required permissions: ohos.permission.POWER_CONFIG

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
sceneName	string	Yes	Scene name of the power configuration. The name can contain a maximum of 128 bytes.

Return value

Type	Description
string	Value of the configuration node.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
4900400	Invalid parameter. Possible causes: 1. The sceneName parameter is an empty string; 2. The length of sceneName parameter exceeds 128 bytes.
4900501	Failed to read the power configuration value.

Example

try {
    let configVal = power.getPowerConfig('scene_name_test');
    console.info('get power config success, configVal: ' + configVal);
} catch(err) {
    console.error('get power config failed, err: ' + err);
}

power.setPowerConfig

setPowerConfig(sceneName: string, value: string): void

Update the power configuration value for a given scene name.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Required permissions: ohos.permission.POWER_CONFIG

System capability: SystemCapability.PowerManager.PowerManager.Core

Parameters

Name	Type	Mandatory	Description
sceneName	string	Yes	Scene name of the power configuration. The name can contain a maximum of 128 bytes.
value	string	Yes	Power configuration value. The value can contain a maximum of 128 bytes.

Error codes

For details about the error codes, see Power Manager Error Codes and Universal Error Codes.

ID	Error Message
4900101	Failed to connect to the service.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
4900400	Invalid parameter. Possible causes: 1. The sceneName or value parameter is an empty string; 2. The length of sceneName parameter exceeds 128 bytes; 3. The length of value parameter exceeds 128 bytes.
4900601	Failed to write the power configuration value.

Example

try {
    power.setPowerConfig('scene_name_test', 'value_test');
    console.info('set power config success');
} catch(err) {
    console.error('set power config failed, err: ' + err);
}