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