The Battery API provides functions to get information about the battery.

Required Header

#include <device/battery.h>
#include <device/callback.h>

Overview

The Battery API provides the way to get the current battery capacity value, battery state and charging state. It also supports the API for an application to receive the battery events from the system. To receive the battery event it should be described by the callback function.

Related Features

This API is related with the following features:

http://tizen.org/feature/battery

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from feature element description.

Functions
int	device_battery_get_percent (int *percent)
	Gets the current device's battery charge percentage as an interger value.
int	device_battery_is_charging (bool *charging)
	Gets the current device's charging state which the battery is charging.
int	device_battery_get_level_status (device_battery_level_e *status)
	Gets the current device's battery level status as a device_battery_level_e.
int	device_battery_get_health (device_battery_health_e *health)
	Gets the current device's battery health information as a device_battery_health_e.
int	device_battery_get_power_source (device_battery_power_source_e *source)
	Gets the current device's power source information from the battery.
int	device_battery_get_property (device_battery_property_e property, int *value)
	Gets the current device's specified battery property as an interger value.
int	device_battery_get_status (device_battery_status_e *status)
	Gets the current device's battery status according to the degree of charge.

Enumeration Type Documentation

enum device_battery_health_e

Enumeration for battery health information.

Since :: 3.0

Enumerator:

DEVICE_BATTERY_HEALTH_GOOD	The battery health is good
DEVICE_BATTERY_HEALTH_COLD	The temperature of the battery is cold
DEVICE_BATTERY_HEALTH_DEAD	The battery is dead
DEVICE_BATTERY_HEALTH_OVER_HEAT	The temperature of the battery is high
DEVICE_BATTERY_HEALTH_OVER_VOLTAGE	The battery is in over voltage state

enum device_battery_level_e

Enumeration for the battery level status.

Since :: 2.3

Enumerator:

DEVICE_BATTERY_LEVEL_EMPTY	The battery goes empty. Prepare for the safe termination of the application, because the device starts a shutdown process soon after entering this level.
DEVICE_BATTERY_LEVEL_CRITICAL	The battery charge is at a critical state. You may have to stop using multimedia features, because they are not guaranteed to work correctly at this battery status.
DEVICE_BATTERY_LEVEL_LOW	The battery has little charge left.
DEVICE_BATTERY_LEVEL_HIGH	The battery status is not to be careful.
DEVICE_BATTERY_LEVEL_FULL	The battery status is fully charged. It means no more charge.

enum device_battery_power_source_e

Enumeration for power source information.

Since :: 3.0

Enumerator:

DEVICE_BATTERY_POWER_SOURCE_NONE	There is no power source
DEVICE_BATTERY_POWER_SOURCE_AC	AC power cable is connected
DEVICE_BATTERY_POWER_SOURCE_USB	USB power cable is connected
DEVICE_BATTERY_POWER_SOURCE_WIRELESS	Power is provided by a wireless source

enum device_battery_property_e

Enumeration for battery property information.

Since :: 3.0

Remarks:: If the fuel gauge hardware does not provide average current or average voltage, CURRENT_AVERAGE/VOLTAGE_AVERAGE can be substituted by CURRENT_NOW/VOLTAGE_NOW, respectively.

Enumerator:

