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 android.Manifest.permission; 20 import android.annotation.RequiresPermission; 21 import android.annotation.SystemApi; 22 import android.annotation.SystemService; 23 import android.compat.annotation.UnsupportedAppUsage; 24 import android.content.Context; 25 import android.content.Intent; 26 import android.hardware.health.V1_0.Constants; 27 28 import com.android.internal.app.IBatteryStats; 29 30 /** 31 * The BatteryManager class contains strings and constants used for values 32 * in the {@link android.content.Intent#ACTION_BATTERY_CHANGED} Intent, and 33 * provides a method for querying battery and charging properties. 34 */ 35 @SystemService(Context.BATTERY_SERVICE) 36 public class BatteryManager { 37 /** 38 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 39 * integer containing the current status constant. 40 */ 41 public static final String EXTRA_STATUS = "status"; 42 43 /** 44 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 45 * integer containing the current health constant. 46 */ 47 public static final String EXTRA_HEALTH = "health"; 48 49 /** 50 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 51 * boolean indicating whether a battery is present. 52 */ 53 public static final String EXTRA_PRESENT = "present"; 54 55 /** 56 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 57 * integer field containing the current battery level, from 0 to 58 * {@link #EXTRA_SCALE}. 59 */ 60 public static final String EXTRA_LEVEL = "level"; 61 62 /** 63 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 64 * Boolean field indicating whether the battery is currently considered to be 65 * low, that is whether a {@link Intent#ACTION_BATTERY_LOW} broadcast 66 * has been sent. 67 */ 68 public static final String EXTRA_BATTERY_LOW = "battery_low"; 69 70 /** 71 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 72 * integer containing the maximum battery level. 73 */ 74 public static final String EXTRA_SCALE = "scale"; 75 76 /** 77 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 78 * integer containing the resource ID of a small status bar icon 79 * indicating the current battery state. 80 */ 81 public static final String EXTRA_ICON_SMALL = "icon-small"; 82 83 /** 84 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 85 * integer indicating whether the device is plugged in to a power 86 * source; 0 means it is on battery, other constants are different 87 * types of power sources. 88 */ 89 public static final String EXTRA_PLUGGED = "plugged"; 90 91 /** 92 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 93 * integer containing the current battery voltage level. 94 */ 95 public static final String EXTRA_VOLTAGE = "voltage"; 96 97 /** 98 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 99 * integer containing the current battery temperature. 100 */ 101 public static final String EXTRA_TEMPERATURE = "temperature"; 102 103 /** 104 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 105 * String describing the technology of the current battery. 106 */ 107 public static final String EXTRA_TECHNOLOGY = "technology"; 108 109 /** 110 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 111 * Int value set to nonzero if an unsupported charger is attached 112 * to the device. 113 * {@hide} 114 */ 115 @UnsupportedAppUsage 116 public static final String EXTRA_INVALID_CHARGER = "invalid_charger"; 117 118 /** 119 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 120 * Int value set to the maximum charging current supported by the charger in micro amperes. 121 * {@hide} 122 */ 123 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 124 public static final String EXTRA_MAX_CHARGING_CURRENT = "max_charging_current"; 125 126 /** 127 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 128 * Int value set to the maximum charging voltage supported by the charger in micro volts. 129 * {@hide} 130 */ 131 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 132 public static final String EXTRA_MAX_CHARGING_VOLTAGE = "max_charging_voltage"; 133 134 /** 135 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 136 * integer containing the charge counter present in the battery. 137 * {@hide} 138 */ 139 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 140 public static final String EXTRA_CHARGE_COUNTER = "charge_counter"; 141 142 /** 143 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 144 * Current int sequence number of the update. 145 * {@hide} 146 */ 147 public static final String EXTRA_SEQUENCE = "seq"; 148 149 /** 150 * Extra for {@link android.content.Intent#ACTION_BATTERY_LEVEL_CHANGED}: 151 * Contains list of Bundles representing battery events 152 * @hide 153 */ 154 @SystemApi 155 public static final String EXTRA_EVENTS = "android.os.extra.EVENTS"; 156 157 /** 158 * Extra for event in {@link android.content.Intent#ACTION_BATTERY_LEVEL_CHANGED}: 159 * Long value representing time when event occurred as returned by 160 * {@link android.os.SystemClock#elapsedRealtime()} 161 * @hide 162 */ 163 @SystemApi 164 public static final String EXTRA_EVENT_TIMESTAMP = "android.os.extra.EVENT_TIMESTAMP"; 165 166 // values for "status" field in the ACTION_BATTERY_CHANGED Intent 167 public static final int BATTERY_STATUS_UNKNOWN = Constants.BATTERY_STATUS_UNKNOWN; 168 public static final int BATTERY_STATUS_CHARGING = Constants.BATTERY_STATUS_CHARGING; 169 public static final int BATTERY_STATUS_DISCHARGING = Constants.BATTERY_STATUS_DISCHARGING; 170 public static final int BATTERY_STATUS_NOT_CHARGING = Constants.BATTERY_STATUS_NOT_CHARGING; 171 public static final int BATTERY_STATUS_FULL = Constants.BATTERY_STATUS_FULL; 172 173 // values for "health" field in the ACTION_BATTERY_CHANGED Intent 174 public static final int BATTERY_HEALTH_UNKNOWN = Constants.BATTERY_HEALTH_UNKNOWN; 175 public static final int BATTERY_HEALTH_GOOD = Constants.BATTERY_HEALTH_GOOD; 176 public static final int BATTERY_HEALTH_OVERHEAT = Constants.BATTERY_HEALTH_OVERHEAT; 177 public static final int BATTERY_HEALTH_DEAD = Constants.BATTERY_HEALTH_DEAD; 178 public static final int BATTERY_HEALTH_OVER_VOLTAGE = Constants.BATTERY_HEALTH_OVER_VOLTAGE; 179 public static final int BATTERY_HEALTH_UNSPECIFIED_FAILURE = Constants.BATTERY_HEALTH_UNSPECIFIED_FAILURE; 180 public static final int BATTERY_HEALTH_COLD = Constants.BATTERY_HEALTH_COLD; 181 182 // values of the "plugged" field in the ACTION_BATTERY_CHANGED intent. 183 // These must be powers of 2. 184 /** Power source is an AC charger. */ 185 public static final int BATTERY_PLUGGED_AC = OsProtoEnums.BATTERY_PLUGGED_AC; // = 1 186 /** Power source is a USB port. */ 187 public static final int BATTERY_PLUGGED_USB = OsProtoEnums.BATTERY_PLUGGED_USB; // = 2 188 /** Power source is wireless. */ 189 public static final int BATTERY_PLUGGED_WIRELESS = OsProtoEnums.BATTERY_PLUGGED_WIRELESS; // = 4 190 191 /** @hide */ 192 public static final int BATTERY_PLUGGED_ANY = 193 BATTERY_PLUGGED_AC | BATTERY_PLUGGED_USB | BATTERY_PLUGGED_WIRELESS; 194 195 /** 196 * Sent when the device's battery has started charging (or has reached full charge 197 * and the device is on power). This is a good time to do work that you would like to 198 * avoid doing while on battery (that is to avoid draining the user's battery due to 199 * things they don't care enough about). 200 * 201 * This is paired with {@link #ACTION_DISCHARGING}. The current state can always 202 * be retrieved with {@link #isCharging()}. 203 */ 204 public static final String ACTION_CHARGING = "android.os.action.CHARGING"; 205 206 /** 207 * Sent when the device's battery may be discharging, so apps should avoid doing 208 * extraneous work that would cause it to discharge faster. 209 * 210 * This is paired with {@link #ACTION_CHARGING}. The current state can always 211 * be retrieved with {@link #isCharging()}. 212 */ 213 public static final String ACTION_DISCHARGING = "android.os.action.DISCHARGING"; 214 215 /* 216 * Battery property identifiers. These must match the values in 217 * frameworks/native/include/batteryservice/BatteryService.h 218 */ 219 /** Battery capacity in microampere-hours, as an integer. */ 220 public static final int BATTERY_PROPERTY_CHARGE_COUNTER = 1; 221 222 /** 223 * Instantaneous battery current in microamperes, as an integer. Positive 224 * values indicate net current entering the battery from a charge source, 225 * negative values indicate net current discharging from the battery. 226 */ 227 public static final int BATTERY_PROPERTY_CURRENT_NOW = 2; 228 229 /** 230 * Average battery current in microamperes, as an integer. Positive 231 * values indicate net current entering the battery from a charge source, 232 * negative values indicate net current discharging from the battery. 233 * The time period over which the average is computed may depend on the 234 * fuel gauge hardware and its configuration. 235 */ 236 public static final int BATTERY_PROPERTY_CURRENT_AVERAGE = 3; 237 238 /** 239 * Remaining battery capacity as an integer percentage of total capacity 240 * (with no fractional part). 241 */ 242 public static final int BATTERY_PROPERTY_CAPACITY = 4; 243 244 /** 245 * Battery remaining energy in nanowatt-hours, as a long integer. 246 */ 247 public static final int BATTERY_PROPERTY_ENERGY_COUNTER = 5; 248 249 /** 250 * Battery charge status, from a BATTERY_STATUS_* value. 251 */ 252 public static final int BATTERY_PROPERTY_STATUS = 6; 253 254 private final Context mContext; 255 private final IBatteryStats mBatteryStats; 256 private final IBatteryPropertiesRegistrar mBatteryPropertiesRegistrar; 257 258 /** 259 * @removed Was previously made visible by accident. 260 */ BatteryManager()261 public BatteryManager() { 262 mContext = null; 263 mBatteryStats = IBatteryStats.Stub.asInterface( 264 ServiceManager.getService(BatteryStats.SERVICE_NAME)); 265 mBatteryPropertiesRegistrar = IBatteryPropertiesRegistrar.Stub.asInterface( 266 ServiceManager.getService("batteryproperties")); 267 } 268 269 /** {@hide} */ BatteryManager(Context context, IBatteryStats batteryStats, IBatteryPropertiesRegistrar batteryPropertiesRegistrar)270 public BatteryManager(Context context, 271 IBatteryStats batteryStats, 272 IBatteryPropertiesRegistrar batteryPropertiesRegistrar) { 273 mContext = context; 274 mBatteryStats = batteryStats; 275 mBatteryPropertiesRegistrar = batteryPropertiesRegistrar; 276 } 277 278 /** 279 * Return true if the battery is currently considered to be charging. This means that 280 * the device is plugged in and is supplying sufficient power that the battery level is 281 * going up (or the battery is fully charged). Changes in this state are matched by 282 * broadcasts of {@link #ACTION_CHARGING} and {@link #ACTION_DISCHARGING}. 283 */ isCharging()284 public boolean isCharging() { 285 try { 286 return mBatteryStats.isCharging(); 287 } catch (RemoteException e) { 288 throw e.rethrowFromSystemServer(); 289 } 290 } 291 292 /** 293 * Query a battery property from the batteryproperties service. 294 * 295 * Returns the requested value, or Long.MIN_VALUE if property not 296 * supported on this system or on other error. 297 */ queryProperty(int id)298 private long queryProperty(int id) { 299 long ret; 300 301 if (mBatteryPropertiesRegistrar == null) { 302 return Long.MIN_VALUE; 303 } 304 305 try { 306 BatteryProperty prop = new BatteryProperty(); 307 308 if (mBatteryPropertiesRegistrar.getProperty(id, prop) == 0) 309 ret = prop.getLong(); 310 else 311 ret = Long.MIN_VALUE; 312 } catch (RemoteException e) { 313 throw e.rethrowFromSystemServer(); 314 } 315 316 return ret; 317 } 318 319 /** 320 * Return the value of a battery property of integer type. 321 * 322 * @param id identifier of the requested property 323 * 324 * @return the property value. If the property is not supported or there is any other error, 325 * return (a) 0 if {@code targetSdkVersion < VERSION_CODES.P} or (b) Integer.MIN_VALUE 326 * if {@code targetSdkVersion >= VERSION_CODES.P}. 327 */ getIntProperty(int id)328 public int getIntProperty(int id) { 329 long value = queryProperty(id); 330 if (value == Long.MIN_VALUE && mContext != null 331 && mContext.getApplicationInfo().targetSdkVersion 332 >= android.os.Build.VERSION_CODES.P) { 333 return Integer.MIN_VALUE; 334 } 335 336 return (int) value; 337 } 338 339 /** 340 * Return the value of a battery property of long type If the 341 * platform does not provide the property queried, this value will 342 * be Long.MIN_VALUE. 343 * 344 * @param id identifier of the requested property 345 * 346 * @return the property value, or Long.MIN_VALUE if not supported. 347 */ getLongProperty(int id)348 public long getLongProperty(int id) { 349 return queryProperty(id); 350 } 351 352 /** 353 * Return true if the plugType given is wired 354 * @param plugType {@link #BATTERY_PLUGGED_AC}, {@link #BATTERY_PLUGGED_USB}, 355 * or {@link #BATTERY_PLUGGED_WIRELESS} 356 * 357 * @return true if plugType is wired 358 * @hide 359 */ isPlugWired(int plugType)360 public static boolean isPlugWired(int plugType) { 361 return plugType == BATTERY_PLUGGED_USB || plugType == BATTERY_PLUGGED_AC; 362 } 363 364 /** 365 * Compute an approximation for how much time (in milliseconds) remains until the battery is 366 * fully charged. Returns -1 if no time can be computed: either there is not enough current 367 * data to make a decision or the battery is currently discharging. 368 * 369 * @return how much time is left, in milliseconds, until the battery is fully charged or -1 if 370 * the computation fails 371 */ computeChargeTimeRemaining()372 public long computeChargeTimeRemaining() { 373 try { 374 return mBatteryStats.computeChargeTimeRemaining(); 375 } catch (RemoteException e) { 376 throw e.rethrowFromSystemServer(); 377 } 378 } 379 380 /** 381 * Sets the delay for reporting battery state as charging after device is plugged in. 382 * This allows machine-learning or heuristics to delay the reporting and the corresponding 383 * broadcast, based on battery level, charging rate, and/or other parameters. 384 * 385 * @param delayMillis the delay in milliseconds, negative value to reset. 386 * 387 * @return True if the delay was set successfully. 388 * 389 * @see ACTION_CHARGING 390 * @hide 391 */ 392 @RequiresPermission(permission.POWER_SAVER) 393 @SystemApi setChargingStateUpdateDelayMillis(int delayMillis)394 public boolean setChargingStateUpdateDelayMillis(int delayMillis) { 395 try { 396 return mBatteryStats.setChargingStateUpdateDelayMillis(delayMillis); 397 } catch (RemoteException e) { 398 throw e.rethrowFromSystemServer(); 399 } 400 } 401 } 402