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.annotation.SystemService; 20 import android.content.Context; 21 import android.hardware.health.V1_0.Constants; 22 import com.android.internal.app.IBatteryStats; 23 24 /** 25 * The BatteryManager class contains strings and constants used for values 26 * in the {@link android.content.Intent#ACTION_BATTERY_CHANGED} Intent, and 27 * provides a method for querying battery and charging properties. 28 */ 29 @SystemService(Context.BATTERY_SERVICE) 30 public class BatteryManager { 31 /** 32 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 33 * integer containing the current status constant. 34 */ 35 public static final String EXTRA_STATUS = "status"; 36 37 /** 38 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 39 * integer containing the current health constant. 40 */ 41 public static final String EXTRA_HEALTH = "health"; 42 43 /** 44 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 45 * boolean indicating whether a battery is present. 46 */ 47 public static final String EXTRA_PRESENT = "present"; 48 49 /** 50 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 51 * integer field containing the current battery level, from 0 to 52 * {@link #EXTRA_SCALE}. 53 */ 54 public static final String EXTRA_LEVEL = "level"; 55 56 /** 57 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 58 * integer containing the maximum battery level. 59 */ 60 public static final String EXTRA_SCALE = "scale"; 61 62 /** 63 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 64 * integer containing the resource ID of a small status bar icon 65 * indicating the current battery state. 66 */ 67 public static final String EXTRA_ICON_SMALL = "icon-small"; 68 69 /** 70 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 71 * integer indicating whether the device is plugged in to a power 72 * source; 0 means it is on battery, other constants are different 73 * types of power sources. 74 */ 75 public static final String EXTRA_PLUGGED = "plugged"; 76 77 /** 78 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 79 * integer containing the current battery voltage level. 80 */ 81 public static final String EXTRA_VOLTAGE = "voltage"; 82 83 /** 84 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 85 * integer containing the current battery temperature. 86 */ 87 public static final String EXTRA_TEMPERATURE = "temperature"; 88 89 /** 90 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 91 * String describing the technology of the current battery. 92 */ 93 public static final String EXTRA_TECHNOLOGY = "technology"; 94 95 /** 96 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 97 * Int value set to nonzero if an unsupported charger is attached 98 * to the device. 99 * {@hide} 100 */ 101 public static final String EXTRA_INVALID_CHARGER = "invalid_charger"; 102 103 /** 104 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 105 * Int value set to the maximum charging current supported by the charger in micro amperes. 106 * {@hide} 107 */ 108 public static final String EXTRA_MAX_CHARGING_CURRENT = "max_charging_current"; 109 110 /** 111 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 112 * Int value set to the maximum charging voltage supported by the charger in micro volts. 113 * {@hide} 114 */ 115 public static final String EXTRA_MAX_CHARGING_VOLTAGE = "max_charging_voltage"; 116 117 /** 118 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 119 * integer containing the charge counter present in the battery. 120 * {@hide} 121 */ 122 public static final String EXTRA_CHARGE_COUNTER = "charge_counter"; 123 124 /** 125 * Extra for {@link android.content.Intent#ACTION_BATTERY_CHANGED}: 126 * Current int sequence number of the update. 127 * {@hide} 128 */ 129 public static final String EXTRA_SEQUENCE = "seq"; 130 131 // values for "status" field in the ACTION_BATTERY_CHANGED Intent 132 public static final int BATTERY_STATUS_UNKNOWN = Constants.BATTERY_STATUS_UNKNOWN; 133 public static final int BATTERY_STATUS_CHARGING = Constants.BATTERY_STATUS_CHARGING; 134 public static final int BATTERY_STATUS_DISCHARGING = Constants.BATTERY_STATUS_DISCHARGING; 135 public static final int BATTERY_STATUS_NOT_CHARGING = Constants.BATTERY_STATUS_NOT_CHARGING; 136 public static final int BATTERY_STATUS_FULL = Constants.BATTERY_STATUS_FULL; 137 138 // values for "health" field in the ACTION_BATTERY_CHANGED Intent 139 public static final int BATTERY_HEALTH_UNKNOWN = Constants.BATTERY_HEALTH_UNKNOWN; 140 public static final int BATTERY_HEALTH_GOOD = Constants.BATTERY_HEALTH_GOOD; 141 public static final int BATTERY_HEALTH_OVERHEAT = Constants.BATTERY_HEALTH_OVERHEAT; 142 public static final int BATTERY_HEALTH_DEAD = Constants.BATTERY_HEALTH_DEAD; 143 public static final int BATTERY_HEALTH_OVER_VOLTAGE = Constants.BATTERY_HEALTH_OVER_VOLTAGE; 144 public static final int BATTERY_HEALTH_UNSPECIFIED_FAILURE = Constants.BATTERY_HEALTH_UNSPECIFIED_FAILURE; 145 public static final int BATTERY_HEALTH_COLD = Constants.BATTERY_HEALTH_COLD; 146 147 // values of the "plugged" field in the ACTION_BATTERY_CHANGED intent. 148 // These must be powers of 2. 149 /** Power source is an AC charger. */ 150 public static final int BATTERY_PLUGGED_AC = 1; 151 /** Power source is a USB port. */ 152 public static final int BATTERY_PLUGGED_USB = 2; 153 /** Power source is wireless. */ 154 public static final int BATTERY_PLUGGED_WIRELESS = 4; 155 156 /** @hide */ 157 public static final int BATTERY_PLUGGED_ANY = 158 BATTERY_PLUGGED_AC | BATTERY_PLUGGED_USB | BATTERY_PLUGGED_WIRELESS; 159 160 /** 161 * Sent when the device's battery has started charging (or has reached full charge 162 * and the device is on power). This is a good time to do work that you would like to 163 * avoid doing while on battery (that is to avoid draining the user's battery due to 164 * things they don't care enough about). 165 * 166 * This is paired with {@link #ACTION_DISCHARGING}. The current state can always 167 * be retrieved with {@link #isCharging()}. 168 */ 169 public static final String ACTION_CHARGING = "android.os.action.CHARGING"; 170 171 /** 172 * Sent when the device's battery may be discharging, so apps should avoid doing 173 * extraneous work that would cause it to discharge faster. 174 * 175 * This is paired with {@link #ACTION_CHARGING}. The current state can always 176 * be retrieved with {@link #isCharging()}. 177 */ 178 public static final String ACTION_DISCHARGING = "android.os.action.DISCHARGING"; 179 180 /* 181 * Battery property identifiers. These must match the values in 182 * frameworks/native/include/batteryservice/BatteryService.h 183 */ 184 /** Battery capacity in microampere-hours, as an integer. */ 185 public static final int BATTERY_PROPERTY_CHARGE_COUNTER = 1; 186 187 /** 188 * Instantaneous battery current in microamperes, as an integer. Positive 189 * values indicate net current entering the battery from a charge source, 190 * negative values indicate net current discharging from the battery. 191 */ 192 public static final int BATTERY_PROPERTY_CURRENT_NOW = 2; 193 194 /** 195 * Average battery current in microamperes, as an integer. Positive 196 * values indicate net current entering the battery from a charge source, 197 * negative values indicate net current discharging from the battery. 198 * The time period over which the average is computed may depend on the 199 * fuel gauge hardware and its configuration. 200 */ 201 public static final int BATTERY_PROPERTY_CURRENT_AVERAGE = 3; 202 203 /** 204 * Remaining battery capacity as an integer percentage of total capacity 205 * (with no fractional part). 206 */ 207 public static final int BATTERY_PROPERTY_CAPACITY = 4; 208 209 /** 210 * Battery remaining energy in nanowatt-hours, as a long integer. 211 */ 212 public static final int BATTERY_PROPERTY_ENERGY_COUNTER = 5; 213 214 /** 215 * Battery charge status, from a BATTERY_STATUS_* value. 216 */ 217 public static final int BATTERY_PROPERTY_STATUS = 6; 218 219 private final IBatteryStats mBatteryStats; 220 private final IBatteryPropertiesRegistrar mBatteryPropertiesRegistrar; 221 222 /** 223 * @removed Was previously made visible by accident. 224 */ BatteryManager()225 public BatteryManager() { 226 mBatteryStats = IBatteryStats.Stub.asInterface( 227 ServiceManager.getService(BatteryStats.SERVICE_NAME)); 228 mBatteryPropertiesRegistrar = IBatteryPropertiesRegistrar.Stub.asInterface( 229 ServiceManager.getService("batteryproperties")); 230 } 231 232 /** {@hide} */ BatteryManager(IBatteryStats batteryStats, IBatteryPropertiesRegistrar batteryPropertiesRegistrar)233 public BatteryManager(IBatteryStats batteryStats, 234 IBatteryPropertiesRegistrar batteryPropertiesRegistrar) { 235 mBatteryStats = batteryStats; 236 mBatteryPropertiesRegistrar = batteryPropertiesRegistrar; 237 } 238 239 /** 240 * Return true if the battery is currently considered to be charging. This means that 241 * the device is plugged in and is supplying sufficient power that the battery level is 242 * going up (or the battery is fully charged). Changes in this state are matched by 243 * broadcasts of {@link #ACTION_CHARGING} and {@link #ACTION_DISCHARGING}. 244 */ isCharging()245 public boolean isCharging() { 246 try { 247 return mBatteryStats.isCharging(); 248 } catch (RemoteException e) { 249 throw e.rethrowFromSystemServer(); 250 } 251 } 252 253 /** 254 * Query a battery property from the batteryproperties service. 255 * 256 * Returns the requested value, or Long.MIN_VALUE if property not 257 * supported on this system or on other error. 258 */ queryProperty(int id)259 private long queryProperty(int id) { 260 long ret; 261 262 if (mBatteryPropertiesRegistrar == null) { 263 return Long.MIN_VALUE; 264 } 265 266 try { 267 BatteryProperty prop = new BatteryProperty(); 268 269 if (mBatteryPropertiesRegistrar.getProperty(id, prop) == 0) 270 ret = prop.getLong(); 271 else 272 ret = Long.MIN_VALUE; 273 } catch (RemoteException e) { 274 throw e.rethrowFromSystemServer(); 275 } 276 277 return ret; 278 } 279 280 /** 281 * Return the value of a battery property of integer type. If the 282 * platform does not provide the property queried, this value will 283 * be Integer.MIN_VALUE. 284 * 285 * @param id identifier of the requested property 286 * 287 * @return the property value, or Integer.MIN_VALUE if not supported. 288 */ getIntProperty(int id)289 public int getIntProperty(int id) { 290 return (int)queryProperty(id); 291 } 292 293 /** 294 * Return the value of a battery property of long type If the 295 * platform does not provide the property queried, this value will 296 * be Long.MIN_VALUE. 297 * 298 * @param id identifier of the requested property 299 * 300 * @return the property value, or Long.MIN_VALUE if not supported. 301 */ getLongProperty(int id)302 public long getLongProperty(int id) { 303 return queryProperty(id); 304 } 305 } 306