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