Tizen Native API  5.5
Battery

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:

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

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

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.

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

Enumeration for battery property information.

Since :
3.0
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)

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

Gets the battery health information.

Since :
3.0
Parameters:
[out]healthThe battery health information
Returns:
0 on success, otherwise a negative error value
Return values:
DEVICE_ERROR_NONESuccessful
DEVICE_ERROR_INVALID_PARAMETERInvalid parameter
DEVICE_ERROR_OPERATION_FAILEDOperation failed
DEVICE_ERROR_NOT_SUPPORTEDNot supported device

Gets the battery level status.

Since :
2.3
Parameters:
[out]statusThe battery level status
Returns:
0 on success, otherwise a negative error value
Return values:
DEVICE_ERROR_NONESuccessful
DEVICE_ERROR_INVALID_PARAMETERInvalid parameter
DEVICE_ERROR_OPERATION_FAILEDOperation failed
DEVICE_ERROR_NOT_SUPPORTEDNot 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
Remarks:
In order to be notified when the battery state changes, use system_info_set_changed_cb().
Parameters:
[out]percentThe remaining battery charge percentage (0 ~ 100)
Returns:
0 on success, otherwise a negative error value
Return values:
DEVICE_ERROR_NONESuccessful
DEVICE_ERROR_INVALID_PARAMETERInvalid parameter
DEVICE_ERROR_PERMISSION_DENIEDPermission denied
DEVICE_ERROR_OPERATION_FAILEDOperation failed
DEVICE_ERROR_NOT_SUPPORTEDNot supported device

Gets the battery power source information.

Since :
3.0
Parameters:
[out]sourceThe battery power source information
Returns:
0 on success, otherwise a negative error value
Return values:
DEVICE_ERROR_NONESuccessful
DEVICE_ERROR_INVALID_PARAMETERInvalid parameter
DEVICE_ERROR_OPERATION_FAILEDOperation failed
DEVICE_ERROR_NOT_SUPPORTEDNot supported device
int device_battery_get_property ( device_battery_property_e  property,
int *  value 
)

Gets the battery properties.

Since :
3.0
Parameters:
[in]propertyThe property type
[out]valueThe battery information for the property given
Returns:
0 on success, otherwise a negative error value
Return values:
DEVICE_ERROR_NONESuccessful
DEVICE_ERROR_INVALID_PARAMETERInvalid parameter
DEVICE_ERROR_OPERATION_FAILEDOperation failed
DEVICE_ERROR_NOT_SUPPORTEDNot supported device

Gets the battery status information.

Since :
3.0
Parameters:
[out]statusThe battery status information
Returns:
0 on success, otherwise a negative error value
Return values:
DEVICE_ERROR_NONESuccessful
DEVICE_ERROR_INVALID_PARAMETERInvalid parameter
DEVICE_ERROR_OPERATION_FAILEDOperation failed
DEVICE_ERROR_NOT_SUPPORTEDNot supported device
int device_battery_is_charging ( bool *  charging)

Gets the charging state.

Since :
2.3
Parameters:
[out]chargingThe battery charging state
Returns:
0 on success, otherwise a negative error value
Return values:
DEVICE_ERROR_NONESuccessful
DEVICE_ERROR_INVALID_PARAMETERInvalid parameter
DEVICE_ERROR_OPERATION_FAILEDOperation failed
DEVICE_ERROR_NOT_SUPPORTEDNot supported device
See also:
device_add_callback
device_remove_callback
DEVICE_CALLBACK_BATTERY_CHARGING