PowerManager.java revision 280a64e793d081847c5dcea23ed9be38aa5332d2
1/*
2 * Copyright (C) 2007 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.os;
18
19import android.annotation.SdkConstant;
20import android.annotation.SystemApi;
21import android.content.Context;
22import android.util.Log;
23
24/**
25 * This class gives you control of the power state of the device.
26 *
27 * <p>
28 * <b>Device battery life will be significantly affected by the use of this API.</b>
29 * Do not acquire {@link WakeLock}s unless you really need them, use the minimum levels
30 * possible, and be sure to release them as soon as possible.
31 * </p><p>
32 * You can obtain an instance of this class by calling
33 * {@link android.content.Context#getSystemService(java.lang.String) Context.getSystemService()}.
34 * </p><p>
35 * The primary API you'll use is {@link #newWakeLock(int, String) newWakeLock()}.
36 * This will create a {@link PowerManager.WakeLock} object.  You can then use methods
37 * on the wake lock object to control the power state of the device.
38 * </p><p>
39 * In practice it's quite simple:
40 * {@samplecode
41 * PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE);
42 * PowerManager.WakeLock wl = pm.newWakeLock(PowerManager.SCREEN_DIM_WAKE_LOCK, "My Tag");
43 * wl.acquire();
44 *   ..screen will stay on during this section..
45 * wl.release();
46 * }
47 * </p><p>
48 * The following wake lock levels are defined, with varying effects on system power.
49 * <i>These levels are mutually exclusive - you may only specify one of them.</i>
50 *
51 * <table>
52 *     <tr><th>Flag Value</th>
53 *     <th>CPU</th> <th>Screen</th> <th>Keyboard</th></tr>
54 *
55 *     <tr><td>{@link #PARTIAL_WAKE_LOCK}</td>
56 *         <td>On*</td> <td>Off</td> <td>Off</td>
57 *     </tr>
58 *
59 *     <tr><td>{@link #SCREEN_DIM_WAKE_LOCK}</td>
60 *         <td>On</td> <td>Dim</td> <td>Off</td>
61 *     </tr>
62 *
63 *     <tr><td>{@link #SCREEN_BRIGHT_WAKE_LOCK}</td>
64 *         <td>On</td> <td>Bright</td> <td>Off</td>
65 *     </tr>
66 *
67 *     <tr><td>{@link #FULL_WAKE_LOCK}</td>
68 *         <td>On</td> <td>Bright</td> <td>Bright</td>
69 *     </tr>
70 * </table>
71 * </p><p>
72 * *<i>If you hold a partial wake lock, the CPU will continue to run, regardless of any
73 * display timeouts or the state of the screen and even after the user presses the power button.
74 * In all other wake locks, the CPU will run, but the user can still put the device to sleep
75 * using the power button.</i>
76 * </p><p>
77 * In addition, you can add two more flags, which affect behavior of the screen only.
78 * <i>These flags have no effect when combined with a {@link #PARTIAL_WAKE_LOCK}.</i></p>
79 *
80 * <table>
81 *     <tr><th>Flag Value</th> <th>Description</th></tr>
82 *
83 *     <tr><td>{@link #ACQUIRE_CAUSES_WAKEUP}</td>
84 *         <td>Normal wake locks don't actually turn on the illumination.  Instead, they cause
85 *         the illumination to remain on once it turns on (e.g. from user activity).  This flag
86 *         will force the screen and/or keyboard to turn on immediately, when the WakeLock is
87 *         acquired.  A typical use would be for notifications which are important for the user to
88 *         see immediately.</td>
89 *     </tr>
90 *
91 *     <tr><td>{@link #ON_AFTER_RELEASE}</td>
92 *         <td>If this flag is set, the user activity timer will be reset when the WakeLock is
93 *         released, causing the illumination to remain on a bit longer.  This can be used to
94 *         reduce flicker if you are cycling between wake lock conditions.</td>
95 *     </tr>
96 * </table>
97 * <p>
98 * Any application using a WakeLock must request the {@code android.permission.WAKE_LOCK}
99 * permission in an {@code &lt;uses-permission&gt;} element of the application's manifest.
100 * </p>
101 */
102public final class PowerManager {
103    private static final String TAG = "PowerManager";
104
105    /* NOTE: Wake lock levels were previously defined as a bit field, except that only a few
106     * combinations were actually supported so the bit field was removed.  This explains
107     * why the numbering scheme is so odd.  If adding a new wake lock level, any unused
108     * value can be used.
109     */
110
111    /**
112     * Wake lock level: Ensures that the CPU is running; the screen and keyboard
113     * backlight will be allowed to go off.
114     * <p>
115     * If the user presses the power button, then the screen will be turned off
116     * but the CPU will be kept on until all partial wake locks have been released.
117     * </p>
118     */
119    public static final int PARTIAL_WAKE_LOCK = 0x00000001;
120
121    /**
122     * Wake lock level: Ensures that the screen is on (but may be dimmed);
123     * the keyboard backlight will be allowed to go off.
124     * <p>
125     * If the user presses the power button, then the {@link #SCREEN_DIM_WAKE_LOCK} will be
126     * implicitly released by the system, causing both the screen and the CPU to be turned off.
127     * Contrast with {@link #PARTIAL_WAKE_LOCK}.
128     * </p>
129     *
130     * @deprecated Most applications should use
131     * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead
132     * of this type of wake lock, as it will be correctly managed by the platform
133     * as the user moves between applications and doesn't require a special permission.
134     */
135    @Deprecated
136    public static final int SCREEN_DIM_WAKE_LOCK = 0x00000006;
137
138    /**
139     * Wake lock level: Ensures that the screen is on at full brightness;
140     * the keyboard backlight will be allowed to go off.
141     * <p>
142     * If the user presses the power button, then the {@link #SCREEN_BRIGHT_WAKE_LOCK} will be
143     * implicitly released by the system, causing both the screen and the CPU to be turned off.
144     * Contrast with {@link #PARTIAL_WAKE_LOCK}.
145     * </p>
146     *
147     * @deprecated Most applications should use
148     * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead
149     * of this type of wake lock, as it will be correctly managed by the platform
150     * as the user moves between applications and doesn't require a special permission.
151     */
152    @Deprecated
153    public static final int SCREEN_BRIGHT_WAKE_LOCK = 0x0000000a;
154
155    /**
156     * Wake lock level: Ensures that the screen and keyboard backlight are on at
157     * full brightness.
158     * <p>
159     * If the user presses the power button, then the {@link #FULL_WAKE_LOCK} will be
160     * implicitly released by the system, causing both the screen and the CPU to be turned off.
161     * Contrast with {@link #PARTIAL_WAKE_LOCK}.
162     * </p>
163     *
164     * @deprecated Most applications should use
165     * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead
166     * of this type of wake lock, as it will be correctly managed by the platform
167     * as the user moves between applications and doesn't require a special permission.
168     */
169    @Deprecated
170    public static final int FULL_WAKE_LOCK = 0x0000001a;
171
172    /**
173     * Wake lock level: Turns the screen off when the proximity sensor activates.
174     * <p>
175     * If the proximity sensor detects that an object is nearby, the screen turns off
176     * immediately.  Shortly after the object moves away, the screen turns on again.
177     * </p><p>
178     * A proximity wake lock does not prevent the device from falling asleep
179     * unlike {@link #FULL_WAKE_LOCK}, {@link #SCREEN_BRIGHT_WAKE_LOCK} and
180     * {@link #SCREEN_DIM_WAKE_LOCK}.  If there is no user activity and no other
181     * wake locks are held, then the device will fall asleep (and lock) as usual.
182     * However, the device will not fall asleep while the screen has been turned off
183     * by the proximity sensor because it effectively counts as ongoing user activity.
184     * </p><p>
185     * Since not all devices have proximity sensors, use {@link #isWakeLockLevelSupported}
186     * to determine whether this wake lock level is supported.
187     * </p><p>
188     * Cannot be used with {@link #ACQUIRE_CAUSES_WAKEUP}.
189     * </p>
190     */
191    public static final int PROXIMITY_SCREEN_OFF_WAKE_LOCK = 0x00000020;
192
193    /**
194     * Wake lock level: Put the screen in a low power state and allow the CPU to suspend
195     * if no other wake locks are held.
196     * <p>
197     * This is used by the dream manager to implement doze mode.  It currently
198     * has no effect unless the power manager is in the dozing state.
199     * </p><p>
200     * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.
201     * </p>
202     *
203     * {@hide}
204     */
205    public static final int DOZE_WAKE_LOCK = 0x00000040;
206
207    /**
208     * Wake lock level: Keep the device awake enough to allow drawing to occur.
209     * <p>
210     * This is used by the window manager to allow applications to draw while the
211     * system is dozing.  It currently has no effect unless the power manager is in
212     * the dozing state.
213     * </p><p>
214     * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.
215     * </p>
216     *
217     * {@hide}
218     */
219    public static final int DRAW_WAKE_LOCK = 0x00000080;
220
221    /**
222     * Mask for the wake lock level component of a combined wake lock level and flags integer.
223     *
224     * @hide
225     */
226    public static final int WAKE_LOCK_LEVEL_MASK = 0x0000ffff;
227
228    /**
229     * Wake lock flag: Turn the screen on when the wake lock is acquired.
230     * <p>
231     * Normally wake locks don't actually wake the device, they just cause
232     * the screen to remain on once it's already on.  Think of the video player
233     * application as the normal behavior.  Notifications that pop up and want
234     * the device to be on are the exception; use this flag to be like them.
235     * </p><p>
236     * Cannot be used with {@link #PARTIAL_WAKE_LOCK}.
237     * </p>
238     */
239    public static final int ACQUIRE_CAUSES_WAKEUP = 0x10000000;
240
241    /**
242     * Wake lock flag: When this wake lock is released, poke the user activity timer
243     * so the screen stays on for a little longer.
244     * <p>
245     * Will not turn the screen on if it is not already on.
246     * See {@link #ACQUIRE_CAUSES_WAKEUP} if you want that.
247     * </p><p>
248     * Cannot be used with {@link #PARTIAL_WAKE_LOCK}.
249     * </p>
250     */
251    public static final int ON_AFTER_RELEASE = 0x20000000;
252
253    /**
254     * Wake lock flag: This wake lock is not important for logging events.  If a later
255     * wake lock is acquired that is important, it will be considered the one to log.
256     * @hide
257     */
258    public static final int UNIMPORTANT_FOR_LOGGING = 0x40000000;
259
260    /**
261     * Flag for {@link WakeLock#release WakeLock.release(int)}: Defer releasing a
262     * {@link #PROXIMITY_SCREEN_OFF_WAKE_LOCK} wake lock until the proximity sensor
263     * indicates that an object is not in close proximity.
264     */
265    public static final int RELEASE_FLAG_WAIT_FOR_NO_PROXIMITY = 1;
266
267    /**
268     * Brightness value for fully on.
269     * @hide
270     */
271    public static final int BRIGHTNESS_ON = 255;
272
273    /**
274     * Brightness value for fully off.
275     * @hide
276     */
277    public static final int BRIGHTNESS_OFF = 0;
278
279    /**
280     * Brightness value for default policy handling by the system.
281     * @hide
282     */
283    public static final int BRIGHTNESS_DEFAULT = -1;
284
285    // Note: Be sure to update android.os.BatteryStats and PowerManager.h
286    // if adding or modifying user activity event constants.
287
288    /**
289     * User activity event type: Unspecified event type.
290     * @hide
291     */
292    @SystemApi
293    public static final int USER_ACTIVITY_EVENT_OTHER = 0;
294
295    /**
296     * User activity event type: Button or key pressed or released.
297     * @hide
298     */
299    @SystemApi
300    public static final int USER_ACTIVITY_EVENT_BUTTON = 1;
301
302    /**
303     * User activity event type: Touch down, move or up.
304     * @hide
305     */
306    @SystemApi
307    public static final int USER_ACTIVITY_EVENT_TOUCH = 2;
308
309    /**
310     * User activity flag: If already dimmed, extend the dim timeout
311     * but do not brighten.  This flag is useful for keeping the screen on
312     * a little longer without causing a visible change such as when
313     * the power key is pressed.
314     * @hide
315     */
316    @SystemApi
317    public static final int USER_ACTIVITY_FLAG_NO_CHANGE_LIGHTS = 1 << 0;
318
319    /**
320     * User activity flag: Note the user activity as usual but do not
321     * reset the user activity timeout.  This flag is useful for applying
322     * user activity power hints when interacting with the device indirectly
323     * on a secondary screen while allowing the primary screen to go to sleep.
324     * @hide
325     */
326    @SystemApi
327    public static final int USER_ACTIVITY_FLAG_INDIRECT = 1 << 1;
328
329    /**
330     * Go to sleep reason code: Going to sleep due by application request.
331     * @hide
332     */
333    public static final int GO_TO_SLEEP_REASON_APPLICATION = 0;
334
335    /**
336     * Go to sleep reason code: Going to sleep due by request of the
337     * device administration policy.
338     * @hide
339     */
340    public static final int GO_TO_SLEEP_REASON_DEVICE_ADMIN = 1;
341
342    /**
343     * Go to sleep reason code: Going to sleep due to a screen timeout.
344     * @hide
345     */
346    public static final int GO_TO_SLEEP_REASON_TIMEOUT = 2;
347
348    /**
349     * Go to sleep reason code: Going to sleep due to the lid switch being closed.
350     * @hide
351     */
352    public static final int GO_TO_SLEEP_REASON_LID_SWITCH = 3;
353
354    /**
355     * Go to sleep reason code: Going to sleep due to the power button being pressed.
356     * @hide
357     */
358    public static final int GO_TO_SLEEP_REASON_POWER_BUTTON = 4;
359
360    /**
361     * Go to sleep reason code: Going to sleep due to HDMI.
362     * @hide
363     */
364    public static final int GO_TO_SLEEP_REASON_HDMI = 5;
365
366    /**
367     * Go to sleep reason code: Going to sleep due to the sleep button being pressed.
368     * @hide
369     */
370    public static final int GO_TO_SLEEP_REASON_SLEEP_BUTTON = 6;
371
372    /**
373     * Go to sleep flag: Skip dozing state and directly go to full sleep.
374     * @hide
375     */
376    public static final int GO_TO_SLEEP_FLAG_NO_DOZE = 1 << 0;
377
378    /**
379     * The value to pass as the 'reason' argument to reboot() to
380     * reboot into recovery mode (for applying system updates, doing
381     * factory resets, etc.).
382     * <p>
383     * Requires the {@link android.Manifest.permission#RECOVERY}
384     * permission (in addition to
385     * {@link android.Manifest.permission#REBOOT}).
386     * </p>
387     * @hide
388     */
389    public static final String REBOOT_RECOVERY = "recovery";
390
391    final Context mContext;
392    final IPowerManager mService;
393    final Handler mHandler;
394
395    IDeviceIdleController mIDeviceIdleController;
396
397    /**
398     * {@hide}
399     */
400    public PowerManager(Context context, IPowerManager service, Handler handler) {
401        mContext = context;
402        mService = service;
403        mHandler = handler;
404    }
405
406    /**
407     * Gets the minimum supported screen brightness setting.
408     * The screen may be allowed to become dimmer than this value but
409     * this is the minimum value that can be set by the user.
410     * @hide
411     */
412    public int getMinimumScreenBrightnessSetting() {
413        return mContext.getResources().getInteger(
414                com.android.internal.R.integer.config_screenBrightnessSettingMinimum);
415    }
416
417    /**
418     * Gets the maximum supported screen brightness setting.
419     * The screen may be allowed to become dimmer than this value but
420     * this is the maximum value that can be set by the user.
421     * @hide
422     */
423    public int getMaximumScreenBrightnessSetting() {
424        return mContext.getResources().getInteger(
425                com.android.internal.R.integer.config_screenBrightnessSettingMaximum);
426    }
427
428    /**
429     * Gets the default screen brightness setting.
430     * @hide
431     */
432    public int getDefaultScreenBrightnessSetting() {
433        return mContext.getResources().getInteger(
434                com.android.internal.R.integer.config_screenBrightnessSettingDefault);
435    }
436
437    /**
438     * Returns true if the twilight service should be used to adjust screen brightness
439     * policy.  This setting is experimental and disabled by default.
440     * @hide
441     */
442    public static boolean useTwilightAdjustmentFeature() {
443        return SystemProperties.getBoolean("persist.power.usetwilightadj", false);
444    }
445
446    /**
447     * Creates a new wake lock with the specified level and flags.
448     * <p>
449     * The {@code levelAndFlags} parameter specifies a wake lock level and optional flags
450     * combined using the logical OR operator.
451     * </p><p>
452     * The wake lock levels are: {@link #PARTIAL_WAKE_LOCK},
453     * {@link #FULL_WAKE_LOCK}, {@link #SCREEN_DIM_WAKE_LOCK}
454     * and {@link #SCREEN_BRIGHT_WAKE_LOCK}.  Exactly one wake lock level must be
455     * specified as part of the {@code levelAndFlags} parameter.
456     * </p><p>
457     * The wake lock flags are: {@link #ACQUIRE_CAUSES_WAKEUP}
458     * and {@link #ON_AFTER_RELEASE}.  Multiple flags can be combined as part of the
459     * {@code levelAndFlags} parameters.
460     * </p><p>
461     * Call {@link WakeLock#acquire() acquire()} on the object to acquire the
462     * wake lock, and {@link WakeLock#release release()} when you are done.
463     * </p><p>
464     * {@samplecode
465     * PowerManager pm = (PowerManager)mContext.getSystemService(
466     *                                          Context.POWER_SERVICE);
467     * PowerManager.WakeLock wl = pm.newWakeLock(
468     *                                      PowerManager.SCREEN_DIM_WAKE_LOCK
469     *                                      | PowerManager.ON_AFTER_RELEASE,
470     *                                      TAG);
471     * wl.acquire();
472     * // ... do work...
473     * wl.release();
474     * }
475     * </p><p>
476     * Although a wake lock can be created without special permissions,
477     * the {@link android.Manifest.permission#WAKE_LOCK} permission is
478     * required to actually acquire or release the wake lock that is returned.
479     * </p><p class="note">
480     * If using this to keep the screen on, you should strongly consider using
481     * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead.
482     * This window flag will be correctly managed by the platform
483     * as the user moves between applications and doesn't require a special permission.
484     * </p>
485     *
486     * @param levelAndFlags Combination of wake lock level and flag values defining
487     * the requested behavior of the WakeLock.
488     * @param tag Your class name (or other tag) for debugging purposes.
489     *
490     * @see WakeLock#acquire()
491     * @see WakeLock#release()
492     * @see #PARTIAL_WAKE_LOCK
493     * @see #FULL_WAKE_LOCK
494     * @see #SCREEN_DIM_WAKE_LOCK
495     * @see #SCREEN_BRIGHT_WAKE_LOCK
496     * @see #PROXIMITY_SCREEN_OFF_WAKE_LOCK
497     * @see #ACQUIRE_CAUSES_WAKEUP
498     * @see #ON_AFTER_RELEASE
499     */
500    public WakeLock newWakeLock(int levelAndFlags, String tag) {
501        validateWakeLockParameters(levelAndFlags, tag);
502        return new WakeLock(levelAndFlags, tag, mContext.getOpPackageName());
503    }
504
505    /** @hide */
506    public static void validateWakeLockParameters(int levelAndFlags, String tag) {
507        switch (levelAndFlags & WAKE_LOCK_LEVEL_MASK) {
508            case PARTIAL_WAKE_LOCK:
509            case SCREEN_DIM_WAKE_LOCK:
510            case SCREEN_BRIGHT_WAKE_LOCK:
511            case FULL_WAKE_LOCK:
512            case PROXIMITY_SCREEN_OFF_WAKE_LOCK:
513            case DOZE_WAKE_LOCK:
514            case DRAW_WAKE_LOCK:
515                break;
516            default:
517                throw new IllegalArgumentException("Must specify a valid wake lock level.");
518        }
519        if (tag == null) {
520            throw new IllegalArgumentException("The tag must not be null.");
521        }
522    }
523
524    /**
525     * Notifies the power manager that user activity happened.
526     * <p>
527     * Resets the auto-off timer and brightens the screen if the device
528     * is not asleep.  This is what happens normally when a key or the touch
529     * screen is pressed or when some other user activity occurs.
530     * This method does not wake up the device if it has been put to sleep.
531     * </p><p>
532     * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.
533     * </p>
534     *
535     * @param when The time of the user activity, in the {@link SystemClock#uptimeMillis()}
536     * time base.  This timestamp is used to correctly order the user activity request with
537     * other power management functions.  It should be set
538     * to the timestamp of the input event that caused the user activity.
539     * @param noChangeLights If true, does not cause the keyboard backlight to turn on
540     * because of this event.  This is set when the power key is pressed.
541     * We want the device to stay on while the button is down, but we're about
542     * to turn off the screen so we don't want the keyboard backlight to turn on again.
543     * Otherwise the lights flash on and then off and it looks weird.
544     *
545     * @see #wakeUp
546     * @see #goToSleep
547     *
548     * @removed Requires signature or system permission.
549     * @deprecated Use {@link #userActivity(long, int, int)}.
550     */
551    @Deprecated
552    public void userActivity(long when, boolean noChangeLights) {
553        userActivity(when, USER_ACTIVITY_EVENT_OTHER,
554                noChangeLights ? USER_ACTIVITY_FLAG_NO_CHANGE_LIGHTS : 0);
555    }
556
557    /**
558     * Notifies the power manager that user activity happened.
559     * <p>
560     * Resets the auto-off timer and brightens the screen if the device
561     * is not asleep.  This is what happens normally when a key or the touch
562     * screen is pressed or when some other user activity occurs.
563     * This method does not wake up the device if it has been put to sleep.
564     * </p><p>
565     * Requires the {@link android.Manifest.permission#DEVICE_POWER} or
566     * {@link android.Manifest.permission#USER_ACTIVITY} permission.
567     * </p>
568     *
569     * @param when The time of the user activity, in the {@link SystemClock#uptimeMillis()}
570     * time base.  This timestamp is used to correctly order the user activity request with
571     * other power management functions.  It should be set
572     * to the timestamp of the input event that caused the user activity.
573     * @param event The user activity event.
574     * @param flags Optional user activity flags.
575     *
576     * @see #wakeUp
577     * @see #goToSleep
578     *
579     * @hide Requires signature or system permission.
580     */
581    @SystemApi
582    public void userActivity(long when, int event, int flags) {
583        try {
584            mService.userActivity(when, event, flags);
585        } catch (RemoteException e) {
586        }
587    }
588
589   /**
590     * Forces the device to go to sleep.
591     * <p>
592     * Overrides all the wake locks that are held.
593     * This is what happens when the power key is pressed to turn off the screen.
594     * </p><p>
595     * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.
596     * </p>
597     *
598     * @param time The time when the request to go to sleep was issued, in the
599     * {@link SystemClock#uptimeMillis()} time base.  This timestamp is used to correctly
600     * order the go to sleep request with other power management functions.  It should be set
601     * to the timestamp of the input event that caused the request to go to sleep.
602     *
603     * @see #userActivity
604     * @see #wakeUp
605     *
606     * @removed Requires signature permission.
607     */
608    public void goToSleep(long time) {
609        goToSleep(time, GO_TO_SLEEP_REASON_APPLICATION, 0);
610    }
611
612    /**
613     * Forces the device to go to sleep.
614     * <p>
615     * Overrides all the wake locks that are held.
616     * This is what happens when the power key is pressed to turn off the screen.
617     * </p><p>
618     * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.
619     * </p>
620     *
621     * @param time The time when the request to go to sleep was issued, in the
622     * {@link SystemClock#uptimeMillis()} time base.  This timestamp is used to correctly
623     * order the go to sleep request with other power management functions.  It should be set
624     * to the timestamp of the input event that caused the request to go to sleep.
625     * @param reason The reason the device is going to sleep.
626     * @param flags Optional flags to apply when going to sleep.
627     *
628     * @see #userActivity
629     * @see #wakeUp
630     *
631     * @hide Requires signature permission.
632     */
633    public void goToSleep(long time, int reason, int flags) {
634        try {
635            mService.goToSleep(time, reason, flags);
636        } catch (RemoteException e) {
637        }
638    }
639
640    /**
641     * Forces the device to wake up from sleep.
642     * <p>
643     * If the device is currently asleep, wakes it up, otherwise does nothing.
644     * This is what happens when the power key is pressed to turn on the screen.
645     * </p><p>
646     * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.
647     * </p>
648     *
649     * @param time The time when the request to wake up was issued, in the
650     * {@link SystemClock#uptimeMillis()} time base.  This timestamp is used to correctly
651     * order the wake up request with other power management functions.  It should be set
652     * to the timestamp of the input event that caused the request to wake up.
653     *
654     * @see #userActivity
655     * @see #goToSleep
656     *
657     * @removed Requires signature permission.
658     */
659    public void wakeUp(long time) {
660        try {
661            mService.wakeUp(time, "wakeUp", mContext.getOpPackageName());
662        } catch (RemoteException e) {
663        }
664    }
665
666    /**
667     * @hide
668     */
669    public void wakeUp(long time, String reason) {
670        try {
671            mService.wakeUp(time, reason, mContext.getOpPackageName());
672        } catch (RemoteException e) {
673        }
674    }
675
676    /**
677     * Forces the device to start napping.
678     * <p>
679     * If the device is currently awake, starts dreaming, otherwise does nothing.
680     * When the dream ends or if the dream cannot be started, the device will
681     * either wake up or go to sleep depending on whether there has been recent
682     * user activity.
683     * </p><p>
684     * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.
685     * </p>
686     *
687     * @param time The time when the request to nap was issued, in the
688     * {@link SystemClock#uptimeMillis()} time base.  This timestamp is used to correctly
689     * order the nap request with other power management functions.  It should be set
690     * to the timestamp of the input event that caused the request to nap.
691     *
692     * @see #wakeUp
693     * @see #goToSleep
694     *
695     * @hide Requires signature permission.
696     */
697    public void nap(long time) {
698        try {
699            mService.nap(time);
700        } catch (RemoteException e) {
701        }
702    }
703
704    /**
705     * Boosts the brightness of the screen to maximum for a predetermined
706     * period of time.  This is used to make the screen more readable in bright
707     * daylight for a short duration.
708     * <p>
709     * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.
710     * </p>
711     *
712     * @param time The time when the request to boost was issued, in the
713     * {@link SystemClock#uptimeMillis()} time base.  This timestamp is used to correctly
714     * order the boost request with other power management functions.  It should be set
715     * to the timestamp of the input event that caused the request to boost.
716     *
717     * @hide Requires signature permission.
718     */
719    public void boostScreenBrightness(long time) {
720        try {
721            mService.boostScreenBrightness(time);
722        } catch (RemoteException e) {
723        }
724    }
725
726    /**
727     * Returns whether the screen brightness is currently boosted to maximum, caused by a call
728     * to {@link #boostScreenBrightness(long)}.
729     * @return {@code True} if the screen brightness is currently boosted. {@code False} otherwise.
730     *
731     * @hide
732     */
733    @SystemApi
734    public boolean isScreenBrightnessBoosted() {
735        try {
736            return mService.isScreenBrightnessBoosted();
737        } catch (RemoteException e) {
738            return false;
739        }
740    }
741
742    /**
743     * Sets the brightness of the backlights (screen, keyboard, button).
744     * <p>
745     * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission.
746     * </p>
747     *
748     * @param brightness The brightness value from 0 to 255.
749     *
750     * @hide Requires signature permission.
751     */
752    public void setBacklightBrightness(int brightness) {
753        try {
754            mService.setTemporaryScreenBrightnessSettingOverride(brightness);
755        } catch (RemoteException e) {
756        }
757    }
758
759   /**
760     * Returns true if the specified wake lock level is supported.
761     *
762     * @param level The wake lock level to check.
763     * @return True if the specified wake lock level is supported.
764     */
765    public boolean isWakeLockLevelSupported(int level) {
766        try {
767            return mService.isWakeLockLevelSupported(level);
768        } catch (RemoteException e) {
769            return false;
770        }
771    }
772
773    /**
774      * Returns true if the device is in an interactive state.
775      * <p>
776      * For historical reasons, the name of this method refers to the power state of
777      * the screen but it actually describes the overall interactive state of
778      * the device.  This method has been replaced by {@link #isInteractive}.
779      * </p><p>
780      * The value returned by this method only indicates whether the device is
781      * in an interactive state which may have nothing to do with the screen being
782      * on or off.  To determine the actual state of the screen,
783      * use {@link android.view.Display#getState}.
784      * </p>
785      *
786      * @return True if the device is in an interactive state.
787      *
788      * @deprecated Use {@link #isInteractive} instead.
789      */
790    @Deprecated
791    public boolean isScreenOn() {
792        return isInteractive();
793    }
794
795    /**
796     * Returns true if the device is in an interactive state.
797     * <p>
798     * When this method returns true, the device is awake and ready to interact
799     * with the user (although this is not a guarantee that the user is actively
800     * interacting with the device just this moment).  The main screen is usually
801     * turned on while in this state.  Certain features, such as the proximity
802     * sensor, may temporarily turn off the screen while still leaving the device in an
803     * interactive state.  Note in particular that the device is still considered
804     * to be interactive while dreaming (since dreams can be interactive) but not
805     * when it is dozing or asleep.
806     * </p><p>
807     * When this method returns false, the device is dozing or asleep and must
808     * be awoken before it will become ready to interact with the user again.  The
809     * main screen is usually turned off while in this state.  Certain features,
810     * such as "ambient mode" may cause the main screen to remain on (albeit in a
811     * low power state) to display system-provided content while the device dozes.
812     * </p><p>
813     * The system will send a {@link android.content.Intent#ACTION_SCREEN_ON screen on}
814     * or {@link android.content.Intent#ACTION_SCREEN_OFF screen off} broadcast
815     * whenever the interactive state of the device changes.  For historical reasons,
816     * the names of these broadcasts refer to the power state of the screen
817     * but they are actually sent in response to changes in the overall interactive
818     * state of the device, as described by this method.
819     * </p><p>
820     * Services may use the non-interactive state as a hint to conserve power
821     * since the user is not present.
822     * </p>
823     *
824     * @return True if the device is in an interactive state.
825     *
826     * @see android.content.Intent#ACTION_SCREEN_ON
827     * @see android.content.Intent#ACTION_SCREEN_OFF
828     */
829    public boolean isInteractive() {
830        try {
831            return mService.isInteractive();
832        } catch (RemoteException e) {
833            return false;
834        }
835    }
836
837    /**
838     * Reboot the device.  Will not return if the reboot is successful.
839     * <p>
840     * Requires the {@link android.Manifest.permission#REBOOT} permission.
841     * </p>
842     *
843     * @param reason code to pass to the kernel (e.g., "recovery") to
844     *               request special boot modes, or null.
845     */
846    public void reboot(String reason) {
847        try {
848            mService.reboot(false, reason, true);
849        } catch (RemoteException e) {
850        }
851    }
852
853    /**
854     * Returns true if the device is currently in power save mode.  When in this mode,
855     * applications should reduce their functionality in order to conserve battery as
856     * much as possible.  You can monitor for changes to this state with
857     * {@link #ACTION_POWER_SAVE_MODE_CHANGED}.
858     *
859     * @return Returns true if currently in low power mode, else false.
860     */
861    public boolean isPowerSaveMode() {
862        try {
863            return mService.isPowerSaveMode();
864        } catch (RemoteException e) {
865            return false;
866        }
867    }
868
869    /**
870     * Set the current power save mode.
871     *
872     * @return True if the set was allowed.
873     *
874     * @see #isPowerSaveMode()
875     *
876     * @hide
877     */
878    public boolean setPowerSaveMode(boolean mode) {
879        try {
880            return mService.setPowerSaveMode(mode);
881        } catch (RemoteException e) {
882            return false;
883        }
884    }
885
886    /**
887     * Returns true if the device is currently in idle mode.  This happens when a device
888     * has been sitting unused and unmoving for a sufficiently long period of time, so that
889     * it decides to go into a lower power-use state.  This may involve things like turning
890     * off network access to apps.  You can monitor for changes to this state with
891     * {@link #ACTION_DEVICE_IDLE_MODE_CHANGED}.
892     *
893     * @return Returns true if currently in active device idle mode, else false.  This is
894     * when idle mode restrictions are being actively applied; it will return false if the
895     * device is in a long-term idle mode but currently running a maintenance window where
896     * restrictions have been lifted.
897     */
898    public boolean isDeviceIdleMode() {
899        try {
900            return mService.isDeviceIdleMode();
901        } catch (RemoteException e) {
902            return false;
903        }
904    }
905
906    /**
907     * Return whether the given application package name is on the device's power whitelist.
908     * Apps can be placed on the whitelist through the settings UI invoked by
909     * {@link android.provider.Settings#ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS}.
910     */
911    public boolean isIgnoringBatteryOptimizations(String packageName) {
912        synchronized (this) {
913            if (mIDeviceIdleController == null) {
914                mIDeviceIdleController = IDeviceIdleController.Stub.asInterface(
915                        ServiceManager.getService(Context.DEVICE_IDLE_CONTROLLER));
916            }
917        }
918        try {
919            return mIDeviceIdleController.isPowerSaveWhitelistApp(packageName);
920        } catch (RemoteException e) {
921            return false;
922        }
923    }
924
925    /**
926     * Turn off the device.
927     *
928     * @param confirm If true, shows a shutdown confirmation dialog.
929     * @param wait If true, this call waits for the shutdown to complete and does not return.
930     *
931     * @hide
932     */
933    public void shutdown(boolean confirm, boolean wait) {
934        try {
935            mService.shutdown(confirm, wait);
936        } catch (RemoteException e) {
937        }
938    }
939
940    /**
941     * Intent that is broadcast when the state of {@link #isPowerSaveMode()} changes.
942     * This broadcast is only sent to registered receivers.
943     */
944    @SdkConstant(SdkConstant.SdkConstantType.BROADCAST_INTENT_ACTION)
945    public static final String ACTION_POWER_SAVE_MODE_CHANGED
946            = "android.os.action.POWER_SAVE_MODE_CHANGED";
947
948    /**
949     * Intent that is broadcast when the state of {@link #isDeviceIdleMode()} changes.
950     * This broadcast is only sent to registered receivers.
951     */
952    @SdkConstant(SdkConstant.SdkConstantType.BROADCAST_INTENT_ACTION)
953    public static final String ACTION_DEVICE_IDLE_MODE_CHANGED
954            = "android.os.action.DEVICE_IDLE_MODE_CHANGED";
955
956    /**
957     * @hide Intent that is broadcast when the set of power save whitelist apps has changed.
958     * This broadcast is only sent to registered receivers.
959     */
960    @SdkConstant(SdkConstant.SdkConstantType.BROADCAST_INTENT_ACTION)
961    public static final String ACTION_POWER_SAVE_WHITELIST_CHANGED
962            = "android.os.action.POWER_SAVE_WHITELIST_CHANGED";
963
964    /**
965     * @hide Intent that is broadcast when the set of temporarily whitelisted apps has changed.
966     * This broadcast is only sent to registered receivers.
967     */
968    @SdkConstant(SdkConstant.SdkConstantType.BROADCAST_INTENT_ACTION)
969    public static final String ACTION_POWER_SAVE_TEMP_WHITELIST_CHANGED
970            = "android.os.action.POWER_SAVE_TEMP_WHITELIST_CHANGED";
971
972    /**
973     * Intent that is broadcast when the state of {@link #isPowerSaveMode()} is about to change.
974     * This broadcast is only sent to registered receivers.
975     *
976     * @hide
977     */
978    @SdkConstant(SdkConstant.SdkConstantType.BROADCAST_INTENT_ACTION)
979    public static final String ACTION_POWER_SAVE_MODE_CHANGING
980            = "android.os.action.POWER_SAVE_MODE_CHANGING";
981
982    /** @hide */
983    public static final String EXTRA_POWER_SAVE_MODE = "mode";
984
985    /**
986     * Intent that is broadcast when the state of {@link #isScreenBrightnessBoosted()} has changed.
987     * This broadcast is only sent to registered receivers.
988     *
989     * @hide
990     **/
991    @SystemApi
992    public static final String ACTION_SCREEN_BRIGHTNESS_BOOST_CHANGED
993            = "android.os.action.SCREEN_BRIGHTNESS_BOOST_CHANGED";
994
995    /**
996     * A wake lock is a mechanism to indicate that your application needs
997     * to have the device stay on.
998     * <p>
999     * Any application using a WakeLock must request the {@code android.permission.WAKE_LOCK}
1000     * permission in an {@code &lt;uses-permission&gt;} element of the application's manifest.
1001     * Obtain a wake lock by calling {@link PowerManager#newWakeLock(int, String)}.
1002     * </p><p>
1003     * Call {@link #acquire()} to acquire the wake lock and force the device to stay
1004     * on at the level that was requested when the wake lock was created.
1005     * </p><p>
1006     * Call {@link #release()} when you are done and don't need the lock anymore.
1007     * It is very important to do this as soon as possible to avoid running down the
1008     * device's battery excessively.
1009     * </p>
1010     */
1011    public final class WakeLock {
1012        private int mFlags;
1013        private String mTag;
1014        private final String mPackageName;
1015        private final IBinder mToken;
1016        private int mCount;
1017        private boolean mRefCounted = true;
1018        private boolean mHeld;
1019        private WorkSource mWorkSource;
1020        private String mHistoryTag;
1021        private final String mTraceName;
1022
1023        private final Runnable mReleaser = new Runnable() {
1024            public void run() {
1025                release();
1026            }
1027        };
1028
1029        WakeLock(int flags, String tag, String packageName) {
1030            mFlags = flags;
1031            mTag = tag;
1032            mPackageName = packageName;
1033            mToken = new Binder();
1034            mTraceName = "WakeLock (" + mTag + ")";
1035        }
1036
1037        @Override
1038        protected void finalize() throws Throwable {
1039            synchronized (mToken) {
1040                if (mHeld) {
1041                    Log.wtf(TAG, "WakeLock finalized while still held: " + mTag);
1042                    Trace.asyncTraceEnd(Trace.TRACE_TAG_POWER, mTraceName, 0);
1043                    try {
1044                        mService.releaseWakeLock(mToken, 0);
1045                    } catch (RemoteException e) {
1046                    }
1047                }
1048            }
1049        }
1050
1051        /**
1052         * Sets whether this WakeLock is reference counted.
1053         * <p>
1054         * Wake locks are reference counted by default.  If a wake lock is
1055         * reference counted, then each call to {@link #acquire()} must be
1056         * balanced by an equal number of calls to {@link #release()}.  If a wake
1057         * lock is not reference counted, then one call to {@link #release()} is
1058         * sufficient to undo the effect of all previous calls to {@link #acquire()}.
1059         * </p>
1060         *
1061         * @param value True to make the wake lock reference counted, false to
1062         * make the wake lock non-reference counted.
1063         */
1064        public void setReferenceCounted(boolean value) {
1065            synchronized (mToken) {
1066                mRefCounted = value;
1067            }
1068        }
1069
1070        /**
1071         * Acquires the wake lock.
1072         * <p>
1073         * Ensures that the device is on at the level requested when
1074         * the wake lock was created.
1075         * </p>
1076         */
1077        public void acquire() {
1078            synchronized (mToken) {
1079                acquireLocked();
1080            }
1081        }
1082
1083        /**
1084         * Acquires the wake lock with a timeout.
1085         * <p>
1086         * Ensures that the device is on at the level requested when
1087         * the wake lock was created.  The lock will be released after the given timeout
1088         * expires.
1089         * </p>
1090         *
1091         * @param timeout The timeout after which to release the wake lock, in milliseconds.
1092         */
1093        public void acquire(long timeout) {
1094            synchronized (mToken) {
1095                acquireLocked();
1096                mHandler.postDelayed(mReleaser, timeout);
1097            }
1098        }
1099
1100        private void acquireLocked() {
1101            if (!mRefCounted || mCount++ == 0) {
1102                // Do this even if the wake lock is already thought to be held (mHeld == true)
1103                // because non-reference counted wake locks are not always properly released.
1104                // For example, the keyguard's wake lock might be forcibly released by the
1105                // power manager without the keyguard knowing.  A subsequent call to acquire
1106                // should immediately acquire the wake lock once again despite never having
1107                // been explicitly released by the keyguard.
1108                mHandler.removeCallbacks(mReleaser);
1109                Trace.asyncTraceBegin(Trace.TRACE_TAG_POWER, mTraceName, 0);
1110                try {
1111                    mService.acquireWakeLock(mToken, mFlags, mTag, mPackageName, mWorkSource,
1112                            mHistoryTag);
1113                } catch (RemoteException e) {
1114                }
1115                mHeld = true;
1116            }
1117        }
1118
1119        /**
1120         * Releases the wake lock.
1121         * <p>
1122         * This method releases your claim to the CPU or screen being on.
1123         * The screen may turn off shortly after you release the wake lock, or it may
1124         * not if there are other wake locks still held.
1125         * </p>
1126         */
1127        public void release() {
1128            release(0);
1129        }
1130
1131        /**
1132         * Releases the wake lock with flags to modify the release behavior.
1133         * <p>
1134         * This method releases your claim to the CPU or screen being on.
1135         * The screen may turn off shortly after you release the wake lock, or it may
1136         * not if there are other wake locks still held.
1137         * </p>
1138         *
1139         * @param flags Combination of flag values to modify the release behavior.
1140         * Currently only {@link #RELEASE_FLAG_WAIT_FOR_NO_PROXIMITY} is supported.
1141         * Passing 0 is equivalent to calling {@link #release()}.
1142         */
1143        public void release(int flags) {
1144            synchronized (mToken) {
1145                if (!mRefCounted || --mCount == 0) {
1146                    mHandler.removeCallbacks(mReleaser);
1147                    if (mHeld) {
1148                        Trace.asyncTraceEnd(Trace.TRACE_TAG_POWER, mTraceName, 0);
1149                        try {
1150                            mService.releaseWakeLock(mToken, flags);
1151                        } catch (RemoteException e) {
1152                        }
1153                        mHeld = false;
1154                    }
1155                }
1156                if (mCount < 0) {
1157                    throw new RuntimeException("WakeLock under-locked " + mTag);
1158                }
1159            }
1160        }
1161
1162        /**
1163         * Returns true if the wake lock has been acquired but not yet released.
1164         *
1165         * @return True if the wake lock is held.
1166         */
1167        public boolean isHeld() {
1168            synchronized (mToken) {
1169                return mHeld;
1170            }
1171        }
1172
1173        /**
1174         * Sets the work source associated with the wake lock.
1175         * <p>
1176         * The work source is used to determine on behalf of which application
1177         * the wake lock is being held.  This is useful in the case where a
1178         * service is performing work on behalf of an application so that the
1179         * cost of that work can be accounted to the application.
1180         * </p>
1181         *
1182         * @param ws The work source, or null if none.
1183         */
1184        public void setWorkSource(WorkSource ws) {
1185            synchronized (mToken) {
1186                if (ws != null && ws.size() == 0) {
1187                    ws = null;
1188                }
1189
1190                final boolean changed;
1191                if (ws == null) {
1192                    changed = mWorkSource != null;
1193                    mWorkSource = null;
1194                } else if (mWorkSource == null) {
1195                    changed = true;
1196                    mWorkSource = new WorkSource(ws);
1197                } else {
1198                    changed = mWorkSource.diff(ws);
1199                    if (changed) {
1200                        mWorkSource.set(ws);
1201                    }
1202                }
1203
1204                if (changed && mHeld) {
1205                    try {
1206                        mService.updateWakeLockWorkSource(mToken, mWorkSource, mHistoryTag);
1207                    } catch (RemoteException e) {
1208                    }
1209                }
1210            }
1211        }
1212
1213        /** @hide */
1214        public void setTag(String tag) {
1215            mTag = tag;
1216        }
1217
1218        /** @hide */
1219        public void setHistoryTag(String tag) {
1220            mHistoryTag = tag;
1221        }
1222
1223        /** @hide */
1224        public void setUnimportantForLogging(boolean state) {
1225            if (state) mFlags |= UNIMPORTANT_FOR_LOGGING;
1226            else mFlags &= ~UNIMPORTANT_FOR_LOGGING;
1227        }
1228
1229        @Override
1230        public String toString() {
1231            synchronized (mToken) {
1232                return "WakeLock{"
1233                    + Integer.toHexString(System.identityHashCode(this))
1234                    + " held=" + mHeld + ", refCount=" + mCount + "}";
1235            }
1236        }
1237    }
1238}
1239