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