PowerManager
public
final
class
PowerManager
extends Object
java.lang.Object | |
↳ | android.os.PowerManager |
This class lets you query and request control of aspects of the device's power state.
Summary
Nested classes | |
---|---|
interface |
PowerManager.OnThermalStatusChangedListener
Listener passed to
|
class |
PowerManager.WakeLock
A wake lock is a mechanism to indicate that your application needs to have the device stay on. |
interface |
PowerManager.WakeLockStateListener
A listener interface to get notified when the wakelock is enabled/disabled. |
Constants | |
---|---|
int |
ACQUIRE_CAUSES_WAKEUP
This constant was deprecated
in API level 33.
Most applications should use |
String |
ACTION_DEVICE_IDLE_MODE_CHANGED
Intent that is broadcast when the state of |
String |
ACTION_DEVICE_LIGHT_IDLE_MODE_CHANGED
Intent that is broadcast when the state of |
String |
ACTION_LOW_POWER_STANDBY_ENABLED_CHANGED
Intent that is broadcast when Low Power Standby is enabled or disabled. |
String |
ACTION_LOW_POWER_STANDBY_POLICY_CHANGED
Intent that is broadcast when Low Power Standby policy is changed. |
String |
ACTION_POWER_SAVE_MODE_CHANGED
Intent that is broadcast when the state of |
String |
FEATURE_WAKE_ON_LAN_IN_LOW_POWER_STANDBY
Signals that wake-on-lan/wake-on-wlan is allowed in Low Power Standby. |
int |
FULL_WAKE_LOCK
This constant was deprecated
in API level 17.
Most applications should use
|
int |
LOCATION_MODE_ALL_DISABLED_WHEN_SCREEN_OFF
All location providers should be disabled when battery saver is on and the device is non-interactive. |
int |
LOCATION_MODE_FOREGROUND_ONLY
In this mode, all the location providers will be kept available, but location fixes should only be provided to foreground apps. |
int |
LOCATION_MODE_GPS_DISABLED_WHEN_SCREEN_OFF
In this mode, the GPS based location provider should be disabled when battery saver is on and the device is non-interactive. |
int |
LOCATION_MODE_NO_CHANGE
Either the location providers shouldn't be affected by battery saver, or battery saver is off. |
int |
LOCATION_MODE_THROTTLE_REQUESTS_WHEN_SCREEN_OFF
In this mode, location will not be turned off, but LocationManager will throttle all requests to providers when the device is non-interactive. |
int |
LOW_POWER_STANDBY_ALLOWED_REASON_ONGOING_CALL
Exempts apps with ongoing calls. |
int |
LOW_POWER_STANDBY_ALLOWED_REASON_TEMP_POWER_SAVE_ALLOWLIST
Exempts apps on the temporary powersave allowlist. |
int |
LOW_POWER_STANDBY_ALLOWED_REASON_VOICE_INTERACTION
Exempts active Voice Interaction Sessions in Low Power Standby. |
int |
ON_AFTER_RELEASE
Wake lock flag: When this wake lock is released, poke the user activity timer so the screen stays on for a little longer. |
int |
PARTIAL_WAKE_LOCK
Wake lock level: Ensures that the CPU is running; the screen and keyboard backlight will be allowed to go off. |
int |
PROXIMITY_SCREEN_OFF_WAKE_LOCK
Wake lock level: Turns the screen off when the proximity sensor activates. |
int |
RELEASE_FLAG_WAIT_FOR_NO_PROXIMITY
Flag for |
int |
SCREEN_BRIGHT_WAKE_LOCK
This constant was deprecated
in API level 15.
Most applications should use
|
int |
SCREEN_DIM_WAKE_LOCK
This constant was deprecated
in API level 17.
Most applications should use
|
int |
THERMAL_STATUS_CRITICAL
Thermal status code: Platform has done everything to reduce power. |
int |
THERMAL_STATUS_EMERGENCY
Thermal status code: Key components in platform are shutting down due to thermal condition. |
int |
THERMAL_STATUS_LIGHT
Thermal status code: Light throttling where UX is not impacted. |
int |
THERMAL_STATUS_MODERATE
Thermal status code: Moderate throttling where UX is not largely impacted. |
int |
THERMAL_STATUS_NONE
Thermal status code: Not under throttling. |
int |
THERMAL_STATUS_SEVERE
Thermal status code: Severe throttling where UX is largely impacted. |
int |
THERMAL_STATUS_SHUTDOWN
Thermal status code: Need shutdown immediately. |
Public methods | |
---|---|
void
|
addThermalStatusListener(Executor executor, PowerManager.OnThermalStatusChangedListener listener)
This function adds a listener for thermal status change. |
void
|
addThermalStatusListener(PowerManager.OnThermalStatusChangedListener listener)
This function adds a listener for thermal status change, listen call back will be enqueued tasks on the main thread |
Duration
|
getBatteryDischargePrediction()
Returns the current battery life remaining estimate. |
int
|
getCurrentThermalStatus()
This function returns the current thermal status of the device. |
int
|
getLocationPowerSaveMode()
Returns how location features should behave when battery saver is on. |
float
|
getThermalHeadroom(int forecastSeconds)
Provides an estimate of how much thermal headroom the device currently has before hitting severe throttling. |
Map<Integer, Float>
|
getThermalHeadroomThresholds()
Gets the thermal headroom thresholds for all available thermal throttling status above
|
boolean
|
isAllowedInLowPowerStandby(String feature)
Returns true if Low Power Standby is disabled (so Low Power Standby does not restrict apps), or apps are allowed to use a given feature during Low Power Standby. |
boolean
|
isAllowedInLowPowerStandby(int reason)
Returns true if Low Power Standby is disabled (so Low Power Standby does not restrict apps), or apps may be automatically exempt from Low Power Standby restrictions for the given reason. |
boolean
|
isBatteryDischargePredictionPersonalized()
Returns whether the current battery life remaining estimate is personalized based on device usage history or not. |
boolean
|
isDeviceIdleMode()
Returns true if the device is currently in idle mode. |
boolean
|
isDeviceLightIdleMode()
Returns true if the device is currently in light idle mode. |
boolean
|
isExemptFromLowPowerStandby()
Returns true if the calling package is exempt from Low Power Standby restrictions or Low Power Standby is disabled (so Low Power Standby does not restrict apps), false otherwise. |
boolean
|
isIgnoringBatteryOptimizations(String packageName)
Return whether the given application package name is on the device's power allowlist. |
boolean
|
isInteractive()
Returns true if the device is in an interactive state. |
boolean
|
isLowPowerStandbyEnabled()
Returns true if Low Power Standby is enabled. |
boolean
|
isPowerSaveMode()
Returns true if the device is currently in power save mode. |
boolean
|
isRebootingUserspaceSupported()
This method was deprecated
in API level 35.
userspace reboot is deprecated, this method always returns |
boolean
|
isScreenOn()
This method was deprecated
in API level 20.
Use |
boolean
|
isSustainedPerformanceModeSupported()
This function checks if the device has implemented Sustained Performance Mode. |
boolean
|
isWakeLockLevelSupported(int level)
Returns true if the specified wake lock level is supported. |
PowerManager.WakeLock
|
newWakeLock(int levelAndFlags, String tag)
Creates a new wake lock with the specified level and flags. |
void
|
reboot(String reason)
Reboot the device. |
void
|
removeThermalStatusListener(PowerManager.OnThermalStatusChangedListener listener)
This function removes a listener for thermal status change |
Inherited methods | |
---|---|
Constants
ACQUIRE_CAUSES_WAKEUP
public static final int ACQUIRE_CAUSES_WAKEUP
This constant was deprecated
in API level 33.
Most applications should use R.attr.turnScreenOn
or
Activity.setTurnScreenOn(boolean)
instead, as this prevents the previous
foreground app from being resumed first when the screen turns on.
Wake lock flag: Turn the screen on when the wake lock is acquired.
This flag will require Manifest.permission.TURN_SCREEN_ON
in future releases.
Normally wake locks don't actually wake the device, they just cause the screen to remain on once it's already on. This flag will cause the device to wake up when the wake lock is acquired.
Android TV playback devices attempt to turn on the HDMI-connected TV via HDMI-CEC on any wake-up, including wake-ups triggered by wake locks.
Cannot be used with PARTIAL_WAKE_LOCK
.
Constant Value: 268435456 (0x10000000)
ACTION_DEVICE_IDLE_MODE_CHANGED
public static final String ACTION_DEVICE_IDLE_MODE_CHANGED
Intent that is broadcast when the state of isDeviceIdleMode()
changes.
This broadcast is only sent to registered receivers.
Constant Value: "android.os.action.DEVICE_IDLE_MODE_CHANGED"
ACTION_DEVICE_LIGHT_IDLE_MODE_CHANGED
public static final String ACTION_DEVICE_LIGHT_IDLE_MODE_CHANGED
Intent that is broadcast when the state of isDeviceLightIdleMode()
changes.
This broadcast is only sent to registered receivers.
Constant Value: "android.os.action.LIGHT_DEVICE_IDLE_MODE_CHANGED"
ACTION_LOW_POWER_STANDBY_ENABLED_CHANGED
public static final String ACTION_LOW_POWER_STANDBY_ENABLED_CHANGED
Intent that is broadcast when Low Power Standby is enabled or disabled.
This broadcast is only sent to registered receivers and receivers holding
android.permission.MANAGE_LOW_POWER_STANDBY
.
See also:
Constant Value: "android.os.action.LOW_POWER_STANDBY_ENABLED_CHANGED"
ACTION_LOW_POWER_STANDBY_POLICY_CHANGED
public static final String ACTION_LOW_POWER_STANDBY_POLICY_CHANGED
Intent that is broadcast when Low Power Standby policy is changed.
This broadcast is only sent to registered receivers and receivers holding
android.permission.MANAGE_LOW_POWER_STANDBY
.
See also:
Constant Value: "android.os.action.LOW_POWER_STANDBY_POLICY_CHANGED"
ACTION_POWER_SAVE_MODE_CHANGED
public static final String ACTION_POWER_SAVE_MODE_CHANGED
Intent that is broadcast when the state of isPowerSaveMode()
changes.
This broadcast is only sent to registered receivers.
Constant Value: "android.os.action.POWER_SAVE_MODE_CHANGED"
FEATURE_WAKE_ON_LAN_IN_LOW_POWER_STANDBY
public static final String FEATURE_WAKE_ON_LAN_IN_LOW_POWER_STANDBY
Signals that wake-on-lan/wake-on-wlan is allowed in Low Power Standby.
If Low Power Standby is enabled (isLowPowerStandbyEnabled()
),
wake-on-lan/wake-on-wlan may not be available while in standby.
Use isAllowedInLowPowerStandby(java.lang.String)
to determine whether the device allows this
feature to be used during Low Power Standby with the currently active Low Power Standby
policy.
See also:
Constant Value: "com.android.lowpowerstandby.WAKE_ON_LAN"
FULL_WAKE_LOCK
public static final int FULL_WAKE_LOCK
This constant was deprecated
in API level 17.
Most applications should use
WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON
instead
of this type of wake lock, as it will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
Wake lock level: Ensures that the screen and keyboard backlight are on at full brightness.
If the user presses the power button, then the FULL_WAKE_LOCK
will be
implicitly released by the system, causing both the screen and the CPU to be turned off.
Contrast with PARTIAL_WAKE_LOCK
.
Constant Value: 26 (0x0000001a)
LOCATION_MODE_ALL_DISABLED_WHEN_SCREEN_OFF
public static final int LOCATION_MODE_ALL_DISABLED_WHEN_SCREEN_OFF
All location providers should be disabled when battery saver is on and the device is non-interactive.
Constant Value: 2 (0x00000002)
LOCATION_MODE_FOREGROUND_ONLY
public static final int LOCATION_MODE_FOREGROUND_ONLY
In this mode, all the location providers will be kept available, but location fixes should only be provided to foreground apps.
Constant Value: 3 (0x00000003)
LOCATION_MODE_GPS_DISABLED_WHEN_SCREEN_OFF
public static final int LOCATION_MODE_GPS_DISABLED_WHEN_SCREEN_OFF
In this mode, the GPS based location provider should be disabled when battery saver is on and the device is non-interactive.
Constant Value: 1 (0x00000001)
LOCATION_MODE_NO_CHANGE
public static final int LOCATION_MODE_NO_CHANGE
Either the location providers shouldn't be affected by battery saver, or battery saver is off.
Constant Value: 0 (0x00000000)
LOCATION_MODE_THROTTLE_REQUESTS_WHEN_SCREEN_OFF
public static final int LOCATION_MODE_THROTTLE_REQUESTS_WHEN_SCREEN_OFF
In this mode, location will not be turned off, but LocationManager will throttle all requests to providers when the device is non-interactive.
Constant Value: 4 (0x00000004)
LOW_POWER_STANDBY_ALLOWED_REASON_ONGOING_CALL
public static final int LOW_POWER_STANDBY_ALLOWED_REASON_ONGOING_CALL
Exempts apps with ongoing calls.
This includes apps with foreground services of type "phoneCall".
See also:
Constant Value: 4 (0x00000004)
LOW_POWER_STANDBY_ALLOWED_REASON_TEMP_POWER_SAVE_ALLOWLIST
public static final int LOW_POWER_STANDBY_ALLOWED_REASON_TEMP_POWER_SAVE_ALLOWLIST
Exempts apps on the temporary powersave allowlist.
See also:
Constant Value: 2 (0x00000002)
LOW_POWER_STANDBY_ALLOWED_REASON_VOICE_INTERACTION
public static final int LOW_POWER_STANDBY_ALLOWED_REASON_VOICE_INTERACTION
Exempts active Voice Interaction Sessions in Low Power Standby.
See also:
Constant Value: 1 (0x00000001)
ON_AFTER_RELEASE
public static final int ON_AFTER_RELEASE
Wake lock flag: When this wake lock is released, poke the user activity timer so the screen stays on for a little longer.
This will not turn the screen on if it is not already on.
Cannot be used with PARTIAL_WAKE_LOCK
.
Constant Value: 536870912 (0x20000000)
PARTIAL_WAKE_LOCK
public static final int PARTIAL_WAKE_LOCK
Wake lock level: Ensures that the CPU is running; the screen and keyboard backlight will be allowed to go off.
If the user presses the power button, then the screen will be turned off but the CPU will be kept on until all partial wake locks have been released.
Constant Value: 1 (0x00000001)
PROXIMITY_SCREEN_OFF_WAKE_LOCK
public static final int PROXIMITY_SCREEN_OFF_WAKE_LOCK
Wake lock level: Turns the screen off when the proximity sensor activates.
If the proximity sensor detects that an object is nearby, the screen turns off immediately. Shortly after the object moves away, the screen turns on again.
A proximity wake lock does not prevent the device from falling asleep
unlike FULL_WAKE_LOCK
, SCREEN_BRIGHT_WAKE_LOCK
and
SCREEN_DIM_WAKE_LOCK
. If there is no user activity and no other
wake locks are held, then the device will fall asleep (and lock) as usual.
However, the device will not fall asleep while the screen has been turned off
by the proximity sensor because it effectively counts as ongoing user activity.
Since not all devices have proximity sensors, use isWakeLockLevelSupported(int)
to determine whether this wake lock level is supported.
Cannot be used with ACQUIRE_CAUSES_WAKEUP
.
Constant Value: 32 (0x00000020)
RELEASE_FLAG_WAIT_FOR_NO_PROXIMITY
public static final int RELEASE_FLAG_WAIT_FOR_NO_PROXIMITY
Flag for WakeLock.release(int)
: Defer releasing a
PROXIMITY_SCREEN_OFF_WAKE_LOCK
wake lock until the proximity sensor
indicates that an object is not in close proximity.
Constant Value: 1 (0x00000001)
SCREEN_BRIGHT_WAKE_LOCK
public static final int SCREEN_BRIGHT_WAKE_LOCK
This constant was deprecated
in API level 15.
Most applications should use
WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON
instead
of this type of wake lock, as it will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
Wake lock level: Ensures that the screen is on at full brightness; the keyboard backlight will be allowed to go off.
If the user presses the power button, then the SCREEN_BRIGHT_WAKE_LOCK
will be
implicitly released by the system, causing both the screen and the CPU to be turned off.
Contrast with PARTIAL_WAKE_LOCK
.
Constant Value: 10 (0x0000000a)
SCREEN_DIM_WAKE_LOCK
public static final int SCREEN_DIM_WAKE_LOCK
This constant was deprecated
in API level 17.
Most applications should use
WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON
instead
of this type of wake lock, as it will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
Wake lock level: Ensures that the screen is on (but may be dimmed); the keyboard backlight will be allowed to go off.
If the user presses the power button, then the SCREEN_DIM_WAKE_LOCK
will be
implicitly released by the system, causing both the screen and the CPU to be turned off.
Contrast with PARTIAL_WAKE_LOCK
.
Constant Value: 6 (0x00000006)
THERMAL_STATUS_CRITICAL
public static final int THERMAL_STATUS_CRITICAL
Thermal status code: Platform has done everything to reduce power.
Constant Value: 4 (0x00000004)
THERMAL_STATUS_EMERGENCY
public static final int THERMAL_STATUS_EMERGENCY
Thermal status code: Key components in platform are shutting down due to thermal condition. Device functionalities will be limited.
Constant Value: 5 (0x00000005)
THERMAL_STATUS_LIGHT
public static final int THERMAL_STATUS_LIGHT
Thermal status code: Light throttling where UX is not impacted.
Constant Value: 1 (0x00000001)
THERMAL_STATUS_MODERATE
public static final int THERMAL_STATUS_MODERATE
Thermal status code: Moderate throttling where UX is not largely impacted.
Constant Value: 2 (0x00000002)
THERMAL_STATUS_NONE
public static final int THERMAL_STATUS_NONE
Thermal status code: Not under throttling.
Constant Value: 0 (0x00000000)
THERMAL_STATUS_SEVERE
public static final int THERMAL_STATUS_SEVERE
Thermal status code: Severe throttling where UX is largely impacted.
Constant Value: 3 (0x00000003)
THERMAL_STATUS_SHUTDOWN
public static final int THERMAL_STATUS_SHUTDOWN
Thermal status code: Need shutdown immediately.
Constant Value: 6 (0x00000006)
Public methods
addThermalStatusListener
public void addThermalStatusListener (Executor executor, PowerManager.OnThermalStatusChangedListener listener)
This function adds a listener for thermal status change.
Parameters | |
---|---|
executor |
Executor : Executor to handle listener callback.
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
PowerManager.OnThermalStatusChangedListener : listener to be added.
This value cannot be null . |
addThermalStatusListener
public void addThermalStatusListener (PowerManager.OnThermalStatusChangedListener listener)
This function adds a listener for thermal status change, listen call back will be enqueued tasks on the main thread
Parameters | |
---|---|
listener |
PowerManager.OnThermalStatusChangedListener : listener to be added,
This value cannot be null . |
getBatteryDischargePrediction
public Duration getBatteryDischargePrediction ()
Returns the current battery life remaining estimate.
Returns | |
---|---|
Duration |
The estimated battery life remaining as a Duration . Will be null if
the device is powered, charging, or an error was encountered. |
getCurrentThermalStatus
public int getCurrentThermalStatus ()
This function returns the current thermal status of the device.
Returns | |
---|---|
int |
thermal status as int, THERMAL_STATUS_NONE if device in not under
thermal throttling.
Value is THERMAL_STATUS_NONE , THERMAL_STATUS_LIGHT , THERMAL_STATUS_MODERATE , THERMAL_STATUS_SEVERE , THERMAL_STATUS_CRITICAL , THERMAL_STATUS_EMERGENCY , or THERMAL_STATUS_SHUTDOWN |
getLocationPowerSaveMode
public int getLocationPowerSaveMode ()
Returns how location features should behave when battery saver is on. When battery saver
is off, this will always return LOCATION_MODE_NO_CHANGE
.
This API is normally only useful for components that provide location features.
getThermalHeadroom
public float getThermalHeadroom (int forecastSeconds)
Provides an estimate of how much thermal headroom the device currently has before hitting
severe throttling.
Note that this only attempts to track the headroom of slow-moving sensors, such as the skin
temperature sensor. This means that there is no benefit to calling this function more
frequently than about once per second, and attempts to call significantly more frequently may
result in the function returning NaN
.
In addition, in order to be able to provide an accurate forecast, the system does not attempt
to forecast until it has multiple temperature samples from which to extrapolate. This should
only take a few seconds from the time of the first call, but during this time, no forecasting
will occur, and the current headroom will be returned regardless of the value of
forecastSeconds
.
The value returned is a non-negative float that represents how much of the thermal envelope
is in use (or is forecasted to be in use). A value of 1.0 indicates that the device is (or
will be) throttled at THERMAL_STATUS_SEVERE
. Such throttling can affect the CPU,
GPU, and other subsystems. Values may exceed 1.0, but there is no implied mapping to specific
thermal status levels beyond that point. This means that values greater than 1.0 may
correspond to THERMAL_STATUS_SEVERE
, but may also represent heavier throttling.
A value of 0.0 corresponds to a fixed distance from 1.0, but does not correspond to any particular thermal status or temperature. Values on (0.0, 1.0] may be expected to scale linearly with temperature, though temperature changes over time are typically not linear. Negative values will be clamped to 0.0 before returning.
Parameters | |
---|---|
forecastSeconds |
int : how many seconds in the future to forecast. Given that device
conditions may change at any time, forecasts from further in the
future will likely be less accurate than forecasts in the near future.
Value is between 0 and 60 inclusive |
Returns | |
---|---|
float |
a value greater than or equal to 0.0 where 1.0 indicates the SEVERE throttling threshold, as described above. Returns NaN if the device does not support this functionality or if this function is called significantly faster than once per second. |
getThermalHeadroomThresholds
public Map<Integer, Float> getThermalHeadroomThresholds ()
Gets the thermal headroom thresholds for all available thermal throttling status above
THERMAL_STATUS_NONE
.
A thermal status key in the returned map is only set if the device manufacturer has the
corresponding threshold defined for at least one of its sensors. If it's set, one should
expect to see that from getCurrentThermalStatus()
or
OnThermalStatusChangedListener#onThermalStatusChanged(int)
.
The headroom threshold is used to interpret the possible thermal throttling status based on
the headroom prediction. For example, if the headroom threshold for
THERMAL_STATUS_LIGHT
is 0.7, and a headroom prediction in 10s returns 0.75
(or getThermalHeadroom(10)=0.75
), one can expect that in 10 seconds the system could
be in lightly throttled state if the workload remains the same. The app can consider
taking actions according to the nearest throttling status the difference between the headroom
and the threshold.
For new devices it's guaranteed to have a single sensor, but for older devices with multiple
sensors reporting different threshold values, the minimum threshold is taken to be
conservative on predictions. Thus, when reading real-time headroom, it's not guaranteed that
a real-time value of 0.75 (or getThermalHeadroom(0)
=0.75) exceeding the threshold of
0.7 above will always come with lightly throttled state
(or getCurrentThermalStatus()=THERMAL_STATUS_LIGHT
) but it can be lower
(or getCurrentThermalStatus()=THERMAL_STATUS_NONE
). While it's always guaranteed that
the device won't be throttled heavier than the unmet threshold's state, so a real-time
headroom of 0.75 will never come with THERMAL_STATUS_MODERATE
but lower, and 0.65
will never come with THERMAL_STATUS_LIGHT
but THERMAL_STATUS_NONE
.
The returned map of thresholds will not change between calls to this function, so it's best to call this once on initialization. Modifying the result will not change the thresholds cached by the system, and a new call to the API will get a new copy.
Returns | |
---|---|
Map<Integer, Float> |
map from each thermal status to its thermal headroom
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if the thermal service is not ready |
UnsupportedOperationException |
if the feature is not enabled |
isAllowedInLowPowerStandby
public boolean isAllowedInLowPowerStandby (String feature)
Returns true if Low Power Standby is disabled (so Low Power Standby does not restrict apps), or apps are allowed to use a given feature during Low Power Standby.
Parameters | |
---|---|
feature |
String : This value cannot be null . |
Returns | |
---|---|
boolean |
isAllowedInLowPowerStandby
public boolean isAllowedInLowPowerStandby (int reason)
Returns true if Low Power Standby is disabled (so Low Power Standby does not restrict apps),
or apps may be automatically exempt from Low Power Standby restrictions for the given reason.
The system may exempt apps from Low Power Standby restrictions when using allowed features.
For example, if LOW_POWER_STANDBY_ALLOWED_REASON_VOICE_INTERACTION
is allowed,
then apps with active voice interaction sessions are exempt from restrictions.
Parameters | |
---|---|
reason |
int : Value is either 0 or a combination of LOW_POWER_STANDBY_ALLOWED_REASON_VOICE_INTERACTION , LOW_POWER_STANDBY_ALLOWED_REASON_TEMP_POWER_SAVE_ALLOWLIST , and LOW_POWER_STANDBY_ALLOWED_REASON_ONGOING_CALL |
Returns | |
---|---|
boolean |
isBatteryDischargePredictionPersonalized
public boolean isBatteryDischargePredictionPersonalized ()
Returns whether the current battery life remaining estimate is personalized based on device usage history or not. This value does not take a device's powered or charging state into account.
Returns | |
---|---|
boolean |
A boolean indicating if the current discharge estimate is personalized based on historical device usage or not. |
isDeviceIdleMode
public boolean isDeviceIdleMode ()
Returns true if the device is currently in idle mode. This happens when a device
has been sitting unused and unmoving for a sufficiently long period of time, so that
it decides to go into a lower power-use state. This may involve things like turning
off network access to apps. You can monitor for changes to this state with
ACTION_DEVICE_IDLE_MODE_CHANGED
.
Returns | |
---|---|
boolean |
Returns true if currently in active device idle mode, else false. This is when idle mode restrictions are being actively applied; it will return false if the device is in a long-term idle mode but currently running a maintenance window where restrictions have been lifted. |
isDeviceLightIdleMode
public boolean isDeviceLightIdleMode ()
Returns true if the device is currently in light idle mode. This happens when a device
has had its screen off for a short time, switching it into a batching mode where we
execute jobs, syncs, networking on a batching schedule. You can monitor for changes to
this state with ACTION_DEVICE_LIGHT_IDLE_MODE_CHANGED
.
Returns | |
---|---|
boolean |
Returns true if currently in active device light idle mode, else false. This is when light idle mode restrictions are being actively applied; it will return false if the device is in a long-term idle mode but currently running a maintenance window where restrictions have been lifted. |
isExemptFromLowPowerStandby
public boolean isExemptFromLowPowerStandby ()
Returns true if the calling package is exempt from Low Power Standby restrictions or Low Power Standby is disabled (so Low Power Standby does not restrict apps), false otherwise.
Returns | |
---|---|
boolean |
isIgnoringBatteryOptimizations
public boolean isIgnoringBatteryOptimizations (String packageName)
Return whether the given application package name is on the device's power allowlist.
Apps can be placed on the allowlist through the settings UI invoked by
Settings.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS
.
Being on the power allowlist means that the system will not apply most power saving features to the app. Guardrails for extreme cases may still be applied.
Parameters | |
---|---|
packageName |
String |
Returns | |
---|---|
boolean |
isInteractive
public boolean isInteractive ()
Returns true if the device is in an interactive state.
When this method returns true, the device is awake and ready to interact with the user (although this is not a guarantee that the user is actively interacting with the device just this moment). The main screen is usually turned on while in this state. Certain features, such as the proximity sensor, may temporarily turn off the screen while still leaving the device in an interactive state. Note in particular that the device is still considered to be interactive while dreaming (since dreams can be interactive) but not when it is dozing or asleep.
When this method returns false, the device is dozing or asleep and must be awoken before it will become ready to interact with the user again. The main screen is usually turned off while in this state. Certain features, such as "ambient mode" may cause the main screen to remain on (albeit in a low power state) to display system-provided content while the device dozes.
The system will send a screen on
or screen off
broadcast
whenever the interactive state of the device changes. For historical reasons,
the names of these broadcasts refer to the power state of the screen
but they are actually sent in response to changes in the overall interactive
state of the device, as described by this method.
Services may use the non-interactive state as a hint to conserve power since the user is not present.
Returns | |
---|---|
boolean |
True if the device is in an interactive state. |
isLowPowerStandbyEnabled
public boolean isLowPowerStandbyEnabled ()
Returns true if Low Power Standby is enabled.
When Low Power Standby is enabled, apps (including apps running foreground services) are subject to additional restrictions while the device is non-interactive, outside of device idle maintenance windows: Their network access is disabled, and any wakelocks they hold are ignored.
When Low Power Standby is enabled or disabled, a Intent with action
ACTION_LOW_POWER_STANDBY_ENABLED_CHANGED
is broadcast to registered receivers.
Returns | |
---|---|
boolean |
isPowerSaveMode
public boolean isPowerSaveMode ()
Returns true if the device is currently in power save mode. When in this mode,
applications should reduce their functionality in order to conserve battery as
much as possible. You can monitor for changes to this state with
ACTION_POWER_SAVE_MODE_CHANGED
.
Returns | |
---|---|
boolean |
Returns true if currently in low power mode, else false. |
isRebootingUserspaceSupported
public boolean isRebootingUserspaceSupported ()
This method was deprecated
in API level 35.
userspace reboot is deprecated, this method always returns false
.
Returns true
if this device supports rebooting userspace.
Returns | |
---|---|
boolean |
isScreenOn
public boolean isScreenOn ()
This method was deprecated
in API level 20.
Use isInteractive()
instead.
Returns true if the device is in an interactive state.
For historical reasons, the name of this method refers to the power state of
the screen but it actually describes the overall interactive state of
the device. This method has been replaced by isInteractive()
.
The value returned by this method only indicates whether the device is
in an interactive state which may have nothing to do with the screen being
on or off. To determine the actual state of the screen,
use Display.getState()
.
Returns | |
---|---|
boolean |
True if the device is in an interactive state. |
isSustainedPerformanceModeSupported
public boolean isSustainedPerformanceModeSupported ()
This function checks if the device has implemented Sustained Performance
Mode. This needs to be checked only once and is constant for a particular
device/release.
Sustained Performance Mode is intended to provide a consistent level of
performance for prolonged amount of time.
Applications should check if the device supports this mode, before using
Window.setSustainedPerformanceMode(boolean)
.
Returns | |
---|---|
boolean |
Returns True if the device supports it, false otherwise. |
isWakeLockLevelSupported
public boolean isWakeLockLevelSupported (int level)
Returns true if the specified wake lock level is supported.
Parameters | |
---|---|
level |
int : The wake lock level to check. |
Returns | |
---|---|
boolean |
True if the specified wake lock level is supported. |
newWakeLock
public PowerManager.WakeLock newWakeLock (int levelAndFlags, String tag)
Creates a new wake lock with the specified level and flags.
The levelAndFlags
parameter specifies a wake lock level and optional flags
combined using the logical OR operator.
The wake lock levels are: PARTIAL_WAKE_LOCK
,
FULL_WAKE_LOCK
, SCREEN_DIM_WAKE_LOCK
and SCREEN_BRIGHT_WAKE_LOCK
. Exactly one wake lock level must be
specified as part of the levelAndFlags
parameter.
The wake lock flags are: ACQUIRE_CAUSES_WAKEUP
and ON_AFTER_RELEASE
. Multiple flags can be combined as part of the
levelAndFlags
parameters.
Call acquire()
on the object to acquire the
wake lock, and release()
when you are done.
PowerManager pm = mContext.getSystemService(PowerManager.class); PowerManager.WakeLock wl = pm.newWakeLock( PowerManager.SCREEN_DIM_WAKE_LOCK | PowerManager.ON_AFTER_RELEASE, TAG); wl.acquire(); // ... do work... wl.release();
Although a wake lock can be created without special permissions,
the Manifest.permission.WAKE_LOCK
permission is
required to actually acquire or release the wake lock that is returned.
Device battery life will be significantly affected by the use of this API.
Do not acquire WakeLock
s unless you really need them, use the minimum levels
possible, and be sure to release them as soon as possible.
If using this to keep the screen on, you should strongly consider using
WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON
instead.
This window flag will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
Additionally using the flag will keep only the appropriate screen on in a
multi-display scenario while using a wake lock will keep every screen powered on.
Recommended naming conventions for tags to make debugging easier:
- use a unique prefix delimited by a colon for your app/library (e.g. gmail:mytag) to make it easier to understand where the wake locks comes from. This namespace will also avoid collision for tags inside your app coming from different libraries which will make debugging easier.
- use constants (e.g. do not include timestamps in the tag) to make it easier for tools to aggregate similar wake locks. When collecting debugging data, the platform only monitors a finite number of tags, using constants will help tools to provide better debugging data.
- avoid using Class#getName() or similar method since this class name can be transformed by java optimizer and obfuscator tools.
- avoid wrapping the tag or a prefix to avoid collision with wake lock tags from the platform (e.g. *alarm*).
- never include personally identifiable information for privacy reasons.
Parameters | |
---|---|
levelAndFlags |
int : Combination of wake lock level and flag values defining
the requested behavior of the WakeLock. |
tag |
String : Your class name (or other tag) for debugging purposes. |
Returns | |
---|---|
PowerManager.WakeLock |
reboot
public void reboot (String reason)
Reboot the device. Will not return if the reboot is successful.
Requires the Manifest.permission.REBOOT
permission.
If the reason
string contains ",quiescent", then the screen stays off during reboot
and is not turned on again until the user triggers the device to wake up (for example,
by pressing the power key).
This behavior applies to Android TV devices launched on Android 11 (API level 30) or higher.
Requires
Manifest.permission.REBOOT
Parameters | |
---|---|
reason |
String : code to pass to the kernel (e.g., "recovery") to
request special boot modes, or null. |
Throws | |
---|---|
UnsupportedOperationException |
if userspace reboot was requested on a device that doesn't support it. |
removeThermalStatusListener
public void removeThermalStatusListener (PowerManager.OnThermalStatusChangedListener listener)
This function removes a listener for thermal status change
Parameters | |
---|---|
listener |
PowerManager.OnThermalStatusChangedListener : listener to be removed
This value cannot be null . |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-06-18 UTC.