PowerManager.java revision eb94fa7975b1e8742f3b00cec6bd4f9d6b329e3a
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 // Note: Be sure to update android.os.BatteryStats and PowerManager.h 267 // if adding or modifying user activity event constants. 268 269 /** 270 * User activity event type: Unspecified event type. 271 * @hide 272 */ 273 public static final int USER_ACTIVITY_EVENT_OTHER = 0; 274 275 /** 276 * User activity event type: Button or key pressed or released. 277 * @hide 278 */ 279 public static final int USER_ACTIVITY_EVENT_BUTTON = 1; 280 281 /** 282 * User activity event type: Touch down, move or up. 283 * @hide 284 */ 285 public static final int USER_ACTIVITY_EVENT_TOUCH = 2; 286 287 /** 288 * User activity flag: Do not restart the user activity timeout or brighten 289 * the display in response to user activity if it is already dimmed. 290 * @hide 291 */ 292 public static final int USER_ACTIVITY_FLAG_NO_CHANGE_LIGHTS = 1 << 0; 293 294 /** 295 * Go to sleep reason code: Going to sleep due by user request. 296 * @hide 297 */ 298 public static final int GO_TO_SLEEP_REASON_USER = 0; 299 300 /** 301 * Go to sleep reason code: Going to sleep due by request of the 302 * device administration policy. 303 * @hide 304 */ 305 public static final int GO_TO_SLEEP_REASON_DEVICE_ADMIN = 1; 306 307 /** 308 * Go to sleep reason code: Going to sleep due to a screen timeout. 309 * @hide 310 */ 311 public static final int GO_TO_SLEEP_REASON_TIMEOUT = 2; 312 313 /** 314 * The value to pass as the 'reason' argument to reboot() to 315 * reboot into recovery mode (for applying system updates, doing 316 * factory resets, etc.). 317 * <p> 318 * Requires the {@link android.Manifest.permission#RECOVERY} 319 * permission (in addition to 320 * {@link android.Manifest.permission#REBOOT}). 321 * </p> 322 */ 323 public static final String REBOOT_RECOVERY = "recovery"; 324 325 /** 326 * Go to sleep flag: Skip dozing state and directly go to full sleep. 327 * @hide 328 */ 329 public static final int GO_TO_SLEEP_FLAG_NO_DOZE = 1 << 0; 330 331 final Context mContext; 332 final IPowerManager mService; 333 final Handler mHandler; 334 335 /** 336 * {@hide} 337 */ 338 public PowerManager(Context context, IPowerManager service, Handler handler) { 339 mContext = context; 340 mService = service; 341 mHandler = handler; 342 } 343 344 /** 345 * Gets the minimum supported screen brightness setting. 346 * The screen may be allowed to become dimmer than this value but 347 * this is the minimum value that can be set by the user. 348 * @hide 349 */ 350 public int getMinimumScreenBrightnessSetting() { 351 return mContext.getResources().getInteger( 352 com.android.internal.R.integer.config_screenBrightnessSettingMinimum); 353 } 354 355 /** 356 * Gets the maximum supported screen brightness setting. 357 * The screen may be allowed to become dimmer than this value but 358 * this is the maximum value that can be set by the user. 359 * @hide 360 */ 361 public int getMaximumScreenBrightnessSetting() { 362 return mContext.getResources().getInteger( 363 com.android.internal.R.integer.config_screenBrightnessSettingMaximum); 364 } 365 366 /** 367 * Gets the default screen brightness setting. 368 * @hide 369 */ 370 public int getDefaultScreenBrightnessSetting() { 371 return mContext.getResources().getInteger( 372 com.android.internal.R.integer.config_screenBrightnessSettingDefault); 373 } 374 375 /** 376 * Returns true if the twilight service should be used to adjust screen brightness 377 * policy. This setting is experimental and disabled by default. 378 * @hide 379 */ 380 public static boolean useTwilightAdjustmentFeature() { 381 return SystemProperties.getBoolean("persist.power.usetwilightadj", false); 382 } 383 384 /** 385 * Creates a new wake lock with the specified level and flags. 386 * <p> 387 * The {@code levelAndFlags} parameter specifies a wake lock level and optional flags 388 * combined using the logical OR operator. 389 * </p><p> 390 * The wake lock levels are: {@link #PARTIAL_WAKE_LOCK}, 391 * {@link #FULL_WAKE_LOCK}, {@link #SCREEN_DIM_WAKE_LOCK} 392 * and {@link #SCREEN_BRIGHT_WAKE_LOCK}. Exactly one wake lock level must be 393 * specified as part of the {@code levelAndFlags} parameter. 394 * </p><p> 395 * The wake lock flags are: {@link #ACQUIRE_CAUSES_WAKEUP} 396 * and {@link #ON_AFTER_RELEASE}. Multiple flags can be combined as part of the 397 * {@code levelAndFlags} parameters. 398 * </p><p> 399 * Call {@link WakeLock#acquire() acquire()} on the object to acquire the 400 * wake lock, and {@link WakeLock#release release()} when you are done. 401 * </p><p> 402 * {@samplecode 403 * PowerManager pm = (PowerManager)mContext.getSystemService( 404 * Context.POWER_SERVICE); 405 * PowerManager.WakeLock wl = pm.newWakeLock( 406 * PowerManager.SCREEN_DIM_WAKE_LOCK 407 * | PowerManager.ON_AFTER_RELEASE, 408 * TAG); 409 * wl.acquire(); 410 * // ... do work... 411 * wl.release(); 412 * } 413 * </p><p> 414 * Although a wake lock can be created without special permissions, 415 * the {@link android.Manifest.permission#WAKE_LOCK} permission is 416 * required to actually acquire or release the wake lock that is returned. 417 * </p><p class="note"> 418 * If using this to keep the screen on, you should strongly consider using 419 * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead. 420 * This window flag will be correctly managed by the platform 421 * as the user moves between applications and doesn't require a special permission. 422 * </p> 423 * 424 * @param levelAndFlags Combination of wake lock level and flag values defining 425 * the requested behavior of the WakeLock. 426 * @param tag Your class name (or other tag) for debugging purposes. 427 * 428 * @see WakeLock#acquire() 429 * @see WakeLock#release() 430 * @see #PARTIAL_WAKE_LOCK 431 * @see #FULL_WAKE_LOCK 432 * @see #SCREEN_DIM_WAKE_LOCK 433 * @see #SCREEN_BRIGHT_WAKE_LOCK 434 * @see #ACQUIRE_CAUSES_WAKEUP 435 * @see #ON_AFTER_RELEASE 436 */ 437 public WakeLock newWakeLock(int levelAndFlags, String tag) { 438 validateWakeLockParameters(levelAndFlags, tag); 439 return new WakeLock(levelAndFlags, tag, mContext.getOpPackageName()); 440 } 441 442 /** @hide */ 443 public static void validateWakeLockParameters(int levelAndFlags, String tag) { 444 switch (levelAndFlags & WAKE_LOCK_LEVEL_MASK) { 445 case PARTIAL_WAKE_LOCK: 446 case SCREEN_DIM_WAKE_LOCK: 447 case SCREEN_BRIGHT_WAKE_LOCK: 448 case FULL_WAKE_LOCK: 449 case PROXIMITY_SCREEN_OFF_WAKE_LOCK: 450 case DOZE_WAKE_LOCK: 451 break; 452 default: 453 throw new IllegalArgumentException("Must specify a valid wake lock level."); 454 } 455 if (tag == null) { 456 throw new IllegalArgumentException("The tag must not be null."); 457 } 458 } 459 460 /** 461 * Notifies the power manager that user activity happened. 462 * <p> 463 * Resets the auto-off timer and brightens the screen if the device 464 * is not asleep. This is what happens normally when a key or the touch 465 * screen is pressed or when some other user activity occurs. 466 * This method does not wake up the device if it has been put to sleep. 467 * </p><p> 468 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 469 * </p> 470 * 471 * @param when The time of the user activity, in the {@link SystemClock#uptimeMillis()} 472 * time base. This timestamp is used to correctly order the user activity request with 473 * other power management functions. It should be set 474 * to the timestamp of the input event that caused the user activity. 475 * @param noChangeLights If true, does not cause the keyboard backlight to turn on 476 * because of this event. This is set when the power key is pressed. 477 * We want the device to stay on while the button is down, but we're about 478 * to turn off the screen so we don't want the keyboard backlight to turn on again. 479 * Otherwise the lights flash on and then off and it looks weird. 480 * 481 * @see #wakeUp 482 * @see #goToSleep 483 */ 484 public void userActivity(long when, boolean noChangeLights) { 485 try { 486 mService.userActivity(when, USER_ACTIVITY_EVENT_OTHER, 487 noChangeLights ? USER_ACTIVITY_FLAG_NO_CHANGE_LIGHTS : 0); 488 } catch (RemoteException e) { 489 } 490 } 491 492 /** 493 * Forces the device to go to sleep. 494 * <p> 495 * Overrides all the wake locks that are held. 496 * This is what happens when the power key is pressed to turn off the screen. 497 * </p><p> 498 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 499 * </p> 500 * 501 * @param time The time when the request to go to sleep was issued, in the 502 * {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly 503 * order the go to sleep request with other power management functions. It should be set 504 * to the timestamp of the input event that caused the request to go to sleep. 505 * 506 * @see #userActivity 507 * @see #wakeUp 508 */ 509 public void goToSleep(long time) { 510 goToSleep(time, GO_TO_SLEEP_REASON_USER, 0); 511 } 512 513 /** 514 * @hide 515 */ 516 public void goToSleep(long time, int reason, int flags) { 517 try { 518 mService.goToSleep(time, reason, flags); 519 } catch (RemoteException e) { 520 } 521 } 522 523 /** 524 * Forces the device to wake up from sleep. 525 * <p> 526 * If the device is currently asleep, wakes it up, otherwise does nothing. 527 * This is what happens when the power key is pressed to turn on the screen. 528 * </p><p> 529 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 530 * </p> 531 * 532 * @param time The time when the request to wake up was issued, in the 533 * {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly 534 * order the wake up request with other power management functions. It should be set 535 * to the timestamp of the input event that caused the request to wake up. 536 * 537 * @see #userActivity 538 * @see #goToSleep 539 */ 540 public void wakeUp(long time) { 541 try { 542 mService.wakeUp(time); 543 } catch (RemoteException e) { 544 } 545 } 546 547 /** 548 * Forces the device to start napping. 549 * <p> 550 * If the device is currently awake, starts dreaming, otherwise does nothing. 551 * When the dream ends or if the dream cannot be started, the device will 552 * either wake up or go to sleep depending on whether there has been recent 553 * user activity. 554 * </p><p> 555 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 556 * </p> 557 * 558 * @param time The time when the request to nap was issued, in the 559 * {@link SystemClock#uptimeMillis()} time base. This timestamp is used to correctly 560 * order the nap request with other power management functions. It should be set 561 * to the timestamp of the input event that caused the request to nap. 562 * 563 * @see #wakeUp 564 * @see #goToSleep 565 * 566 * @hide 567 */ 568 public void nap(long time) { 569 try { 570 mService.nap(time); 571 } catch (RemoteException e) { 572 } 573 } 574 575 /** 576 * Sets the brightness of the backlights (screen, keyboard, button). 577 * <p> 578 * Requires the {@link android.Manifest.permission#DEVICE_POWER} permission. 579 * </p> 580 * 581 * @param brightness The brightness value from 0 to 255. 582 * 583 * {@hide} 584 */ 585 public void setBacklightBrightness(int brightness) { 586 try { 587 mService.setTemporaryScreenBrightnessSettingOverride(brightness); 588 } catch (RemoteException e) { 589 } 590 } 591 592 /** 593 * Returns true if the specified wake lock level is supported. 594 * 595 * @param level The wake lock level to check. 596 * @return True if the specified wake lock level is supported. 597 * 598 * {@hide} 599 */ 600 public boolean isWakeLockLevelSupported(int level) { 601 try { 602 return mService.isWakeLockLevelSupported(level); 603 } catch (RemoteException e) { 604 return false; 605 } 606 } 607 608 /** 609 * Returns true if the device is in an interactive state. 610 * <p> 611 * For historical reasons, the name of this method refers to the power state of 612 * the screen but it actually describes the overall interactive state of 613 * the device. This method has been replaced by {@link #isInteractive}. 614 * </p><p> 615 * The value returned by this method only indicates whether the device is 616 * in an interactive state which may have nothing to do with the screen being 617 * on or off. To determine the actual state of the screen, 618 * use {@link android.view.Display#getState}. 619 * </p> 620 * 621 * @return True if the device is in an interactive state. 622 * 623 * @deprecated Use {@link #isInteractive} instead. 624 */ 625 @Deprecated 626 public boolean isScreenOn() { 627 return isInteractive(); 628 } 629 630 /** 631 * Returns true if the device is in an interactive state. 632 * <p> 633 * When this method returns true, the device is awake and ready to interact 634 * with the user (although this is not a guarantee that the user is actively 635 * interacting with the device just this moment). The main screen is usually 636 * turned on while in this state. Certain features, such as the proximity 637 * sensor, may temporarily turn off the screen while still leaving the device in an 638 * interactive state. Note in particular that the device is still considered 639 * to be interactive while dreaming (since dreams can be interactive) but not 640 * when it is dozing or asleep. 641 * </p><p> 642 * When this method returns false, the device is dozing or asleep and must 643 * be awoken before it will become ready to interact with the user again. The 644 * main screen is usually turned off while in this state. Certain features, 645 * such as "ambient mode" may cause the main screen to remain on (albeit in a 646 * low power state) to display system-provided content while the device dozes. 647 * </p><p> 648 * The system will send a {@link android.content.Intent#ACTION_SCREEN_ON screen on} 649 * or {@link android.content.Intent#ACTION_SCREEN_OFF screen off} broadcast 650 * whenever the interactive state of the device changes. For historical reasons, 651 * the names of these broadcasts refer to the power state of the screen 652 * but they are actually sent in response to changes in the overall interactive 653 * state of the device, as described by this method. 654 * </p><p> 655 * Services may use the non-interactive state as a hint to conserve power 656 * since the user is not present. 657 * </p> 658 * 659 * @return True if the device is in an interactive state. 660 * 661 * @see android.content.Intent#ACTION_SCREEN_ON 662 * @see android.content.Intent#ACTION_SCREEN_OFF 663 */ 664 public boolean isInteractive() { 665 try { 666 return mService.isInteractive(); 667 } catch (RemoteException e) { 668 return false; 669 } 670 } 671 672 /** 673 * Reboot the device. Will not return if the reboot is successful. 674 * <p> 675 * Requires the {@link android.Manifest.permission#REBOOT} permission. 676 * </p> 677 * 678 * @param reason code to pass to the kernel (e.g., "recovery") to 679 * request special boot modes, or null. 680 */ 681 public void reboot(String reason) { 682 try { 683 mService.reboot(false, reason, true); 684 } catch (RemoteException e) { 685 } 686 } 687 688 /** 689 * Returns true if the device is currently in power save mode. When in this mode, 690 * applications should reduce their functionality in order to conserve battery as 691 * much as possible. You can monitor for changes to this state with 692 * {@link #ACTION_POWER_SAVE_MODE_CHANGED}. 693 * 694 * @return Returns true if currently in low power mode, else false. 695 */ 696 public boolean isPowerSaveMode() { 697 try { 698 return mService.isPowerSaveMode(); 699 } catch (RemoteException e) { 700 return false; 701 } 702 } 703 704 /** 705 * Intent that is broadcast when the state of {@link #isPowerSaveMode()} changes. 706 * This broadcast is only sent to registered receivers. 707 */ 708 @SdkConstant(SdkConstant.SdkConstantType.BROADCAST_INTENT_ACTION) 709 public static final String ACTION_POWER_SAVE_MODE_CHANGED 710 = "android.os.action.POWER_SAVE_MODE_CHANGED"; 711 712 /** 713 * A wake lock is a mechanism to indicate that your application needs 714 * to have the device stay on. 715 * <p> 716 * Any application using a WakeLock must request the {@code android.permission.WAKE_LOCK} 717 * permission in an {@code <uses-permission>} element of the application's manifest. 718 * Obtain a wake lock by calling {@link PowerManager#newWakeLock(int, String)}. 719 * </p><p> 720 * Call {@link #acquire()} to acquire the wake lock and force the device to stay 721 * on at the level that was requested when the wake lock was created. 722 * </p><p> 723 * Call {@link #release()} when you are done and don't need the lock anymore. 724 * It is very important to do this as soon as possible to avoid running down the 725 * device's battery excessively. 726 * </p> 727 */ 728 public final class WakeLock { 729 private int mFlags; 730 private String mTag; 731 private final String mPackageName; 732 private final IBinder mToken; 733 private int mCount; 734 private boolean mRefCounted = true; 735 private boolean mHeld; 736 private WorkSource mWorkSource; 737 private String mHistoryTag; 738 739 private final Runnable mReleaser = new Runnable() { 740 public void run() { 741 release(); 742 } 743 }; 744 745 WakeLock(int flags, String tag, String packageName) { 746 mFlags = flags; 747 mTag = tag; 748 mPackageName = packageName; 749 mToken = new Binder(); 750 } 751 752 @Override 753 protected void finalize() throws Throwable { 754 synchronized (mToken) { 755 if (mHeld) { 756 Log.wtf(TAG, "WakeLock finalized while still held: " + mTag); 757 try { 758 mService.releaseWakeLock(mToken, 0); 759 } catch (RemoteException e) { 760 } 761 } 762 } 763 } 764 765 /** 766 * Sets whether this WakeLock is reference counted. 767 * <p> 768 * Wake locks are reference counted by default. If a wake lock is 769 * reference counted, then each call to {@link #acquire()} must be 770 * balanced by an equal number of calls to {@link #release()}. If a wake 771 * lock is not reference counted, then one call to {@link #release()} is 772 * sufficient to undo the effect of all previous calls to {@link #acquire()}. 773 * </p> 774 * 775 * @param value True to make the wake lock reference counted, false to 776 * make the wake lock non-reference counted. 777 */ 778 public void setReferenceCounted(boolean value) { 779 synchronized (mToken) { 780 mRefCounted = value; 781 } 782 } 783 784 /** 785 * Acquires the wake lock. 786 * <p> 787 * Ensures that the device is on at the level requested when 788 * the wake lock was created. 789 * </p> 790 */ 791 public void acquire() { 792 synchronized (mToken) { 793 acquireLocked(); 794 } 795 } 796 797 /** 798 * Acquires the wake lock with a timeout. 799 * <p> 800 * Ensures that the device is on at the level requested when 801 * the wake lock was created. The lock will be released after the given timeout 802 * expires. 803 * </p> 804 * 805 * @param timeout The timeout after which to release the wake lock, in milliseconds. 806 */ 807 public void acquire(long timeout) { 808 synchronized (mToken) { 809 acquireLocked(); 810 mHandler.postDelayed(mReleaser, timeout); 811 } 812 } 813 814 private void acquireLocked() { 815 if (!mRefCounted || mCount++ == 0) { 816 // Do this even if the wake lock is already thought to be held (mHeld == true) 817 // because non-reference counted wake locks are not always properly released. 818 // For example, the keyguard's wake lock might be forcibly released by the 819 // power manager without the keyguard knowing. A subsequent call to acquire 820 // should immediately acquire the wake lock once again despite never having 821 // been explicitly released by the keyguard. 822 mHandler.removeCallbacks(mReleaser); 823 try { 824 mService.acquireWakeLock(mToken, mFlags, mTag, mPackageName, mWorkSource, 825 mHistoryTag); 826 } catch (RemoteException e) { 827 } 828 mHeld = true; 829 } 830 } 831 832 /** 833 * Releases the wake lock. 834 * <p> 835 * This method releases your claim to the CPU or screen being on. 836 * The screen may turn off shortly after you release the wake lock, or it may 837 * not if there are other wake locks still held. 838 * </p> 839 */ 840 public void release() { 841 release(0); 842 } 843 844 /** 845 * Releases the wake lock with flags to modify the release behavior. 846 * <p> 847 * This method releases your claim to the CPU or screen being on. 848 * The screen may turn off shortly after you release the wake lock, or it may 849 * not if there are other wake locks still held. 850 * </p> 851 * 852 * @param flags Combination of flag values to modify the release behavior. 853 * Currently only {@link #WAIT_FOR_PROXIMITY_NEGATIVE} is supported. 854 * 855 * {@hide} 856 */ 857 public void release(int flags) { 858 synchronized (mToken) { 859 if (!mRefCounted || --mCount == 0) { 860 mHandler.removeCallbacks(mReleaser); 861 if (mHeld) { 862 try { 863 mService.releaseWakeLock(mToken, flags); 864 } catch (RemoteException e) { 865 } 866 mHeld = false; 867 } 868 } 869 if (mCount < 0) { 870 throw new RuntimeException("WakeLock under-locked " + mTag); 871 } 872 } 873 } 874 875 /** 876 * Returns true if the wake lock has been acquired but not yet released. 877 * 878 * @return True if the wake lock is held. 879 */ 880 public boolean isHeld() { 881 synchronized (mToken) { 882 return mHeld; 883 } 884 } 885 886 /** 887 * Sets the work source associated with the wake lock. 888 * <p> 889 * The work source is used to determine on behalf of which application 890 * the wake lock is being held. This is useful in the case where a 891 * service is performing work on behalf of an application so that the 892 * cost of that work can be accounted to the application. 893 * </p> 894 * 895 * @param ws The work source, or null if none. 896 */ 897 public void setWorkSource(WorkSource ws) { 898 synchronized (mToken) { 899 if (ws != null && ws.size() == 0) { 900 ws = null; 901 } 902 903 final boolean changed; 904 if (ws == null) { 905 changed = mWorkSource != null; 906 mWorkSource = null; 907 } else if (mWorkSource == null) { 908 changed = true; 909 mWorkSource = new WorkSource(ws); 910 } else { 911 changed = mWorkSource.diff(ws); 912 if (changed) { 913 mWorkSource.set(ws); 914 } 915 } 916 917 if (changed && mHeld) { 918 try { 919 mService.updateWakeLockWorkSource(mToken, mWorkSource, mHistoryTag); 920 } catch (RemoteException e) { 921 } 922 } 923 } 924 } 925 926 /** @hide */ 927 public void setTag(String tag) { 928 mTag = tag; 929 } 930 931 /** @hide */ 932 public void setHistoryTag(String tag) { 933 mHistoryTag = tag; 934 } 935 936 /** @hide */ 937 public void setUnimportantForLogging(boolean state) { 938 if (state) mFlags |= UNIMPORTANT_FOR_LOGGING; 939 else mFlags &= ~UNIMPORTANT_FOR_LOGGING; 940 } 941 942 @Override 943 public String toString() { 944 synchronized (mToken) { 945 return "WakeLock{" 946 + Integer.toHexString(System.identityHashCode(this)) 947 + " held=" + mHeld + ", refCount=" + mCount + "}"; 948 } 949 } 950 } 951} 952