FileDocCategorySizeDatePackage
PowerManager.javaAPI DocAndroid 5.1 API42018Thu Mar 12 22:22:10 GMT 2015android.os

PowerManager

public final class PowerManager extends Object
This class gives you control of the power state of the device.

Device battery life will be significantly affected by the use of this API. Do not acquire {@link WakeLock}s unless you really need them, use the minimum levels possible, and be sure to release them as soon as possible.

You can obtain an instance of this class by calling {@link android.content.Context#getSystemService(java.lang.String) Context.getSystemService()}.

The primary API you'll use is {@link #newWakeLock(int, String) newWakeLock()}. This will create a {@link PowerManager.WakeLock} object. You can then use methods on the wake lock object to control the power state of the device.

In practice it's quite simple: {@samplecode PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE); PowerManager.WakeLock wl = pm.newWakeLock(PowerManager.SCREEN_DIM_WAKE_LOCK, "My Tag"); wl.acquire(); ..screen will stay on during this section.. wl.release(); }

The following wake lock levels are defined, with varying effects on system power. These levels are mutually exclusive - you may only specify one of them.
Flag Value CPU Screen Keyboard
{@link #PARTIAL_WAKE_LOCK} On* Off Off
{@link #SCREEN_DIM_WAKE_LOCK} On Dim Off
{@link #SCREEN_BRIGHT_WAKE_LOCK} On Bright Off
{@link #FULL_WAKE_LOCK} On Bright Bright

*If you hold a partial wake lock, the CPU will continue to run, regardless of any display timeouts or the state of the screen and even after the user presses the power button. In all other wake locks, the CPU will run, but the user can still put the device to sleep using the power button.

In addition, you can add two more flags, which affect behavior of the screen only. These flags have no effect when combined with a {@link #PARTIAL_WAKE_LOCK}.

Flag Value Description
{@link #ACQUIRE_CAUSES_WAKEUP} Normal wake locks don't actually turn on the illumination. Instead, they cause the illumination to remain on once it turns on (e.g. from user activity). This flag will force the screen and/or keyboard to turn on immediately, when the WakeLock is acquired. A typical use would be for notifications which are important for the user to see immediately.
{@link #ON_AFTER_RELEASE} If this flag is set, the user activity timer will be reset when the WakeLock is released, causing the illumination to remain on a bit longer. This can be used to reduce flicker if you are cycling between wake lock conditions.

Any application using a WakeLock must request the {@code android.permission.WAKE_LOCK} permission in an {@code <uses-permission>} element of the application's manifest.

Fields Summary
private static final String
TAG
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.

public static final int
SCREEN_DIM_WAKE_LOCK
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 {@link #SCREEN_DIM_WAKE_LOCK} will be implicitly released by the system, causing both the screen and the CPU to be turned off. Contrast with {@link #PARTIAL_WAKE_LOCK}.

public static final int
SCREEN_BRIGHT_WAKE_LOCK
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 {@link #SCREEN_BRIGHT_WAKE_LOCK} will be implicitly released by the system, causing both the screen and the CPU to be turned off. Contrast with {@link #PARTIAL_WAKE_LOCK}.

public static final int
FULL_WAKE_LOCK
Wake lock level: Ensures that the screen and keyboard backlight are on at full brightness.

If the user presses the power button, then the {@link #FULL_WAKE_LOCK} will be implicitly released by the system, causing both the screen and the CPU to be turned off. Contrast with {@link #PARTIAL_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 {@link #FULL_WAKE_LOCK}, {@link #SCREEN_BRIGHT_WAKE_LOCK} and {@link #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 {@link #isWakeLockLevelSupported} to determine whether this wake lock level is supported.

Cannot be used with {@link #ACQUIRE_CAUSES_WAKEUP}.

public static final int
DOZE_WAKE_LOCK
Wake lock level: Put the screen in a low power state and allow the CPU to suspend if no other wake locks are held.

This is used by the dream manager to implement doze mode. It currently has no effect unless the power manager is in the dozing state.

Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.

{@hide}
public static final int
WAKE_LOCK_LEVEL_MASK
Mask for the wake lock level component of a combined wake lock level and flags integer.
public static final int
ACQUIRE_CAUSES_WAKEUP
Wake lock flag: Turn the screen on when the wake lock is acquired.

Normally wake locks don't actually wake the device, they just cause the screen to remain on once it's already on. Think of the video player application as the normal behavior. Notifications that pop up and want the device to be on are the exception; use this flag to be like them.

Cannot be used with {@link #PARTIAL_WAKE_LOCK}.

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.

Will not turn the screen on if it is not already on. See {@link #ACQUIRE_CAUSES_WAKEUP} if you want that.

Cannot be used with {@link #PARTIAL_WAKE_LOCK}.

public static final int
UNIMPORTANT_FOR_LOGGING
Wake lock flag: This wake lock is not important for logging events. If a later wake lock is acquired that is important, it will be considered the one to log.
public static final int
RELEASE_FLAG_WAIT_FOR_NO_PROXIMITY
Flag for {@link WakeLock#release WakeLock.release(int)}: Defer releasing a {@link #PROXIMITY_SCREEN_OFF_WAKE_LOCK} wake lock until the proximity sensor indicates that an object is not in close proximity.
public static final int
BRIGHTNESS_ON
Brightness value for fully on.
public static final int
BRIGHTNESS_OFF
Brightness value for fully off.
public static final int
BRIGHTNESS_DEFAULT
Brightness value for default policy handling by the system.
public static final int
USER_ACTIVITY_EVENT_OTHER
User activity event type: Unspecified event type.
public static final int
USER_ACTIVITY_EVENT_BUTTON
User activity event type: Button or key pressed or released.
public static final int
USER_ACTIVITY_EVENT_TOUCH
User activity event type: Touch down, move or up.
public static final int
USER_ACTIVITY_FLAG_NO_CHANGE_LIGHTS
User activity flag: If already dimmed, extend the dim timeout but do not brighten. This flag is useful for keeping the screen on a little longer without causing a visible change such as when the power key is pressed.
public static final int
USER_ACTIVITY_FLAG_INDIRECT
User activity flag: Note the user activity as usual but do not reset the user activity timeout. This flag is useful for applying user activity power hints when interacting with the device indirectly on a secondary screen while allowing the primary screen to go to sleep.
public static final int
GO_TO_SLEEP_REASON_APPLICATION
Go to sleep reason code: Going to sleep due by application request.
public static final int
GO_TO_SLEEP_REASON_DEVICE_ADMIN
Go to sleep reason code: Going to sleep due by request of the device administration policy.
public static final int
GO_TO_SLEEP_REASON_TIMEOUT
Go to sleep reason code: Going to sleep due to a screen timeout.
public static final int
GO_TO_SLEEP_REASON_LID_SWITCH
Go to sleep reason code: Going to sleep due to the lid switch being closed.
public static final int
GO_TO_SLEEP_REASON_POWER_BUTTON
Go to sleep reason code: Going to sleep due to the power button being pressed.
public static final int
GO_TO_SLEEP_REASON_HDMI
Go to sleep reason code: Going to sleep due to HDMI.
public static final int
GO_TO_SLEEP_FLAG_NO_DOZE
Go to sleep flag: Skip dozing state and directly go to full sleep.
public static final String
REBOOT_RECOVERY
The value to pass as the 'reason' argument to reboot() to reboot into recovery mode (for applying system updates, doing factory resets, etc.).

Requires the {@link android.Manifest.permission#RECOVERY} permission (in addition to {@link android.Manifest.permission#REBOOT}).

final android.content.Context
mContext
final IPowerManager
mService
final Handler
mHandler
public static final String
ACTION_POWER_SAVE_MODE_CHANGED
Intent that is broadcast when the state of {@link #isPowerSaveMode()} changes. This broadcast is only sent to registered receivers.
public static final String
ACTION_POWER_SAVE_MODE_CHANGING
Intent that is broadcast when the state of {@link #isPowerSaveMode()} is about to change. This broadcast is only sent to registered receivers.
public static final String
EXTRA_POWER_SAVE_MODE
Constructors Summary
public PowerManager(android.content.Context context, IPowerManager service, Handler handler)
{@hide}


          
           
        mContext = context;
        mService = service;
        mHandler = handler;
Methods Summary
public voidboostScreenBrightness(long time)
Boosts the brightness of the screen to maximum for a predetermined period of time. This is used to make the screen more readable in bright daylight for a short duration.

Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.

param
time The time when the request to boost was issued, in the {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly order the boost request with other power management functions. It should be set to the timestamp of the input event that caused the request to boost.
hide
Requires signature permission.

        try {
            mService.boostScreenBrightness(time);
        } catch (RemoteException e) {
        }
public intgetDefaultScreenBrightnessSetting()
Gets the default screen brightness setting.

hide

        return mContext.getResources().getInteger(
                com.android.internal.R.integer.config_screenBrightnessSettingDefault);
public intgetMaximumScreenBrightnessSetting()
Gets the maximum supported screen brightness setting. The screen may be allowed to become dimmer than this value but this is the maximum value that can be set by the user.

hide

        return mContext.getResources().getInteger(
                com.android.internal.R.integer.config_screenBrightnessSettingMaximum);
public intgetMinimumScreenBrightnessSetting()
Gets the minimum supported screen brightness setting. The screen may be allowed to become dimmer than this value but this is the minimum value that can be set by the user.

hide

        return mContext.getResources().getInteger(
                com.android.internal.R.integer.config_screenBrightnessSettingMinimum);
public voidgoToSleep(long time)
Forces the device to go to sleep.

Overrides all the wake locks that are held. This is what happens when the power key is pressed to turn off the screen.

Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.

param
time The time when the request to go to sleep was issued, in the {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly order the go to sleep request with other power management functions. It should be set to the timestamp of the input event that caused the request to go to sleep.
see
#userActivity
see
#wakeUp
removed
Requires signature permission.

        goToSleep(time, GO_TO_SLEEP_REASON_APPLICATION, 0);
public voidgoToSleep(long time, int reason, int flags)
Forces the device to go to sleep.

Overrides all the wake locks that are held. This is what happens when the power key is pressed to turn off the screen.

Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.

param
time The time when the request to go to sleep was issued, in the {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly order the go to sleep request with other power management functions. It should be set to the timestamp of the input event that caused the request to go to sleep.
param
reason The reason the device is going to sleep.
param
flags Optional flags to apply when going to sleep.
see
#userActivity
see
#wakeUp
hide
Requires signature permission.

        try {
            mService.goToSleep(time, reason, flags);
        } catch (RemoteException e) {
        }
public booleanisInteractive()
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 {@link android.content.Intent#ACTION_SCREEN_ON screen on} or {@link android.content.Intent#ACTION_SCREEN_OFF 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.

return
True if the device is in an interactive state.
see
android.content.Intent#ACTION_SCREEN_ON
see
android.content.Intent#ACTION_SCREEN_OFF

        try {
            return mService.isInteractive();
        } catch (RemoteException e) {
            return false;
        }
public booleanisPowerSaveMode()
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 {@link #ACTION_POWER_SAVE_MODE_CHANGED}.

return
Returns true if currently in low power mode, else false.

        try {
            return mService.isPowerSaveMode();
        } catch (RemoteException e) {
            return false;
        }
public booleanisScreenOn()
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 {@link #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 {@link android.view.Display#getState}.

return
True if the device is in an interactive state.
deprecated
Use {@link #isInteractive} instead.

        return isInteractive();
public booleanisWakeLockLevelSupported(int level)
Returns true if the specified wake lock level is supported.

param
level The wake lock level to check.
return
True if the specified wake lock level is supported.

        try {
            return mService.isWakeLockLevelSupported(level);
        } catch (RemoteException e) {
            return false;
        }
public voidnap(long time)
Forces the device to start napping.

If the device is currently awake, starts dreaming, otherwise does nothing. When the dream ends or if the dream cannot be started, the device will either wake up or go to sleep depending on whether there has been recent user activity.

Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.

param
time The time when the request to nap was issued, in the {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly order the nap request with other power management functions. It should be set to the timestamp of the input event that caused the request to nap.
see
#wakeUp
see
#goToSleep
hide
Requires signature permission.

        try {
            mService.nap(time);
        } catch (RemoteException e) {
        }
public android.os.PowerManager$WakeLocknewWakeLock(int levelAndFlags, java.lang.String tag)
Creates a new wake lock with the specified level and flags.

The {@code levelAndFlags} parameter specifies a wake lock level and optional flags combined using the logical OR operator.

The wake lock levels are: {@link #PARTIAL_WAKE_LOCK}, {@link #FULL_WAKE_LOCK}, {@link #SCREEN_DIM_WAKE_LOCK} and {@link #SCREEN_BRIGHT_WAKE_LOCK}. Exactly one wake lock level must be specified as part of the {@code levelAndFlags} parameter.

The wake lock flags are: {@link #ACQUIRE_CAUSES_WAKEUP} and {@link #ON_AFTER_RELEASE}. Multiple flags can be combined as part of the {@code levelAndFlags} parameters.

Call {@link WakeLock#acquire() acquire()} on the object to acquire the wake lock, and {@link WakeLock#release release()} when you are done.

{@samplecode PowerManager pm = (PowerManager)mContext.getSystemService( Context.POWER_SERVICE); 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 {@link android.Manifest.permission#WAKE_LOCK} permission is required to actually acquire or release the wake lock that is returned.

If using this to keep the screen on, you should strongly consider using {@link android.view.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.

param
levelAndFlags Combination of wake lock level and flag values defining the requested behavior of the WakeLock.
param
tag Your class name (or other tag) for debugging purposes.
see
WakeLock#acquire()
see
WakeLock#release()
see
#PARTIAL_WAKE_LOCK
see
#FULL_WAKE_LOCK
see
#SCREEN_DIM_WAKE_LOCK
see
#SCREEN_BRIGHT_WAKE_LOCK
see
#PROXIMITY_SCREEN_OFF_WAKE_LOCK
see
#ACQUIRE_CAUSES_WAKEUP
see
#ON_AFTER_RELEASE

        validateWakeLockParameters(levelAndFlags, tag);
        return new WakeLock(levelAndFlags, tag, mContext.getOpPackageName());
public voidreboot(java.lang.String reason)
Reboot the device. Will not return if the reboot is successful.

Requires the {@link android.Manifest.permission#REBOOT} permission.

param
reason code to pass to the kernel (e.g., "recovery") to request special boot modes, or null.

        try {
            mService.reboot(false, reason, true);
        } catch (RemoteException e) {
        }
public voidsetBacklightBrightness(int brightness)
Sets the brightness of the backlights (screen, keyboard, button).

Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.

param
brightness The brightness value from 0 to 255.
hide
Requires signature permission.

        try {
            mService.setTemporaryScreenBrightnessSettingOverride(brightness);
        } catch (RemoteException e) {
        }
public booleansetPowerSaveMode(boolean mode)
Set the current power save mode.

return
True if the set was allowed.
see
#isPowerSaveMode()
hide

        try {
            return mService.setPowerSaveMode(mode);
        } catch (RemoteException e) {
            return false;
        }
public static booleanuseTwilightAdjustmentFeature()
Returns true if the twilight service should be used to adjust screen brightness policy. This setting is experimental and disabled by default.

hide

        return SystemProperties.getBoolean("persist.power.usetwilightadj", false);
public voiduserActivity(long when, boolean noChangeLights)
Notifies the power manager that user activity happened.

Resets the auto-off timer and brightens the screen if the device is not asleep. This is what happens normally when a key or the touch screen is pressed or when some other user activity occurs. This method does not wake up the device if it has been put to sleep.

Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.

param
when The time of the user activity, in the {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly order the user activity request with other power management functions. It should be set to the timestamp of the input event that caused the user activity.
param
noChangeLights If true, does not cause the keyboard backlight to turn on because of this event. This is set when the power key is pressed. We want the device to stay on while the button is down, but we're about to turn off the screen so we don't want the keyboard backlight to turn on again. Otherwise the lights flash on and then off and it looks weird.
see
#wakeUp
see
#goToSleep
removed
Requires signature or system permission.
deprecated
Use {@link #userActivity(long, int, int)}.

        userActivity(when, USER_ACTIVITY_EVENT_OTHER,
                noChangeLights ? USER_ACTIVITY_FLAG_NO_CHANGE_LIGHTS : 0);
public voiduserActivity(long when, int event, int flags)
Notifies the power manager that user activity happened.

Resets the auto-off timer and brightens the screen if the device is not asleep. This is what happens normally when a key or the touch screen is pressed or when some other user activity occurs. This method does not wake up the device if it has been put to sleep.

Requires the {@link android.Manifest.permission#DEVICE_POWER} or {@link android.Manifest.permission#USER_ACTIVITY} permission.

param
when The time of the user activity, in the {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly order the user activity request with other power management functions. It should be set to the timestamp of the input event that caused the user activity.
param
event The user activity event.
param
flags Optional user activity flags.
see
#wakeUp
see
#goToSleep
hide
Requires signature or system permission.

        try {
            mService.userActivity(when, event, flags);
        } catch (RemoteException e) {
        }
public static voidvalidateWakeLockParameters(int levelAndFlags, java.lang.String tag)

hide

        switch (levelAndFlags & WAKE_LOCK_LEVEL_MASK) {
            case PARTIAL_WAKE_LOCK:
            case SCREEN_DIM_WAKE_LOCK:
            case SCREEN_BRIGHT_WAKE_LOCK:
            case FULL_WAKE_LOCK:
            case PROXIMITY_SCREEN_OFF_WAKE_LOCK:
            case DOZE_WAKE_LOCK:
                break;
            default:
                throw new IllegalArgumentException("Must specify a valid wake lock level.");
        }
        if (tag == null) {
            throw new IllegalArgumentException("The tag must not be null.");
        }
public voidwakeUp(long time)
Forces the device to wake up from sleep.

If the device is currently asleep, wakes it up, otherwise does nothing. This is what happens when the power key is pressed to turn on the screen.

Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.

param
time The time when the request to wake up was issued, in the {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly order the wake up request with other power management functions. It should be set to the timestamp of the input event that caused the request to wake up.
see
#userActivity
see
#goToSleep
removed
Requires signature permission.

        try {
            mService.wakeUp(time);
        } catch (RemoteException e) {
        }