DEVICE_BATTERY_PROPERTY_CAPACITY	The battery capacity (0 ~ 100 %)
DEVICE_BATTERY_PROPERTY_CURRENT_NOW	The battery current (uA)
DEVICE_BATTERY_PROPERTY_CURRENT_AVERAGE	The average battery current (uA)
DEVICE_BATTERY_PROPERTY_VOLTAGE_NOW	The battery voltage (uV) (Since 5.0)
DEVICE_BATTERY_PROPERTY_VOLTAGE_AVERAGE	The average battery voltage (uV) (Since 5.0)
DEVICE_BATTERY_PROPERTY_TEMPERATURE	The battery temperature (`C) (Since 5.0)

enum device_battery_status_e

Enumeration for battery status information.

Since :: 3.0

Enumerator:

DEVICE_BATTERY_STATUS_CHARGING	Battery is charging
DEVICE_BATTERY_STATUS_DISCHARGING	Battery is discharging
DEVICE_BATTERY_STATUS_FULL	Battery is fully charged
DEVICE_BATTERY_STATUS_NOT_CHARGING	Battery is not charging

Function Documentation

int device_battery_get_health ( device_battery_health_e * health )

Gets the current device's battery health information as a device_battery_health_e.

Retrieves the current battery health status information (e.g., good, overheat, dead, etc).

Since :: 3.0

Remarks:: Ensure that the provided health pointer is valid and has enough memory allocated.

Parameters:

[out] health The battery health information

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/battery.h> ... device_battery_health_e batt_health = DEVICE_BATTERY_HEALTH_GOOD; int ret = 0; ... ret = device_battery_get_health(&batt_health); ...

See also:: device_battery_health_e

int device_battery_get_level_status ( device_battery_level_e * status )

Gets the current device's battery level status as a device_battery_level_e.

Retrieves the current battery level status based on remaining battery capacity.

Since :: 2.3

Remarks:: Ensure that the provided status pointer is valid and has enough memory allocated.

Parameters:

[out] status The battery level status

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/battery.h> ... device_battery_level_e batt_lev_status = DEVICE_BATTERY_LEVEL_EMPTY; int ret = 0; ... ret = device_battery_get_level_status(&batt_lev_status); ...

See also:: device_battery_level_e; device_add_callback; device_remove_callback; DEVICE_CALLBACK_BATTERY_LEVEL

int device_battery_get_percent ( int * percent )

Gets the current device's battery charge percentage as an interger value.

It returns an integer value from 0 to 100 that indicates remaining battery charge as a percentage of the maximum level.

Since :: 2.3

Remarks:: Ensure that the provided percent pointer is valid and has enough memory allocated.

Parameters:

[out] percent The remaining battery charge percentage (0 ~ 100)

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_PERMISSION_DENIED	Permission denied
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/battery.h> ... int percent = 0; int ret = 0; ... ret = device_battery_get_info(&percent); ...

int device_battery_get_power_source ( device_battery_power_source_e * source )

Gets the current device's power source information from the battery.

Retrieves the current battery power source information (e.g., ac, usb, etc).

Since :: 3.0

Remarks:: Ensure that the provided source pointer is valid and has enough memory allocated.

Parameters:

[out] source The battery power source information

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/battery.h> ... device_battery_power_source_e batt_power_src = DEVICE_BATTERY_POWER_SOURCE_NONE; int ret = 0; ... ret = device_battery_get_power_source(&batt_power_src); ...

See also:: device_battery_power_source_e

int device_battery_get_property	(	device_battery_property_e	property,
		int *	value
	)

Gets the current device's specified battery property as an interger value.

Retrieves the current battery property information (e.g., capacity, current_average, temperature, etc).

Since :: 3.0

Remarks:: Ensure that the provided value pointer is valid and has enough memory allocated.

Parameters:

[in]	property	The property type
[out]	value	The battery information for the property given

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/battery.h> ... int value = 0; int ret = 0; ... ret = device_battery_get_property(DEVICE_BATTERY_PROPERTY_CAPACITY, &value); ...

See also:: device_battery_property_e

int device_battery_get_status ( device_battery_status_e * status )

Gets the current device's battery status according to the degree of charge.

Retrieves the current battery status information (e.g., charging, discharging, full, etc).

Since :: 3.0

Remarks:: Ensure that the provided status pointer is valid and has enough memory allocated.

Parameters:

[out] status The battery status information

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/battery.h> ... device_battery_status_e batt_status = DEVICE_BATTERY_STATUS_CHARGING; int ret = 0; ... ret = device_battery_get_property(&batt_status); ...

See also:: device_battery_status_e

int device_battery_is_charging ( bool * charging )

Gets the current device's charging state which the battery is charging.

Checks whether the battery is currently being charged or not.

Since :: 2.3

Remarks:: Ensure that the provided charging pointer is valid and has enough memory allocated.

Parameters:

[out] charging The battery charging state

Returns:: 0 on success, otherwise a negative error value

Return values:

DEVICE_ERROR_NONE	Successful
DEVICE_ERROR_INVALID_PARAMETER	Invalid parameter
DEVICE_ERROR_OPERATION_FAILED	Operation failed
DEVICE_ERROR_NOT_SUPPORTED	Not supported device #include <device/battery.h> ... bool is_charging = false; int ret = 0; ... ret = device_battery_is_charging(&is_charging); ...

See also:: device_add_callback; device_remove_callback; DEVICE_CALLBACK_BATTERY_CHARGING

Required Header

Overview

Related Features

Functions

Enumeration Type Documentation

Function Documentation