universum.studios.android.device.battery

Interface Battery

public interface Battery

Battery interface specifies API through which an actual information about the Android device's battery may be accessed.

A battery implementation may be obtained via Battery.PROVIDER.getBattery(Context).

Below are listed methods provided by the this interface:

• getStatus()
• getStrength()
• getPluggedState()
• getHealth()
• getVoltage()
• getTechnology()

Listening for changes in the battery

The following code snippet shows, how to properly register battery receivers and where to handle the desired callbacks.

 public class BatteryActivity extends Activity {

      // Battery state listener.
      private final Battery.OnStatusListener STATUS_LISTENER = new Battery.OnStatusListener() {

          @Override
          public void onStatusChange(@NonNull Battery battery, @NonNull Context context) {
              // Handle here battery status changes.
          }
      }

      // Battery health listener.
      private final Battery.OnHealthListener HEALTH_LISTENER = new Battery.OnHealthListener() {

          @Override
          public void onHealthOk(@NonNull Battery battery, @NonNull Context context) {
              // Handle here battery health OK status.
          }

          @Override
          public void onHealthLow(@NonNull Battery battery, @NonNull Context context) {
              // Handle here battery health LOW status.
          }
      }

      // Battery plugged state listener.
      private final Battery.OnPluggedStateListener PLUGGED_STATE_LISTENER = new Battery.OnPluggedStateListener() {

          @Override
          public void onPluggedToPowerSource(@NonNull Battery battery, @NonNull Context context) {
              // Handle here battery charging status.
          }

          @Override
          public void onUnpluggedFromPowerSource(@NonNull Battery battery, @NonNull Context context) {
              // Handle here battery discharging status.
          }
      }

      // Battery implementation.
      private Battery mBattery;

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          // ...
          // Get the battery API implementation.
          this.mBattery = Battery.PROVIDER.getBattery(this);
          // Register battery listeners to handle battery status changes.
          mBattery.registerOnStatusListener(STATUS_LISTENER);
          mBattery.registerOnHealthListener(HEALTH_LISTENER);
          mBattery.registerOnPluggedStateListener(PLUGGED_STATE_LISTENER);
          // ...
      }

      @Override
      protected void onResume() {
          super.onResume();
          // Register battery broadcast receivers so the Battery implementation will receive info
          // about the current battery status, plugged state or health.
          mBattery.registerBatteryReceiver(this, Battery.RECEIVER_BATTERY_STATUS | Battery.RECEIVER_BATTERY_HEALTH | Battery.RECEIVER_BATTERY_PLUGGED_STATE);
      }

      @Override
      protected void onPause() {
          super.onPause();
          // Un-register all registered receivers.
          mBattery.unregisterBatteryReceiver(this, Battery.RECEIVER_BATTERY_STATUS | Battery.RECEIVER_BATTERY_HEALTH | Battery.RECEIVER_BATTERY_PLUGGED_STATE);
      }

      @Override
      protected void onDestroy() {
          super.onDestroy();
          // Un-register battery listeners.
          mBattery.registerOnStatusListener(STATUS_LISTENER);
          mBattery.registerOnHealthListener(HEALTH_LISTENER);
          mBattery.registerOnPluggedStateListener(PLUGGED_STATE_LISTENER);
      }
 }
 

Author:

Martin Albedinsky

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Battery.BatteryBroadcastReceiver Base battery status broadcast receiver.
static class	Battery.BatteryTechnology Represents technology of the Android device's battery.
static interface	Battery.Health Defines an annotation for determining set of available battery healths.
static interface	Battery.OnHealthListener Listener that may be used to receive callback with info about changed battery's health (LOW/OK).
static interface	Battery.OnPluggedStateListener Listener that may be used to receive callback with info about changed battery's plugged state.
static interface	Battery.OnStatusListener Listener that may be used to receive callback with info about changed battery's status.
static interface	Battery.PluggedState Defines an annotation for determining set of available battery plugged states.
static interface	Battery.Provider Interface for provider that may be used to access implementation of Battery.
static interface	Battery.Receiver Defines an annotation for determining set of available battery receiver ids.
static interface	Battery.Status Defines an annotation for determining set of available battery statuses.

