1 /* 2 * Copyright (C) 2008 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 static android.os.Flags.FLAG_STATE_OF_HEALTH_PUBLIC; 20 import static android.os.Flags.FLAG_BATTERY_PART_STATUS_API; 21 22 import android.Manifest.permission; 23 import android.annotation.FlaggedApi; 24 import android.annotation.Nullable; 25 import android.annotation.RequiresPermission; 26 import android.annotation.SuppressLint; 27 import android.annotation.SystemApi; 28 import android.annotation.SystemService; 29 import android.annotation.TestApi; 30 import android.compat.annotation.UnsupportedAppUsage; 31 import android.content.Context; 32 import android.content.Intent; 33 import android.hardware.health.V1_0.Constants; 34 35 import com.android.internal.app.IBatteryStats; 36 37 /** 38 * The BatteryManager class contains strings and constants used for values 39 * in the {@link android.content.Intent#ACTION_BATTERY_CHANGED} Intent, and 40 * provides a method for querying battery and charging properties. 41 */ 42 @SystemService(Context.BATTERY_SERVICE) 43 public class BatteryManager { 44 /** 45 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 46 * integer containing the current status constant. 47 */ 48 public static final String EXTRA_STATUS = "status"; 49 50 /** 51 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 52 * integer containing the current health constant. 53 */ 54 public static final String EXTRA_HEALTH = "health"; 55 56 /** 57 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 58 * boolean indicating whether a battery is present. 59 */ 60 public static final String EXTRA_PRESENT = "present"; 61 62 /** 63 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 64 * integer field containing the current battery level, from 0 to 65 * {@link #EXTRA_SCALE}. 66 */ 67 public static final String EXTRA_LEVEL = "level"; 68 69 /** 70 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 71 * Boolean field indicating whether the battery is currently considered to be 72 * low, that is whether a {@link Intent#ACTION_BATTERY_LOW} broadcast 73 * has been sent. 74 */ 75 public static final String EXTRA_BATTERY_LOW = "battery_low"; 76 77 /** 78 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 79 * integer containing the maximum battery level. 80 */ 81 public static final String EXTRA_SCALE = "scale"; 82 83 /** 84 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 85 * integer containing the resource ID of a small status bar icon 86 * indicating the current battery state. 87 */ 88 public static final String EXTRA_ICON_SMALL = "icon-small"; 89 90 /** 91 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 92 * integer indicating whether the device is plugged in to a power 93 * source; 0 means it is on battery, other constants are different 94 * types of power sources. 95 */ 96 public static final String EXTRA_PLUGGED = "plugged"; 97 98 /** 99 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 100 * integer containing the current battery voltage level. 101 */ 102 public static final String EXTRA_VOLTAGE = "voltage"; 103 104 /** 105 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 106 * integer containing the current battery temperature. 107 */ 108 public static final String EXTRA_TEMPERATURE = "temperature"; 109 110 /** 111 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 112 * String describing the technology of the current battery. 113 */ 114 public static final String EXTRA_TECHNOLOGY = "technology"; 115 116 /** 117 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 118 * Int value set to nonzero if an unsupported charger is attached 119 * to the device. 120 * {@hide} 121 */ 122 @UnsupportedAppUsage 123 public static final String EXTRA_INVALID_CHARGER = "invalid_charger"; 124 125 /** 126 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 127 * Int value set to the maximum charging current supported by the charger in micro amperes. 128 * {@hide} 129 */ 130 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 131 public static final String EXTRA_MAX_CHARGING_CURRENT = "max_charging_current"; 132 133 /** 134 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 135 * Int value set to the maximum charging voltage supported by the charger in micro volts. 136 * {@hide} 137 */ 138 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 139 public static final String EXTRA_MAX_CHARGING_VOLTAGE = "max_charging_voltage"; 140 141 /** 142 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 143 * integer containing the charge counter present in the battery. 144 * It shows the available battery power in µAh 145 * {@hide} 146 */ 147 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 148 public static final String EXTRA_CHARGE_COUNTER = "charge_counter"; 149 150 /** 151 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 152 * Current int sequence number of the update. 153 * {@hide} 154 */ 155 public static final String EXTRA_SEQUENCE = "seq"; 156 157 /** 158 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 159 * Int value representing the battery charging cycle count. 160 */ 161 public static final String EXTRA_CYCLE_COUNT = "android.os.extra.CYCLE_COUNT"; 162 163 /** 164 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 165 * Int value representing the battery charging status. 166 */ 167 public static final String EXTRA_CHARGING_STATUS = "android.os.extra.CHARGING_STATUS"; 168 169 /** 170 * Battery capacity level is unsupported. 171 * 172 * @see #EXTRA_CAPACITY_LEVEL 173 */ 174 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 175 public static final int BATTERY_CAPACITY_LEVEL_UNSUPPORTED = -1; 176 177 /** 178 * Battery capacity level is unknown. 179 * 180 * @see #EXTRA_CAPACITY_LEVEL 181 */ 182 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 183 public static final int BATTERY_CAPACITY_LEVEL_UNKNOWN = 0; 184 185 /** 186 * Battery capacity level is critical. The Android framework has been notified to schedule 187 * a shutdown by this value. 188 * 189 * @see #EXTRA_CAPACITY_LEVEL 190 */ 191 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 192 public static final int BATTERY_CAPACITY_LEVEL_CRITICAL = 1; 193 194 /** 195 * Battery capacity level is low. The Android framework must limit background jobs to avoid 196 * impacting charging speed. 197 * 198 * @see #EXTRA_CAPACITY_LEVEL 199 */ 200 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 201 public static final int BATTERY_CAPACITY_LEVEL_LOW = 2; 202 203 /** 204 * Battery capacity level is normal. Battery level and charging rates are normal, battery 205 * temperature is within the normal range, and adapter power is enough to charge the battery 206 * at an acceptable rate. The Android framework can run light background tasks without 207 * affecting charging performance severely. 208 * 209 * @see #EXTRA_CAPACITY_LEVEL 210 */ 211 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 212 public static final int BATTERY_CAPACITY_LEVEL_NORMAL = 3; 213 214 /** 215 * Battery capacity level is high. Battery level is high, battery temperature is within the 216 * normal range, and adapter power is enough to charge the battery at an acceptable rate 217 * while running background loads. The Android framework can run background tasks without 218 * affecting charging or battery performance. 219 * 220 * @see #EXTRA_CAPACITY_LEVEL 221 */ 222 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 223 public static final int BATTERY_CAPACITY_LEVEL_HIGH = 4; 224 225 /** 226 * Battery capacity level is full. The battery is full, the battery temperature is within the 227 * normal range, and adapter power is enough to sustain running background loads. The Android 228 * framework can run background tasks without affecting the battery level or battery 229 * performance. 230 * 231 * @see #EXTRA_CAPACITY_LEVEL 232 */ 233 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 234 public static final int BATTERY_CAPACITY_LEVEL_FULL = 5; 235 236 /** 237 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 238 * Int value representing the battery's capacity level. These constants are key indicators of 239 * battery status and system capabilities, guiding power management decisions for both the 240 * system and apps. 241 * 242 * @see #BATTERY_CAPACITY_LEVEL_UNSUPPORTED 243 * @see #BATTERY_CAPACITY_LEVEL_UNKNOWN 244 * @see #BATTERY_CAPACITY_LEVEL_CRITICAL 245 * @see #BATTERY_CAPACITY_LEVEL_LOW 246 * @see #BATTERY_CAPACITY_LEVEL_NORMAL 247 * @see #BATTERY_CAPACITY_LEVEL_HIGH 248 * @see #BATTERY_CAPACITY_LEVEL_FULL 249 */ 250 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 251 public static final String EXTRA_CAPACITY_LEVEL = "android.os.extra.CAPACITY_LEVEL"; 252 253 /** 254 * Extra for {@link android.content.Intent#ACTION_BATTERY_LEVEL_CHANGED}: 255 * Contains list of Bundles representing battery events 256 * @hide 257 */ 258 @SystemApi 259 public static final String EXTRA_EVENTS = "android.os.extra.EVENTS"; 260 261 /** 262 * Extra for event in {@link android.content.Intent#ACTION_BATTERY_LEVEL_CHANGED}: 263 * Long value representing time when event occurred as returned by 264 * {@link android.os.SystemClock#elapsedRealtime()} 265 * @hide 266 */ 267 @SystemApi 268 public static final String EXTRA_EVENT_TIMESTAMP = "android.os.extra.EVENT_TIMESTAMP"; 269 270 // values for "status" field in the ACTION_BATTERY_CHANGED Intent 271 public static final int BATTERY_STATUS_UNKNOWN = Constants.BATTERY_STATUS_UNKNOWN; 272 public static final int BATTERY_STATUS_CHARGING = Constants.BATTERY_STATUS_CHARGING; 273 public static final int BATTERY_STATUS_DISCHARGING = Constants.BATTERY_STATUS_DISCHARGING; 274 public static final int BATTERY_STATUS_NOT_CHARGING = Constants.BATTERY_STATUS_NOT_CHARGING; 275 public static final int BATTERY_STATUS_FULL = Constants.BATTERY_STATUS_FULL; 276 277 // values for "health" field in the ACTION_BATTERY_CHANGED Intent 278 public static final int BATTERY_HEALTH_UNKNOWN = Constants.BATTERY_HEALTH_UNKNOWN; 279 public static final int BATTERY_HEALTH_GOOD = Constants.BATTERY_HEALTH_GOOD; 280 public static final int BATTERY_HEALTH_OVERHEAT = Constants.BATTERY_HEALTH_OVERHEAT; 281 public static final int BATTERY_HEALTH_DEAD = Constants.BATTERY_HEALTH_DEAD; 282 public static final int BATTERY_HEALTH_OVER_VOLTAGE = Constants.BATTERY_HEALTH_OVER_VOLTAGE; 283 public static final int BATTERY_HEALTH_UNSPECIFIED_FAILURE = Constants.BATTERY_HEALTH_UNSPECIFIED_FAILURE; 284 public static final int BATTERY_HEALTH_COLD = Constants.BATTERY_HEALTH_COLD; 285 286 // values of the "plugged" field in the ACTION_BATTERY_CHANGED intent. 287 // These must be powers of 2. 288 /** Power source is an AC charger. */ 289 public static final int BATTERY_PLUGGED_AC = OsProtoEnums.BATTERY_PLUGGED_AC; // = 1 290 /** Power source is a USB port. */ 291 public static final int BATTERY_PLUGGED_USB = OsProtoEnums.BATTERY_PLUGGED_USB; // = 2 292 /** Power source is wireless. */ 293 public static final int BATTERY_PLUGGED_WIRELESS = OsProtoEnums.BATTERY_PLUGGED_WIRELESS; // = 4 294 /** Power source is dock. */ 295 public static final int BATTERY_PLUGGED_DOCK = OsProtoEnums.BATTERY_PLUGGED_DOCK; // = 8 296 297 // values for "charge policy" property 298 /** 299 * Default policy (e.g. normal). 300 * @hide 301 */ 302 @SystemApi 303 public static final int CHARGING_POLICY_DEFAULT = OsProtoEnums.CHARGING_POLICY_DEFAULT; // = 1 304 /** 305 * Optimized for battery health using static thresholds (e.g stop at 80%). 306 * @hide 307 */ 308 @SystemApi 309 public static final int CHARGING_POLICY_ADAPTIVE_AON = 310 OsProtoEnums.CHARGING_POLICY_ADAPTIVE_AON; // = 2 311 /** 312 * Optimized for battery health using adaptive thresholds. 313 * @hide 314 */ 315 @SystemApi 316 public static final int CHARGING_POLICY_ADAPTIVE_AC = 317 OsProtoEnums.CHARGING_POLICY_ADAPTIVE_AC; // = 3 318 /** 319 * Optimized for battery health, devices always connected to power. 320 * @hide 321 */ 322 @SystemApi 323 public static final int CHARGING_POLICY_ADAPTIVE_LONGLIFE = 324 OsProtoEnums.CHARGING_POLICY_ADAPTIVE_LONGLIFE; // = 4 325 326 /** 327 * Returns true if the policy is some type of adaptive charging policy. 328 * @hide 329 */ isAdaptiveChargingPolicy(int policy)330 public static boolean isAdaptiveChargingPolicy(int policy) { 331 return policy == CHARGING_POLICY_ADAPTIVE_AC 332 || policy == CHARGING_POLICY_ADAPTIVE_AON 333 || policy == CHARGING_POLICY_ADAPTIVE_LONGLIFE; 334 } 335 336 // values for "battery part status" property 337 /** 338 * Battery part status is not supported. 339 * @hide 340 */ 341 @SystemApi 342 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 343 public static final int PART_STATUS_UNSUPPORTED = 0; 344 345 /** 346 * Battery is the original device battery. 347 * @hide 348 */ 349 @SystemApi 350 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 351 public static final int PART_STATUS_ORIGINAL = 1; 352 353 /** 354 * Battery has been replaced. 355 * @hide 356 */ 357 @SystemApi 358 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 359 public static final int PART_STATUS_REPLACED = 2; 360 361 /** @hide */ 362 @SuppressLint("UnflaggedApi") // TestApi without associated feature. 363 @TestApi 364 public static final int BATTERY_PLUGGED_ANY = 365 BATTERY_PLUGGED_AC | BATTERY_PLUGGED_USB | BATTERY_PLUGGED_WIRELESS 366 | BATTERY_PLUGGED_DOCK; 367 368 /** 369 * Sent when the device's battery has started charging (or has reached full charge 370 * and the device is on power). This is a good time to do work that you would like to 371 * avoid doing while on battery (that is to avoid draining the user's battery due to 372 * things they don't care enough about). 373 * 374 * This is paired with {@link #ACTION_DISCHARGING}. The current state can always 375 * be retrieved with {@link #isCharging()}. 376 */ 377 public static final String ACTION_CHARGING = "android.os.action.CHARGING"; 378 379 /** 380 * Sent when the device's battery may be discharging, so apps should avoid doing 381 * extraneous work that would cause it to discharge faster. 382 * 383 * This is paired with {@link #ACTION_CHARGING}. The current state can always 384 * be retrieved with {@link #isCharging()}. 385 */ 386 public static final String ACTION_DISCHARGING = "android.os.action.DISCHARGING"; 387 388 /* 389 * Battery property identifiers. These must match the values in 390 * frameworks/native/include/batteryservice/BatteryService.h 391 */ 392 /** Battery capacity in microampere-hours, as an integer. */ 393 public static final int BATTERY_PROPERTY_CHARGE_COUNTER = 1; 394 395 /** 396 * Instantaneous battery current in microamperes, as an integer. Positive 397 * values indicate net current entering the battery from a charge source, 398 * negative values indicate net current discharging from the battery. 399 */ 400 public static final int BATTERY_PROPERTY_CURRENT_NOW = 2; 401 402 /** 403 * Average battery current in microamperes, as an integer. Positive 404 * values indicate net current entering the battery from a charge source, 405 * negative values indicate net current discharging from the battery. 406 * The time period over which the average is computed may depend on the 407 * fuel gauge hardware and its configuration. 408 */ 409 public static final int BATTERY_PROPERTY_CURRENT_AVERAGE = 3; 410 411 /** 412 * Remaining battery capacity as an integer percentage of total capacity 413 * (with no fractional part). 414 */ 415 public static final int BATTERY_PROPERTY_CAPACITY = 4; 416 417 /** 418 * Battery remaining energy in nanowatt-hours, as a long integer. 419 */ 420 public static final int BATTERY_PROPERTY_ENERGY_COUNTER = 5; 421 422 /** 423 * Battery charge status, from a BATTERY_STATUS_* value. 424 */ 425 public static final int BATTERY_PROPERTY_STATUS = 6; 426 427 /** 428 * Battery manufacturing date is reported in epoch. The 0 timepoint 429 * begins at midnight Coordinated Universal Time (UTC) on January 1, 1970. 430 * It is a long integer in seconds. 431 * 432 * <p class="note"> 433 * The sender must hold the {@link android.Manifest.permission#BATTERY_STATS} permission. 434 * 435 * Example: <code> 436 * // The value returned from the API can be used to create a Date, used 437 * // to set the time on a calendar and coverted to a string. 438 * import java.util.Date; 439 * 440 * mBatteryManager = mContext.getSystemService(BatteryManager.class); 441 * final long manufacturingDate = 442 * mBatteryManager.getLongProperty(BatteryManager.BATTERY_PROPERTY_MANUFACTURING_DATE); 443 * Date date = new Date(manufacturingDate); 444 * Calendar calendar = Calendar.getInstance(); 445 * calendar.setTime(date); 446 * // Convert to yyyy-MM-dd HH:mm:ss format string 447 * SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"); 448 * String dateString = sdf.format(date); 449 * </code> 450 * @hide 451 */ 452 @RequiresPermission(permission.BATTERY_STATS) 453 @SystemApi 454 public static final int BATTERY_PROPERTY_MANUFACTURING_DATE = 7; 455 456 /** 457 * The date of first usage is reported in epoch. The 0 timepoint 458 * begins at midnight Coordinated Universal Time (UTC) on January 1, 1970. 459 * It is a long integer in seconds. 460 * 461 * <p class="note"> 462 * The sender must hold the {@link android.Manifest.permission#BATTERY_STATS} permission. 463 * 464 * {@link BATTERY_PROPERTY_MANUFACTURING_DATE for sample code} 465 * @hide 466 */ 467 @RequiresPermission(permission.BATTERY_STATS) 468 @SystemApi 469 public static final int BATTERY_PROPERTY_FIRST_USAGE_DATE = 8; 470 471 /** 472 * Battery charging policy from a CHARGING_POLICY_* value.. 473 * 474 * <p class="note"> 475 * The sender must hold the {@link android.Manifest.permission#BATTERY_STATS} permission. 476 * 477 * @hide 478 */ 479 @RequiresPermission(permission.BATTERY_STATS) 480 @SystemApi 481 public static final int BATTERY_PROPERTY_CHARGING_POLICY = 9; 482 483 /** 484 * Percentage representing the measured battery state of health. 485 * This is the remaining estimated full charge capacity relative 486 * to the rated capacity in %. 487 */ 488 @FlaggedApi(FLAG_STATE_OF_HEALTH_PUBLIC) 489 public static final int BATTERY_PROPERTY_STATE_OF_HEALTH = 10; 490 491 /** 492 * Battery part serial number. 493 * 494 * <p class="note"> 495 * The sender must hold the {@link android.Manifest.permission#BATTERY_STATS} permission. 496 * 497 * @hide 498 */ 499 @RequiresPermission(permission.BATTERY_STATS) 500 @SystemApi 501 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 502 public static final int BATTERY_PROPERTY_SERIAL_NUMBER = 11; 503 504 /** 505 * Battery part status from a BATTERY_PART_STATUS_* value. 506 * 507 * <p class="note"> 508 * The sender must hold the {@link android.Manifest.permission#BATTERY_STATS} permission. 509 * 510 * @hide 511 */ 512 @RequiresPermission(permission.BATTERY_STATS) 513 @SystemApi 514 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) 515 public static final int BATTERY_PROPERTY_PART_STATUS = 12; 516 517 private final Context mContext; 518 private final IBatteryStats mBatteryStats; 519 private final IBatteryPropertiesRegistrar mBatteryPropertiesRegistrar; 520 521 /** 522 * @removed Was previously made visible by accident. 523 */ BatteryManager()524 public BatteryManager() { 525 mContext = null; 526 mBatteryStats = IBatteryStats.Stub.asInterface( 527 ServiceManager.getService(BatteryStats.SERVICE_NAME)); 528 mBatteryPropertiesRegistrar = IBatteryPropertiesRegistrar.Stub.asInterface( 529 ServiceManager.getService("batteryproperties")); 530 } 531 532 /** {@hide} */ BatteryManager(Context context, IBatteryStats batteryStats, IBatteryPropertiesRegistrar batteryPropertiesRegistrar)533 public BatteryManager(Context context, 534 IBatteryStats batteryStats, 535 IBatteryPropertiesRegistrar batteryPropertiesRegistrar) { 536 mContext = context; 537 mBatteryStats = batteryStats; 538 mBatteryPropertiesRegistrar = batteryPropertiesRegistrar; 539 } 540 541 /** 542 * Return true if the battery is currently considered to be charging. This means that 543 * the device is plugged in and is supplying sufficient power that the battery level is 544 * going up (or the battery is fully charged). Changes in this state are matched by 545 * broadcasts of {@link #ACTION_CHARGING} and {@link #ACTION_DISCHARGING}. 546 */ isCharging()547 public boolean isCharging() { 548 try { 549 return mBatteryStats.isCharging(); 550 } catch (RemoteException e) { 551 throw e.rethrowFromSystemServer(); 552 } 553 } 554 555 /** 556 * Query a battery property from the batteryproperties service. 557 * 558 * Returns the requested value, or Long.MIN_VALUE if property not 559 * supported on this system or on other error. 560 */ queryProperty(int id)561 private long queryProperty(int id) { 562 long ret; 563 564 if (mBatteryPropertiesRegistrar == null) { 565 return Long.MIN_VALUE; 566 } 567 568 try { 569 BatteryProperty prop = new BatteryProperty(); 570 if (mBatteryPropertiesRegistrar.getProperty(id, prop) == 0) 571 ret = prop.getLong(); 572 else 573 ret = Long.MIN_VALUE; 574 } catch (RemoteException e) { 575 throw e.rethrowFromSystemServer(); 576 } 577 578 return ret; 579 } 580 581 /** 582 * Same as queryProperty, but for strings. 583 */ queryStringProperty(int id)584 private String queryStringProperty(int id) { 585 if (mBatteryPropertiesRegistrar == null) { 586 return null; 587 } 588 589 try { 590 BatteryProperty prop = new BatteryProperty(); 591 if (mBatteryPropertiesRegistrar.getProperty(id, prop) == 0) { 592 return prop.getString(); 593 } 594 return null; 595 } catch (RemoteException e) { 596 throw e.rethrowFromSystemServer(); 597 } 598 } 599 600 /** 601 * Return the value of a battery property of integer type. 602 * 603 * @param id identifier of the requested property 604 * 605 * @return the property value. If the property is not supported or there is any other error, 606 * return (a) 0 if {@code targetSdkVersion < VERSION_CODES.P} or (b) Integer.MIN_VALUE 607 * if {@code targetSdkVersion >= VERSION_CODES.P}. 608 */ getIntProperty(int id)609 public int getIntProperty(int id) { 610 long value = queryProperty(id); 611 if (value == Long.MIN_VALUE && mContext != null 612 && mContext.getApplicationInfo().targetSdkVersion 613 >= android.os.Build.VERSION_CODES.P) { 614 return Integer.MIN_VALUE; 615 } 616 617 return (int) value; 618 } 619 620 /** 621 * Return the value of a battery property of long type If the 622 * platform does not provide the property queried, this value will 623 * be Long.MIN_VALUE. 624 * 625 * @param id identifier of the requested property 626 * 627 * @return the property value, or Long.MIN_VALUE if not supported. 628 */ getLongProperty(int id)629 public long getLongProperty(int id) { 630 return queryProperty(id); 631 } 632 633 /** 634 * Return the value of a battery property of String type. If the 635 * platform does not provide the property queried, this value will 636 * be null. 637 * 638 * @param id identifier of the requested property. 639 * 640 * @return the property value, or null if not supported. 641 */ 642 @Nullable 643 @FlaggedApi(FLAG_BATTERY_PART_STATUS_API) getStringProperty(int id)644 public String getStringProperty(int id) { 645 return queryStringProperty(id); 646 } 647 648 /** 649 * Return true if the plugType given is wired 650 * @param plugType {@link #BATTERY_PLUGGED_AC}, {@link #BATTERY_PLUGGED_USB}, 651 * or {@link #BATTERY_PLUGGED_WIRELESS} 652 * 653 * @return true if plugType is wired 654 * @hide 655 */ isPlugWired(int plugType)656 public static boolean isPlugWired(int plugType) { 657 return plugType == BATTERY_PLUGGED_USB || plugType == BATTERY_PLUGGED_AC; 658 } 659 660 /** 661 * Compute an approximation for how much time (in milliseconds) remains until the battery is 662 * fully charged. Returns -1 if no time can be computed: either there is not enough current 663 * data to make a decision or the battery is currently discharging. 664 * 665 * @return how much time is left, in milliseconds, until the battery is fully charged or -1 if 666 * the computation fails 667 */ computeChargeTimeRemaining()668 public long computeChargeTimeRemaining() { 669 try { 670 return mBatteryStats.computeChargeTimeRemaining(); 671 } catch (RemoteException e) { 672 throw e.rethrowFromSystemServer(); 673 } 674 } 675 676 /** 677 * Sets the delay for reporting battery state as charging after device is plugged in. 678 * This allows machine-learning or heuristics to delay the reporting and the corresponding 679 * broadcast, based on battery level, charging rate, and/or other parameters. 680 * 681 * @param delayMillis the delay in milliseconds, negative value to reset. 682 * 683 * @return True if the delay was set successfully. 684 * 685 * @see ACTION_CHARGING 686 * @hide 687 */ 688 @RequiresPermission(permission.POWER_SAVER) 689 @SystemApi setChargingStateUpdateDelayMillis(int delayMillis)690 public boolean setChargingStateUpdateDelayMillis(int delayMillis) { 691 try { 692 return mBatteryStats.setChargingStateUpdateDelayMillis(delayMillis); 693 } catch (RemoteException e) { 694 throw e.rethrowFromSystemServer(); 695 } 696 } 697 } 698