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.

Overview

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 battery charge percentage.
int	device_battery_is_charging (bool *charging)
	Gets the charging state.
int	device_battery_get_level_status (device_battery_level_e *status)
	Gets the battery level status.
int	device_battery_get_health (device_battery_health_e *health)
	Gets the battery health information.
int	device_battery_get_power_source (device_battery_power_source_e *source)
	Gets the battery power source information.
int	device_battery_get_property (device_battery_property_e property, int *value)
	Gets the battery properties.
int	device_battery_get_status (device_battery_status_e *status)
	Gets the battery status information.

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.1

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 battery health information.

Since :: 3.0

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

int device_battery_get_level_status ( device_battery_level_e * status )

Gets the battery level status.

Since :: 2.3.1

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

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 battery charge percentage.

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

Since :: 2.3.1

Remarks:: In order to be notified when the battery state changes, use system_info_set_changed_cb().

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

int device_battery_get_power_source ( device_battery_power_source_e * source )

Gets the battery power source information.

Since :: 3.0

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

int device_battery_get_property	(	device_battery_property_e	property,
		int *	value
	)

Gets the battery properties.

Since :: 3.0

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

int device_battery_get_status ( device_battery_status_e * status )

Gets the battery status information.

Since :: 3.0

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

int device_battery_is_charging ( bool * charging )

Gets the charging state.

Since :: 2.3.1

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

See also:: device_add_callback; device_remove_callback; DEVICE_CALLBACK_BATTERY_CHARGING

Required Header

Overview

Overview

Functions

Enumeration Type Documentation

Function Documentation