Field Summary

Fields

Modifier and Type	Field and Description
static int	HEALTH_COLD Copy of BatteryManager.BATTERY_HEALTH_COLD flag for better access.
static int	HEALTH_DEAD Copy of BatteryManager.BATTERY_HEALTH_DEAD flag for better access.
static int	HEALTH_GOOD Copy of BatteryManager.BATTERY_HEALTH_GOOD flag for better access.
static int	HEALTH_LOW_LEVEL Default value of the battery health indicating LOW level.
static int	HEALTH_OK_LEVEL Default value of the battery health indicating OK level.
static int	HEALTH_OVER_VOLTAGE Copy of BatteryManager.BATTERY_HEALTH_OVER_VOLTAGE flag for better access.
static int	HEALTH_OVERHEAT Copy of BatteryManager.BATTERY_HEALTH_OVERHEAT flag for better access.
static int	HEALTH_UNKNOWN Copy of BatteryManager.BATTERY_HEALTH_UNKNOWN flag for better access.
static int	HEALTH_UNSPECIFIED_FAILURE Copy of BatteryManager.BATTERY_HEALTH_UNSPECIFIED_FAILURE flag for better access.
static int	PLUGGED_AC Copy of BatteryManager.BATTERY_PLUGGED_AC flag for better access.
static int	PLUGGED_NONE Plugged state flag indicating that the battery isn't connected to any power source.
static int	PLUGGED_UNKNOWN Plugged state flag indicating that the battery plugged state is unknown due to some error or the current battery data are unavailable.
static int	PLUGGED_USB Copy of BatteryManager.BATTERY_PLUGGED_USB flag for better access.
static int	PLUGGED_WIRELESS Copy of BatteryManager.BATTERY_PLUGGED_WIRELESS flag for better access.
static Battery.Provider	PROVIDER A Battery.Provider implementation that may be used to access implementation of Battery.
static int	RECEIVER_BATTERY_HEALTH Flag used to identify BatteryHealthReceiver.
static int	RECEIVER_BATTERY_PLUGGED_STATE Flag used to identify BatteryPluggedStateReceiver.
static int	RECEIVER_BATTERY_STATUS Flag used to identify BatteryStatusReceiver.
static int	STATUS_CHARGING Copy of BatteryManager.BATTERY_STATUS_CHARGING flag for better access.
static int	STATUS_DISCHARGING Copy of BatteryManager.BATTERY_STATUS_DISCHARGING flag for better access.
static int	STATUS_FULL Copy of BatteryManager.BATTERY_STATUS_FULL flag for better access.
static int	STATUS_NOT_CHARGING Copy of BatteryManager.BATTERY_STATUS_NOT_CHARGING flag for better access.
static int	STATUS_UNKNOWN Copy of BatteryManager.BATTERY_STATUS_UNKNOWN flag for better access.

Method Summary

Modifier and Type	Method and Description
int	getHealth() Returns the current health of the Android device's battery.
int	getHealthLowLevel() Returns value of the battery current health LOW level.
int	getHealthOkLevel() Returns value of the battery current health OK level.
int	getPluggedState() Returns the current plugged state of the Android device's battery.
int	getStatus() Returns the current status of the Android device's battery.
int	getStrength() Returns the current strength of life of the Android device's battery.
Battery.BatteryTechnology	getTechnology() Returns the technology of the Android device's battery.
float	getTemperature() Returns the current temperature of the Android device's battery.
int	getVoltage() Returns the current voltage of the Android device's battery.
boolean	isBatteryReceiverRegistered(int receiverFlag) Returns flag indicating whether the battery receiver with the specified receiverFlag is currently registered or not.
boolean	isCharging() Returns flag indicating whether the Android device's battery is currently being charging or not.
boolean	isLow() Returns flag indicating whether the current strength of the Android device's battery is below the LOW (getHealthLowLevel()) level value or not.
boolean	isPlugged() Returns flag indicating whether the Android device's battery is currently plugged to some power source or not.
void	registerBatteryReceiver(android.content.Context context, int receiverFlag) Registers a battery receiver for the given context.
void	registerOnHealthListener(Battery.OnHealthListener listener) Registers a callback to be invoked when health of the battery changes.
void	registerOnPluggedStateListener(Battery.OnPluggedStateListener listener) Registers a callback to be invoked when plugged state of the battery changes.
void	registerOnStatusListener(Battery.OnStatusListener listener) Registers a callback to be invoked when the battery status changes.
void	setHealthLowLevel(int level) Sets value of the battery health LOW level.
void	setHealthOkLevel(int level) Sets value of the battery health OK level.
void	unregisterBatteryReceiver(android.content.Context context, int receiverFlag) Un-registers the battery receiver from the given context.
void	unregisterOnHealthListener(Battery.OnHealthListener listener) Un-registers the given health callback.
void	unregisterOnPluggedStateListener(Battery.OnPluggedStateListener listener) Un-registers the given plugged state callback.
void	unregisterOnStatusListener(Battery.OnStatusListener listener) Un-registers the given status callback.

