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