PowerManager.java revision 970d4132ea28e748c1010be39450a98bbf7466f3
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.content.Context; 21import android.util.Log; 22 23/** 24 * This class gives you control of the power state of the device. 25 * 26 * <p> 27 * <b>Device battery life will be significantly affected by the use of this API.</b> 28 * Do not acquire {@link WakeLock}s unless you really need them, use the minimum levels 29 * possible, and be sure to release them as soon as possible. 30 * </p><p> 31 * You can obtain an instance of this class by calling 32 * {@link android.content.Context#getSystemService(java.lang.String) Context.getSystemService()}. 33 * </p><p> 34 * The primary API you'll use is {@link #newWakeLock(int, String) newWakeLock()}. 35 * This will create a {@link PowerManager.WakeLock} object. You can then use methods 36 * on the wake lock object to control the power state of the device. 37 * </p><p> 38 * In practice it's quite simple: 39 * {@samplecode 40 * PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE); 41 * PowerManager.WakeLock wl = pm.newWakeLock(PowerManager.SCREEN_DIM_WAKE_LOCK, "My Tag"); 42 * wl.acquire(); 43 * ..screen will stay on during this section.. 44 * wl.release(); 45 * } 46 * </p><p> 47 * The following wake lock levels are defined, with varying effects on system power. 48 * <i>These levels are mutually exclusive - you may only specify one of them.</i> 49 * 50 * <table> 51 * <tr><th>Flag Value</th> 52 * <th>CPU</th> <th>Screen</th> <th>Keyboard</th></tr> 53 * 54 * <tr><td>{@link #PARTIAL_WAKE_LOCK}</td> 55 * <td>On*</td> <td>Off</td> <td>Off</td> 56 * </tr> 57 * 58 * <tr><td>{@link #SCREEN_DIM_WAKE_LOCK}</td> 59 * <td>On</td> <td>Dim</td> <td>Off</td> 60 * </tr> 61 * 62 * <tr><td>{@link #SCREEN_BRIGHT_WAKE_LOCK}</td> 63 * <td>On</td> <td>Bright</td> <td>Off</td> 64 * </tr> 65 * 66 * <tr><td>{@link #FULL_WAKE_LOCK}</td> 67 * <td>On</td> <td>Bright</td> <td>Bright</td> 68 * </tr> 69 * </table> 70 * </p><p> 71 * *<i>If you hold a partial wake lock, the CPU will continue to run, regardless of any 72 * display timeouts or the state of the screen and even after the user presses the power button. 73 * In all other wake locks, the CPU will run, but the user can still put the device to sleep 74 * using the power button.</i> 75 * </p><p> 76 * In addition, you can add two more flags, which affect behavior of the screen only. 77 * <i>These flags have no effect when combined with a {@link #PARTIAL_WAKE_LOCK}.</i></p> 78 * 79 * <table> 80 * <tr><th>Flag Value</th> <th>Description</th></tr> 81 * 82 * <tr><td>{@link #ACQUIRE_CAUSES_WAKEUP}</td> 83 * <td>Normal wake locks don't actually turn on the illumination. Instead, they cause 84 * the illumination to remain on once it turns on (e.g. from user activity). This flag 85 * will force the screen and/or keyboard to turn on immediately, when the WakeLock is 86 * acquired. A typical use would be for notifications which are important for the user to 87 * see immediately.</td> 88 * </tr> 89 * 90 * <tr><td>{@link #ON_AFTER_RELEASE}</td> 91 * <td>If this flag is set, the user activity timer will be reset when the WakeLock is 92 * released, causing the illumination to remain on a bit longer. This can be used to 93 * reduce flicker if you are cycling between wake lock conditions.</td> 94 * </tr> 95 * </table> 96 * <p> 97 * Any application using a WakeLock must request the {@code android.permission.WAKE_LOCK} 98 * permission in an {@code <uses-permission>} element of the application's manifest. 99 * </p> 100 */ 101public final class PowerManager { 102 private static final String TAG = "PowerManager"; 103 104 /* NOTE: Wake lock levels were previously defined as a bit field, except that only a few 105 * combinations were actually supported so the bit field was removed. This explains 106 * why the numbering scheme is so odd. If adding a new wake lock level, any unused 107 * value can be used. 108 */ 109 110 /** 111 * Wake lock level: Ensures that the CPU is running; the screen and keyboard 112 * backlight will be allowed to go off. 113 * <p> 114 * If the user presses the power button, then the screen will be turned off 115 * but the CPU will be kept on until all partial wake locks have been released. 116 * </p> 117 */ 118 public static final int PARTIAL_WAKE_LOCK = 0x00000001; 119 120 /** 121 * Wake lock level: Ensures that the screen is on (but may be dimmed); 122 * the keyboard backlight will be allowed to go off. 123 * <p> 124 * If the user presses the power button, then the {@link #SCREEN_DIM_WAKE_LOCK} will be 125 * implicitly released by the system, causing both the screen and the CPU to be turned off. 126 * Contrast with {@link #PARTIAL_WAKE_LOCK}. 127 * </p> 128 * 129 * @deprecated Most applications should use 130 * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead 131 * of this type of wake lock, as it will be correctly managed by the platform 132 * as the user moves between applications and doesn't require a special permission. 133 */ 134 @Deprecated 135 public static final int SCREEN_DIM_WAKE_LOCK = 0x00000006; 136 137 /** 138 * Wake lock level: Ensures that the screen is on at full brightness; 139 * the keyboard backlight will be allowed to go off. 140 * <p> 141 * If the user presses the power button, then the {@link #SCREEN_BRIGHT_WAKE_LOCK} will be 142 * implicitly released by the system, causing both the screen and the CPU to be turned off. 143 * Contrast with {@link #PARTIAL_WAKE_LOCK}. 144 * </p> 145 * 146 * @deprecated Most applications should use 147 * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead 148 * of this type of wake lock, as it will be correctly managed by the platform 149 * as the user moves between applications and doesn't require a special permission. 150 */ 151 @Deprecated 152 public static final int SCREEN_BRIGHT_WAKE_LOCK = 0x0000000a; 153 154 /** 155 * Wake lock level: Ensures that the screen and keyboard backlight are on at 156 * full brightness. 157 * <p> 158 * If the user presses the power button, then the {@link #FULL_WAKE_LOCK} will be 159 * implicitly released by the system, causing both the screen and the CPU to be turned off. 160 * Contrast with {@link #PARTIAL_WAKE_LOCK}. 161 * </p> 162 * 163 * @deprecated Most applications should use 164 * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead 165 * of this type of wake lock, as it will be correctly managed by the platform 166 * as the user moves between applications and doesn't require a special permission. 167 */ 168 @Deprecated 169 public static final int FULL_WAKE_LOCK = 0x0000001a; 170 171 /** 172 * Wake lock level: Turns the screen off when the proximity sensor activates. 173 * <p> 174 * If the proximity sensor detects that an object is nearby, the screen turns off 175 * immediately. Shortly after the object moves away, the screen turns on again. 176 * </p><p> 177 * A proximity wake lock does not prevent the device from falling asleep 178 * unlike {@link #FULL_WAKE_LOCK}, {@link #SCREEN_BRIGHT_WAKE_LOCK} and 179 * {@link #SCREEN_DIM_WAKE_LOCK}. If there is no user activity and no other 180 * wake locks are held, then the device will fall asleep (and lock) as usual. 181 * However, the device will not fall asleep while the screen has been turned off 182 * by the proximity sensor because it effectively counts as ongoing user activity. 183 * </p><p> 184 * Since not all devices have proximity sensors, use {@link #isWakeLockLevelSupported} 185 * to determine whether this wake lock level is supported. 186 * </p><p> 187 * Cannot be used with {@link #ACQUIRE_CAUSES_WAKEUP}. 188 * </p> 189 * 190 * {@hide} 191 */ 192 public static final int PROXIMITY_SCREEN_OFF_WAKE_LOCK = 0x00000020; 193 194 /** 195 * Wake lock level: Put the screen in a low power state and allow the CPU to suspend 196 * if no other wake locks are held. 197 * <p> 198 * This is used by the dream manager to implement doze mode. It currently 199 * has no effect unless the power manager is in the dozing state. 200 * </p> 201 * 202 * {@hide} 203 */ 204 public static final int DOZE_WAKE_LOCK = 0x00000040; 205 206 /** 207 * Mask for the wake lock level component of a combined wake lock level and flags integer. 208 * 209 * @hide 210 */ 211 public static final int WAKE_LOCK_LEVEL_MASK = 0x0000ffff; 212 213 /** 214 * Wake lock flag: Turn the screen on when the wake lock is acquired. 215 * <p> 216 * Normally wake locks don't actually wake the device, they just cause 217 * the screen to remain on once it's already on. Think of the video player 218 * application as the normal behavior. Notifications that pop up and want 219 * the device to be on are the exception; use this flag to be like them. 220 * </p><p> 221 * Cannot be used with {@link #PARTIAL_WAKE_LOCK}. 222 * </p> 223 */ 224 public static final int ACQUIRE_CAUSES_WAKEUP = 0x10000000; 225 226 /** 227 * Wake lock flag: When this wake lock is released, poke the user activity timer 228 * so the screen stays on for a little longer. 229 * <p> 230 * Will not turn the screen on if it is not already on. 231 * See {@link #ACQUIRE_CAUSES_WAKEUP} if you want that. 232 * </p><p> 233 * Cannot be used with {@link #PARTIAL_WAKE_LOCK}. 234 * </p> 235 */ 236 public static final int ON_AFTER_RELEASE = 0x20000000; 237 238 /** 239 * Wake lock flag: This wake lock is not important for logging events. If a later 240 * wake lock is acquired that is important, it will be considered the one to log. 241 * @hide 242 */ 243 public static final int UNIMPORTANT_FOR_LOGGING = 0x40000000; 244 245 /** 246 * Flag for {@link WakeLock#release release(int)} to defer releasing a 247 * {@link #PROXIMITY_SCREEN_OFF_WAKE_LOCK} wake lock until the proximity sensor returns 248 * a negative value. 249 * 250 * {@hide} 251 */ 252 public static final int WAIT_FOR_PROXIMITY_NEGATIVE = 1; 253 254 /** 255 * Brightness value for fully on. 256 * @hide 257 */ 258 public static final int BRIGHTNESS_ON = 255; 259 260 /** 261 * Brightness value for fully off. 262 * @hide 263 */ 264 public static final int BRIGHTNESS_OFF = 0; 265 266 /** 267 * Brightness value for default policy handling by the system. 268 * @hide 269 */ 270 public static final int BRIGHTNESS_DEFAULT = -1; 271 272 // Note: Be sure to update android.os.BatteryStats and PowerManager.h 273 // if adding or modifying user activity event constants. 274 275 /** 276 * User activity event type: Unspecified event type. 277 * @hide 278 */ 279 public static final int USER_ACTIVITY_EVENT_OTHER = 0; 280 281 /** 282 * User activity event type: Button or key pressed or released. 283 * @hide 284 */ 285 public static final int USER_ACTIVITY_EVENT_BUTTON = 1; 286 287 /** 288 * User activity event type: Touch down, move or up. 289 * @hide 290 */ 291 public static final int USER_ACTIVITY_EVENT_TOUCH = 2; 292 293 /** 294 * User activity flag: Do not restart the user activity timeout or brighten 295 * the display in response to user activity if it is already dimmed. 296 * @hide 297 */ 298 public static final int USER_ACTIVITY_FLAG_NO_CHANGE_LIGHTS = 1 << 0; 299 300 /** 301 * Go to sleep reason code: Going to sleep due by user request. 302 * @hide 303 */ 304 public static final int GO_TO_SLEEP_REASON_USER = 0; 305 306 /** 307 * Go to sleep reason code: Going to sleep due by request of the 308 * device administration policy. 309 * @hide 310 */ 311 public static final int GO_TO_SLEEP_REASON_DEVICE_ADMIN = 1; 312 313 /** 314 * Go to sleep reason code: Going to sleep due to a screen timeout. 315 * @hide 316 */ 317 public static final int GO_TO_SLEEP_REASON_TIMEOUT = 2; 318 319 /** 320 * The value to pass as the 'reason' argument to reboot() to 321 * reboot into recovery mode (for applying system updates, doing 322 * factory resets, etc.). 323 * <p> 324 * Requires the {@link android.Manifest.permission#RECOVERY} 325 * permission (in addition to 326 * {@link android.Manifest.permission#REBOOT}). 327 * </p> 328 */ 329 public static final String REBOOT_RECOVERY = "recovery"; 330 331 /** 332 * Go to sleep flag: Skip dozing state and directly go to full sleep. 333 * @hide 334 */ 335 public static final int GO_TO_SLEEP_FLAG_NO_DOZE = 1 << 0; 336 337 final Context mContext; 338 final IPowerManager mService; 339 final Handler mHandler; 340 341 /** 342 * {@hide} 343 */ 344 public PowerManager(Context context, IPowerManager service, Handler handler) { 345 mContext = context; 346 mService = service; 347 mHandler = handler; 348 } 349 350 /** 351 * Gets the minimum supported screen brightness setting. 352 * The screen may be allowed to become dimmer than this value but 353 * this is the minimum value that can be set by the user. 354 * @hide 355 */ 356 public int getMinimumScreenBrightnessSetting() { 357 return mContext.getResources().getInteger( 358 com.android.internal.R.integer.config_screenBrightnessSettingMinimum); 359 } 360 361 /** 362 * Gets the maximum supported screen brightness setting. 363 * The screen may be allowed to become dimmer than this value but 364 * this is the maximum value that can be set by the user. 365 * @hide 366 */ 367 public int getMaximumScreenBrightnessSetting() { 368 return mContext.getResources().getInteger( 369 com.android.internal.R.integer.config_screenBrightnessSettingMaximum); 370 } 371 372 /** 373 * Gets the default screen brightness setting. 374 * @hide 375 */ 376 public int getDefaultScreenBrightnessSetting() { 377 return mContext.getResources().getInteger( 378 com.android.internal.R.integer.config_screenBrightnessSettingDefault); 379 } 380 381 /** 382 * Returns true if the twilight service should be used to adjust screen brightness 383 * policy. This setting is experimental and disabled by default. 384 * @hide 385 */ 386 public static boolean useTwilightAdjustmentFeature() { 387 return SystemProperties.getBoolean("persist.power.usetwilightadj", false); 388 } 389 390 /** 391 * Creates a new wake lock with the specified level and flags. 392 * <p> 393 * The {@code levelAndFlags} parameter specifies a wake lock level and optional flags 394 * combined using the logical OR operator. 395 * </p><p> 396 * The wake lock levels are: {@link #PARTIAL_WAKE_LOCK}, 397 * {@link #FULL_WAKE_LOCK}, {@link #SCREEN_DIM_WAKE_LOCK} 398 * and {@link #SCREEN_BRIGHT_WAKE_LOCK}. Exactly one wake lock level must be 399 * specified as part of the {@code levelAndFlags} parameter. 400 * </p><p> 401 * The wake lock flags are: {@link #ACQUIRE_CAUSES_WAKEUP} 402 * and {@link #ON_AFTER_RELEASE}. Multiple flags can be combined as part of the 403 * {@code levelAndFlags} parameters. 404 * </p><p> 405 * Call {@link WakeLock#acquire() acquire()} on the object to acquire the 406 * wake lock, and {@link WakeLock#release release()} when you are done. 407 * </p><p> 408 * {@samplecode 409 * PowerManager pm = (PowerManager)mContext.getSystemService( 410 * Context.POWER_SERVICE); 411 * PowerManager.WakeLock wl = pm.newWakeLock( 412 * PowerManager.SCREEN_DIM_WAKE_LOCK 413 * | PowerManager.ON_AFTER_RELEASE, 414 * TAG); 415 * wl.acquire(); 416 * // ... do work... 417 * wl.release(); 418 * } 419 * </p><p> 420 * Although a wake lock can be created without special permissions, 421 * the {@link android.Manifest.permission#WAKE_LOCK} permission is 422 * required to actually acquire or release the wake lock that is returned. 423 * </p><p class="note"> 424 * If using this to keep the screen on, you should strongly consider using 425 * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead. 426 * This window flag will be correctly managed by the platform 427 * as the user moves between applications and doesn't require a special permission. 428 * </p> 429 * 430 * @param levelAndFlags Combination of wake lock level and flag values defining 431 * the requested behavior of the WakeLock. 432 * @param tag Your class name (or other tag) for debugging purposes. 433 * 434 * @see WakeLock#acquire() 435 * @see WakeLock#release() 436 * @see #PARTIAL_WAKE_LOCK 437 * @see #FULL_WAKE_LOCK 438 * @see #SCREEN_DIM_WAKE_LOCK 439 * @see #SCREEN_BRIGHT_WAKE_LOCK 440 * @see #ACQUIRE_CAUSES_WAKEUP 441 * @see #ON_AFTER_RELEASE 442 */ 443 public WakeLock newWakeLock(int levelAndFlags, String tag) { 444 validateWakeLockParameters(levelAndFlags, tag); 445 return new WakeLock(levelAndFlags, tag, mContext.getOpPackageName()); 446 } 447 448 /** @hide */ 449 public static void validateWakeLockParameters(int levelAndFlags, String tag) { 450 switch (levelAndFlags & WAKE_LOCK_LEVEL_MASK) { 451 case PARTIAL_WAKE_LOCK: 452 case SCREEN_DIM_WAKE_LOCK: 453 case SCREEN_BRIGHT_WAKE_LOCK: 454 case FULL_WAKE_LOCK: 455 case PROXIMITY_SCREEN_OFF_WAKE_LOCK: 456 case DOZE_WAKE_LOCK: 457 break; 458 default: 459 throw new IllegalArgumentException("Must specify a valid wake lock level."); 460 } 461 if (tag == null) { 462 throw new IllegalArgumentException("The tag must not be null."); 463 } 464 } 465 466 /** 467 * Notifies the power manager that user activity happened. 468 * <p> 469 * Resets the auto-off timer and brightens the screen if the device 470 * is not asleep. This is what happens normally when a key or the touch 471 * screen is pressed or when some other user activity occurs. 472 * This method does not wake up the device if it has been put to sleep. 473 * </p><p> 474 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 475 * </p> 476 * 477 * @param when The time of the user activity, in the {@link SystemClock#uptimeMillis()} 478 * time base. This timestamp is used to correctly order the user activity request with 479 * other power management functions. It should be set 480 * to the timestamp of the input event that caused the user activity. 481 * @param noChangeLights If true, does not cause the keyboard backlight to turn on 482 * because of this event. This is set when the power key is pressed. 483 * We want the device to stay on while the button is down, but we're about 484 * to turn off the screen so we don't want the keyboard backlight to turn on again. 485 * Otherwise the lights flash on and then off and it looks weird. 486 * 487 * @see #wakeUp 488 * @see #goToSleep 489 */ 490 public void userActivity(long when, boolean noChangeLights) { 491 try { 492 mService.userActivity(when, USER_ACTIVITY_EVENT_OTHER, 493 noChangeLights ? USER_ACTIVITY_FLAG_NO_CHANGE_LIGHTS : 0); 494 } catch (RemoteException e) { 495 } 496 } 497 498 /** 499 * Forces the device to go to sleep. 500 * <p> 501 * Overrides all the wake locks that are held. 502 * This is what happens when the power key is pressed to turn off the screen. 503 * </p><p> 504 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 505 * </p> 506 * 507 * @param time The time when the request to go to sleep was issued, in the 508 * {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly 509 * order the go to sleep request with other power management functions. It should be set 510 * to the timestamp of the input event that caused the request to go to sleep. 511 * 512 * @see #userActivity 513 * @see #wakeUp 514 */ 515 public void goToSleep(long time) { 516 goToSleep(time, GO_TO_SLEEP_REASON_USER, 0); 517 } 518 519 /** 520 * @hide 521 */ 522 public void goToSleep(long time, int reason, int flags) { 523 try { 524 mService.goToSleep(time, reason, flags); 525 } catch (RemoteException e) { 526 } 527 } 528 529 /** 530 * Forces the device to wake up from sleep. 531 * <p> 532 * If the device is currently asleep, wakes it up, otherwise does nothing. 533 * This is what happens when the power key is pressed to turn on the screen. 534 * </p><p> 535 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 536 * </p> 537 * 538 * @param time The time when the request to wake up was issued, in the 539 * {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly 540 * order the wake up request with other power management functions. It should be set 541 * to the timestamp of the input event that caused the request to wake up. 542 * 543 * @see #userActivity 544 * @see #goToSleep 545 */ 546 public void wakeUp(long time) { 547 try { 548 mService.wakeUp(time); 549 } catch (RemoteException e) { 550 } 551 } 552 553 /** 554 * Forces the device to start napping. 555 * <p> 556 * If the device is currently awake, starts dreaming, otherwise does nothing. 557 * When the dream ends or if the dream cannot be started, the device will 558 * either wake up or go to sleep depending on whether there has been recent 559 * user activity. 560 * </p><p> 561 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 562 * </p> 563 * 564 * @param time The time when the request to nap was issued, in the 565 * {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly 566 * order the nap request with other power management functions. It should be set 567 * to the timestamp of the input event that caused the request to nap. 568 * 569 * @see #wakeUp 570 * @see #goToSleep 571 * 572 * @hide 573 */ 574 public void nap(long time) { 575 try { 576 mService.nap(time); 577 } catch (RemoteException e) { 578 } 579 } 580 581 /** 582 * Sets the brightness of the backlights (screen, keyboard, button). 583 * <p> 584 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 585 * </p> 586 * 587 * @param brightness The brightness value from 0 to 255. 588 * 589 * {@hide} 590 */ 591 public void setBacklightBrightness(int brightness) { 592 try { 593 mService.setTemporaryScreenBrightnessSettingOverride(brightness); 594 } catch (RemoteException e) { 595 } 596 } 597 598 /** 599 * Returns true if the specified wake lock level is supported. 600 * 601 * @param level The wake lock level to check. 602 * @return True if the specified wake lock level is supported. 603 * 604 * {@hide} 605 */ 606 public boolean isWakeLockLevelSupported(int level) { 607 try { 608 return mService.isWakeLockLevelSupported(level); 609 } catch (RemoteException e) { 610 return false; 611 } 612 } 613 614 /** 615 * Returns true if the device is in an interactive state. 616 * <p> 617 * For historical reasons, the name of this method refers to the power state of 618 * the screen but it actually describes the overall interactive state of 619 * the device. This method has been replaced by {@link #isInteractive}. 620 * </p><p> 621 * The value returned by this method only indicates whether the device is 622 * in an interactive state which may have nothing to do with the screen being 623 * on or off. To determine the actual state of the screen, 624 * use {@link android.view.Display#getState}. 625 * </p> 626 * 627 * @return True if the device is in an interactive state. 628 * 629 * @deprecated Use {@link #isInteractive} instead. 630 */ 631 @Deprecated 632 public boolean isScreenOn() { 633 return isInteractive(); 634 } 635 636 /** 637 * Returns true if the device is in an interactive state. 638 * <p> 639 * When this method returns true, the device is awake and ready to interact 640 * with the user (although this is not a guarantee that the user is actively 641 * interacting with the device just this moment). The main screen is usually 642 * turned on while in this state. Certain features, such as the proximity 643 * sensor, may temporarily turn off the screen while still leaving the device in an 644 * interactive state. Note in particular that the device is still considered 645 * to be interactive while dreaming (since dreams can be interactive) but not 646 * when it is dozing or asleep. 647 * </p><p> 648 * When this method returns false, the device is dozing or asleep and must 649 * be awoken before it will become ready to interact with the user again. The 650 * main screen is usually turned off while in this state. Certain features, 651 * such as "ambient mode" may cause the main screen to remain on (albeit in a 652 * low power state) to display system-provided content while the device dozes. 653 * </p><p> 654 * The system will send a {@link android.content.Intent#ACTION_SCREEN_ON screen on} 655 * or {@link android.content.Intent#ACTION_SCREEN_OFF screen off} broadcast 656 * whenever the interactive state of the device changes. For historical reasons, 657 * the names of these broadcasts refer to the power state of the screen 658 * but they are actually sent in response to changes in the overall interactive 659 * state of the device, as described by this method. 660 * </p><p> 661 * Services may use the non-interactive state as a hint to conserve power 662 * since the user is not present. 663 * </p> 664 * 665 * @return True if the device is in an interactive state. 666 * 667 * @see android.content.Intent#ACTION_SCREEN_ON 668 * @see android.content.Intent#ACTION_SCREEN_OFF 669 */ 670 public boolean isInteractive() { 671 try { 672 return mService.isInteractive(); 673 } catch (RemoteException e) { 674 return false; 675 } 676 } 677 678 /** 679 * Reboot the device. Will not return if the reboot is successful. 680 * <p> 681 * Requires the {@link android.Manifest.permission#REBOOT} permission. 682 * </p> 683 * 684 * @param reason code to pass to the kernel (e.g., "recovery") to 685 * request special boot modes, or null. 686 */ 687 public void reboot(String reason) { 688 try { 689 mService.reboot(false, reason, true); 690 } catch (RemoteException e) { 691 } 692 } 693 694 /** 695 * Returns true if the device is currently in power save mode. When in this mode, 696 * applications should reduce their functionality in order to conserve battery as 697 * much as possible. You can monitor for changes to this state with 698 * {@link #ACTION_POWER_SAVE_MODE_CHANGED}. 699 * 700 * @return Returns true if currently in low power mode, else false. 701 */ 702 public boolean isPowerSaveMode() { 703 try { 704 return mService.isPowerSaveMode(); 705 } catch (RemoteException e) { 706 return false; 707 } 708 } 709 710 /** 711 * Intent that is broadcast when the state of {@link #isPowerSaveMode()} changes. 712 * This broadcast is only sent to registered receivers. 713 */ 714 @SdkConstant(SdkConstant.SdkConstantType.BROADCAST_INTENT_ACTION) 715 public static final String ACTION_POWER_SAVE_MODE_CHANGED 716 = "android.os.action.POWER_SAVE_MODE_CHANGED"; 717 718 /** 719 * A wake lock is a mechanism to indicate that your application needs 720 * to have the device stay on. 721 * <p> 722 * Any application using a WakeLock must request the {@code android.permission.WAKE_LOCK} 723 * permission in an {@code <uses-permission>} element of the application's manifest. 724 * Obtain a wake lock by calling {@link PowerManager#newWakeLock(int, String)}. 725 * </p><p> 726 * Call {@link #acquire()} to acquire the wake lock and force the device to stay 727 * on at the level that was requested when the wake lock was created. 728 * </p><p> 729 * Call {@link #release()} when you are done and don't need the lock anymore. 730 * It is very important to do this as soon as possible to avoid running down the 731 * device's battery excessively. 732 * </p> 733 */ 734 public final class WakeLock { 735 private int mFlags; 736 private String mTag; 737 private final String mPackageName; 738 private final IBinder mToken; 739 private int mCount; 740 private boolean mRefCounted = true; 741 private boolean mHeld; 742 private WorkSource mWorkSource; 743 private String mHistoryTag; 744 745 private final Runnable mReleaser = new Runnable() { 746 public void run() { 747 release(); 748 } 749 }; 750 751 WakeLock(int flags, String tag, String packageName) { 752 mFlags = flags; 753 mTag = tag; 754 mPackageName = packageName; 755 mToken = new Binder(); 756 } 757 758 @Override 759 protected void finalize() throws Throwable { 760 synchronized (mToken) { 761 if (mHeld) { 762 Log.wtf(TAG, "WakeLock finalized while still held: " + mTag); 763 try { 764 mService.releaseWakeLock(mToken, 0); 765 } catch (RemoteException e) { 766 } 767 } 768 } 769 } 770 771 /** 772 * Sets whether this WakeLock is reference counted. 773 * <p> 774 * Wake locks are reference counted by default. If a wake lock is 775 * reference counted, then each call to {@link #acquire()} must be 776 * balanced by an equal number of calls to {@link #release()}. If a wake 777 * lock is not reference counted, then one call to {@link #release()} is 778 * sufficient to undo the effect of all previous calls to {@link #acquire()}. 779 * </p> 780 * 781 * @param value True to make the wake lock reference counted, false to 782 * make the wake lock non-reference counted. 783 */ 784 public void setReferenceCounted(boolean value) { 785 synchronized (mToken) { 786 mRefCounted = value; 787 } 788 } 789 790 /** 791 * Acquires the wake lock. 792 * <p> 793 * Ensures that the device is on at the level requested when 794 * the wake lock was created. 795 * </p> 796 */ 797 public void acquire() { 798 synchronized (mToken) { 799 acquireLocked(); 800 } 801 } 802 803 /** 804 * Acquires the wake lock with a timeout. 805 * <p> 806 * Ensures that the device is on at the level requested when 807 * the wake lock was created. The lock will be released after the given timeout 808 * expires. 809 * </p> 810 * 811 * @param timeout The timeout after which to release the wake lock, in milliseconds. 812 */ 813 public void acquire(long timeout) { 814 synchronized (mToken) { 815 acquireLocked(); 816 mHandler.postDelayed(mReleaser, timeout); 817 } 818 } 819 820 private void acquireLocked() { 821 if (!mRefCounted || mCount++ == 0) { 822 // Do this even if the wake lock is already thought to be held (mHeld == true) 823 // because non-reference counted wake locks are not always properly released. 824 // For example, the keyguard's wake lock might be forcibly released by the 825 // power manager without the keyguard knowing. A subsequent call to acquire 826 // should immediately acquire the wake lock once again despite never having 827 // been explicitly released by the keyguard. 828 mHandler.removeCallbacks(mReleaser); 829 try { 830 mService.acquireWakeLock(mToken, mFlags, mTag, mPackageName, mWorkSource, 831 mHistoryTag); 832 } catch (RemoteException e) { 833 } 834 mHeld = true; 835 } 836 } 837 838 /** 839 * Releases the wake lock. 840 * <p> 841 * This method releases your claim to the CPU or screen being on. 842 * The screen may turn off shortly after you release the wake lock, or it may 843 * not if there are other wake locks still held. 844 * </p> 845 */ 846 public void release() { 847 release(0); 848 } 849 850 /** 851 * Releases the wake lock with flags to modify the release behavior. 852 * <p> 853 * This method releases your claim to the CPU or screen being on. 854 * The screen may turn off shortly after you release the wake lock, or it may 855 * not if there are other wake locks still held. 856 * </p> 857 * 858 * @param flags Combination of flag values to modify the release behavior. 859 * Currently only {@link #WAIT_FOR_PROXIMITY_NEGATIVE} is supported. 860 * 861 * {@hide} 862 */ 863 public void release(int flags) { 864 synchronized (mToken) { 865 if (!mRefCounted || --mCount == 0) { 866 mHandler.removeCallbacks(mReleaser); 867 if (mHeld) { 868 try { 869 mService.releaseWakeLock(mToken, flags); 870 } catch (RemoteException e) { 871 } 872 mHeld = false; 873 } 874 } 875 if (mCount < 0) { 876 throw new RuntimeException("WakeLock under-locked " + mTag); 877 } 878 } 879 } 880 881 /** 882 * Returns true if the wake lock has been acquired but not yet released. 883 * 884 * @return True if the wake lock is held. 885 */ 886 public boolean isHeld() { 887 synchronized (mToken) { 888 return mHeld; 889 } 890 } 891 892 /** 893 * Sets the work source associated with the wake lock. 894 * <p> 895 * The work source is used to determine on behalf of which application 896 * the wake lock is being held. This is useful in the case where a 897 * service is performing work on behalf of an application so that the 898 * cost of that work can be accounted to the application. 899 * </p> 900 * 901 * @param ws The work source, or null if none. 902 */ 903 public void setWorkSource(WorkSource ws) { 904 synchronized (mToken) { 905 if (ws != null && ws.size() == 0) { 906 ws = null; 907 } 908 909 final boolean changed; 910 if (ws == null) { 911 changed = mWorkSource != null; 912 mWorkSource = null; 913 } else if (mWorkSource == null) { 914 changed = true; 915 mWorkSource = new WorkSource(ws); 916 } else { 917 changed = mWorkSource.diff(ws); 918 if (changed) { 919 mWorkSource.set(ws); 920 } 921 } 922 923 if (changed && mHeld) { 924 try { 925 mService.updateWakeLockWorkSource(mToken, mWorkSource, mHistoryTag); 926 } catch (RemoteException e) { 927 } 928 } 929 } 930 } 931 932 /** @hide */ 933 public void setTag(String tag) { 934 mTag = tag; 935 } 936 937 /** @hide */ 938 public void setHistoryTag(String tag) { 939 mHistoryTag = tag; 940 } 941 942 /** @hide */ 943 public void setUnimportantForLogging(boolean state) { 944 if (state) mFlags |= UNIMPORTANT_FOR_LOGGING; 945 else mFlags &= ~UNIMPORTANT_FOR_LOGGING; 946 } 947 948 @Override 949 public String toString() { 950 synchronized (mToken) { 951 return "WakeLock{" 952 + Integer.toHexString(System.identityHashCode(this)) 953 + " held=" + mHeld + ", refCount=" + mCount + "}"; 954 } 955 } 956 } 957} 958