Field Detail

PROVIDER

static final Battery.Provider PROVIDER

A Battery.Provider implementation that may be used to access implementation of Battery.

RECEIVER_BATTERY_STATUS

static final int RECEIVER_BATTERY_STATUS

Flag used to identify BatteryStatusReceiver.

See Also:

Constant Field Values

RECEIVER_BATTERY_HEALTH

static final int RECEIVER_BATTERY_HEALTH

Flag used to identify BatteryHealthReceiver.

See Also:

Constant Field Values

RECEIVER_BATTERY_PLUGGED_STATE

static final int RECEIVER_BATTERY_PLUGGED_STATE

Flag used to identify BatteryPluggedStateReceiver.

See Also:

Constant Field Values

STATUS_UNKNOWN

static final int STATUS_UNKNOWN

Copy of BatteryManager.BATTERY_STATUS_UNKNOWN flag for better access.

See Also:

Constant Field Values

STATUS_CHARGING

static final int STATUS_CHARGING

Copy of BatteryManager.BATTERY_STATUS_CHARGING flag for better access.

See Also:

Constant Field Values

STATUS_DISCHARGING

static final int STATUS_DISCHARGING

Copy of BatteryManager.BATTERY_STATUS_DISCHARGING flag for better access.

See Also:

Constant Field Values

STATUS_NOT_CHARGING

static final int STATUS_NOT_CHARGING

Copy of BatteryManager.BATTERY_STATUS_NOT_CHARGING flag for better access.

See Also:

Constant Field Values

STATUS_FULL

static final int STATUS_FULL

Copy of BatteryManager.BATTERY_STATUS_FULL flag for better access.

See Also:

Constant Field Values

PLUGGED_UNKNOWN

static final int PLUGGED_UNKNOWN

Plugged state flag indicating that the battery plugged state is unknown due to some error or the current battery data are unavailable.

See Also:

Constant Field Values

PLUGGED_NONE

static final int PLUGGED_NONE

Plugged state flag indicating that the battery isn't connected to any power source.

See Also:

Constant Field Values

PLUGGED_AC

static final int PLUGGED_AC

Copy of BatteryManager.BATTERY_PLUGGED_AC flag for better access.

See Also:

Constant Field Values

PLUGGED_USB

static final int PLUGGED_USB

Copy of BatteryManager.BATTERY_PLUGGED_USB flag for better access.

See Also:

Constant Field Values

PLUGGED_WIRELESS

static final int PLUGGED_WIRELESS

Copy of BatteryManager.BATTERY_PLUGGED_WIRELESS flag for better access.

See Also:

Constant Field Values

HEALTH_LOW_LEVEL

static final int HEALTH_LOW_LEVEL

Default value of the battery health indicating LOW level.

Constant value: 15

See Also:

Constant Field Values

HEALTH_OK_LEVEL

static final int HEALTH_OK_LEVEL

Default value of the battery health indicating OK level.

Constant value: 20

See Also:

Constant Field Values

HEALTH_UNKNOWN

static final int HEALTH_UNKNOWN

Copy of BatteryManager.BATTERY_HEALTH_UNKNOWN flag for better access.

See Also:

Constant Field Values

