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