HEALTH_GOOD

static final int HEALTH_GOOD

Copy of BatteryManager.BATTERY_HEALTH_GOOD flag for better access.

See Also:

Constant Field Values

HEALTH_OVERHEAT

static final int HEALTH_OVERHEAT

Copy of BatteryManager.BATTERY_HEALTH_OVERHEAT flag for better access.

See Also:

Constant Field Values

HEALTH_DEAD

static final int HEALTH_DEAD

Copy of BatteryManager.BATTERY_HEALTH_DEAD flag for better access.

See Also:

Constant Field Values

HEALTH_OVER_VOLTAGE

static final int HEALTH_OVER_VOLTAGE

Copy of BatteryManager.BATTERY_HEALTH_OVER_VOLTAGE flag for better access.

See Also:

Constant Field Values

HEALTH_UNSPECIFIED_FAILURE

static final int HEALTH_UNSPECIFIED_FAILURE

Copy of BatteryManager.BATTERY_HEALTH_UNSPECIFIED_FAILURE flag for better access.

See Also:

Constant Field Values

HEALTH_COLD

static final int HEALTH_COLD

Copy of BatteryManager.BATTERY_HEALTH_COLD flag for better access.

See Also:

Constant Field Values

Method Detail

getStrength

int getStrength()

Returns the current strength of life of the Android device's battery.

Returns:

The value of strength in the range [0, 100] or negative number if the current battery data are unavailable.

getStatus

int getStatus()

Returns the current status of the Android device's battery.

Returns:

One of STATUS_CHARGING, STATUS_DISCHARGING, STATUS_NOT_CHARGING STATUS_FULL or STATUS_UNKNOWN if the current battery data are unavailable.

getPluggedState

int getPluggedState()

Returns the current plugged state of the Android device's battery.

Returns:

One of PLUGGED_AC, PLUGGED_USB, PLUGGED_WIRELESS, PLUGGED_NONE or PLUGGED_UNKNOWN if the current battery data are unavailable.

getHealth

int getHealth()

Returns the current health of the Android device's battery.

Returns:

One of HEALTH_GOOD, HEALTH_LOW_LEVEL, HEALTH_OK_LEVEL, HEALTH_DEAD, HEALTH_OVERHEAT, HEALTH_OVER_VOLTAGE or HEALTH_UNKNOWN if the current battery data are unavailable.

getTechnology

Battery.BatteryTechnology getTechnology()

Returns the technology of the Android device's battery.

Returns:

One of Battery.BatteryTechnology values or BatteryTechnology.UNKNOWN if technology can't be parsed due to unknown technology tag name or if the current battery data are unavailable.

getTemperature

float getTemperature()

Returns the current temperature of the Android device's battery.

Returns:

Current temperature in degree Centigrade (°C) or negative number if the current battery data are unavailable.

getVoltage

int getVoltage()

Returns the current voltage of the Android device's battery.

Returns:

Current voltage in milli-Volts (mV) or negative number if current voltage is unknown or the current battery data are unavailable.

isCharging

boolean isCharging()

Returns flag indicating whether the Android device's battery is currently being charging or not.

This is similar to isPlugged() but here is checked the battery current status.

Returns:

True if battery is currently being charging (status == STATUS_CHARGING || STATUS_FULL), false otherwise.

See Also:

isPlugged()

isPlugged

boolean isPlugged()

Returns flag indicating whether the Android device's battery is currently plugged to some power source or not.

This is similar to isCharging() but here is checked the battery current plugged state.

Returns:

True if battery is plugged to some power source, false otherwise.

See Also:

getPluggedState(), isCharging()

isLow

boolean isLow()

Returns flag indicating whether the current strength of the Android device's battery is below the LOW (getHealthLowLevel()) level value or not.

Returns:

True if the current strength is less then or equal to the current LOW level value, false otherwise.

See Also:

getStrength(), getHealth()

setHealthLowLevel

void setHealthLowLevel(int level)

Sets value of the battery health LOW level. This value will be used to determine whether the battery health change should be fired for Battery.OnHealthListener with true flag for isLow parameter.

Note that this level is checked only in case of received intent for BatteryStatusReceiver which must be registered.

Parameters:

level - Level from the range [0, 100].

See Also:

getHealthLowLevel(), registerBatteryReceiver(Context, int)

getHealthLowLevel

int getHealthLowLevel()

Returns value of the battery current health LOW level.

Returns:

The value of LOW level in the range [0, 100].

See Also:

setHealthLowLevel(int), isLow()

setHealthOkLevel

void setHealthOkLevel(int level)

Sets value of the battery health OK level. This value will be used to determine whether the battery health change should be fired for Battery.OnHealthListener with false flag for isLow parameter.

Note that this level is checked only in case of received intent for BatteryStatusReceiver which must be registered.

Parameters:

level - Level from the range [0, 100].

See Also:

getHealthOkLevel(), registerBatteryReceiver(Context, int)

getHealthOkLevel

int getHealthOkLevel()

Returns value of the battery current health OK level.

Returns:

The value of OK level in the range [0, 100].

See Also:

setHealthOkLevel(int)

registerOnStatusListener

void registerOnStatusListener(Battery.OnStatusListener listener)

Registers a callback to be invoked when the battery status changes.

Parameters:

listener - Callback to register.

See Also:

unregisterOnStatusListener(OnStatusListener), registerBatteryReceiver(Context, int)

unregisterOnStatusListener

void unregisterOnStatusListener(Battery.OnStatusListener listener)

Un-registers the given status callback.

Parameters:

listener - Callback to un-register.

See Also:

registerOnStatusListener(OnStatusListener)

registerOnHealthListener

void registerOnHealthListener(Battery.OnHealthListener listener)

Registers a callback to be invoked when health of the battery changes.

Parameters:

listener - Callback to register.

See Also:

unregisterOnHealthListener(OnHealthListener), registerBatteryReceiver(Context, int)

unregisterOnHealthListener

void unregisterOnHealthListener(Battery.OnHealthListener listener)

Un-registers the given health callback.

Parameters:

listener - Callback to un-register.

See Also:

registerOnHealthListener(OnHealthListener)

registerOnPluggedStateListener

void registerOnPluggedStateListener(Battery.OnPluggedStateListener listener)

Registers a callback to be invoked when plugged state of the battery changes.

Parameters:

listener - Callback to register.

See Also:

unregisterOnPluggedStateListener(OnPluggedStateListener), registerBatteryReceiver(Context, int)

unregisterOnPluggedStateListener

void unregisterOnPluggedStateListener(Battery.OnPluggedStateListener listener)

Un-registers the given plugged state callback.

Parameters:

listener - Callback to un-register.

See Also:

registerOnPluggedStateListener(OnPluggedStateListener)

registerBatteryReceiver

void registerBatteryReceiver(android.content.Context context,
                             int receiverFlag)

Registers a battery receiver for the given context.

Parameters:

context - Context where to register the desired battery receiver.

receiverFlag - One of RECEIVER_BATTERY_STATUS, RECEIVER_BATTERY_HEALTH, RECEIVER_BATTERY_PLUGGED_STATE or theirs combination.

See Also:

isBatteryReceiverRegistered(int), unregisterBatteryReceiver(Context, int)

isBatteryReceiverRegistered

boolean isBatteryReceiverRegistered(int receiverFlag)

Returns flag indicating whether the battery receiver with the specified receiverFlag is currently registered or not.

Parameters:

receiverFlag - The flag used to identify the battery receiver. One of RECEIVER_BATTERY_STATUS, RECEIVER_BATTERY_HEALTH, RECEIVER_BATTERY_PLUGGED_STATE or theirs combination.

Returns:

True if battery receiver is registered, false otherwise.

unregisterBatteryReceiver

void unregisterBatteryReceiver(android.content.Context context,
                               int receiverFlag)

Un-registers the battery receiver from the given context.

Parameters:

context - Context where was battery receiver registered before.

receiverFlag - The flag of battery receiver to un-register. One of RECEIVER_BATTERY_STATUS, RECEIVER_BATTERY_HEALTH, RECEIVER_BATTERY_PLUGGED_STATE or theirs combination.

See Also:

registerBatteryReceiver(Context, int)