Tizen Native API  6.5
Functions | Typedefs
Battery Monitor
Resource

The Battery Monitor API provides per-resource battery consumption by the application.

Required Header

#include <battery_monitor.h>

Overview

Battery consumption by a device does not only comprises power consumed by CPU, but it also includes power consumed by other components like - WiFi, Bt, Display, Mobile radio etc. The user is normally unaware of power consumed by these components & hence when battery drains out, user treats it as abnormal behaviour of device.

Under these circumstances, user takes immediate action like killing all power hungry applications, use minimal display brightness, enable night mode in day time, shutting down some sensors, disabling background data for applications to restrict power usage & in the worst case - uninstall the application.

User's decision making at such time is greatly influenced by the accuracy of battery consumption estimation and statistics provided to him.

With this battery-monitor framework, power consumed by each & every application is determined along with the power consumed by individual resources which are used by the application at the time of running.

The API's provide the following functionality: Battery Power Usage in mAh (milli-Ampere-Hour) for, between a custom start & end time.

  • battery consumption in mAh for specific resource from available data.
  • battery consumption in mAh for all resources used by app_id.
  • battery consumption in mAh by an app-id for a specific resource.
  • total battery usage in mAh by an app-id for certain start & end time pair.
  • battery consumption in mAh by a resource for certain start & end time pair.

Related Features

The API's defined are related with the following features:

  • http://tizen.org/feature/battery

It is recommended to design applications with regard to features, for reliability.

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 using features in your application can be found in the Feature List.

Functions

int battery_monitor_battery_usage_data_destroy (battery_usage_data_h result)
 Destroys the Battery Consumption handle and releases all its resources.
int battery_monitor_usage_data_get_power_usage_per_resource (battery_usage_data_h result, battery_monitor_resource_id_e resource, double *usage)
 Gets the battery consumption in mAh (milli-Ampere hour) for specific resource from available data usage handle.
int battery_monitor_get_power_usage_by_app_for_all_resources (const char *appid, time_t from, time_t to, battery_usage_data_h *result)
 Gets the battery_usage_data_h with battery consumption values in mAh (milli-Ampere hour) by the specified application in custom interval. Data within the last 7 days can be retrieved.
int battery_monitor_get_power_usage_by_app_per_resource (const char *appid, battery_monitor_resource_id_e resource, time_t from, time_t to, double *usage)
 Gets the battery consumption in mAh (milli-Ampere hour) for the specific resource for the given application in custom interval. Data within the last 7 days can be retrieved.
int battery_monitor_get_power_usage_by_app (const char *appid, time_t from, time_t to, double *usage)
 Gets the total battery usage in mAh (milli-Ampere hour) by an application for certain time interval. Data within the last 7 days can be retrieved.
int battery_monitor_get_power_usage_by_resource (battery_monitor_resource_id_e resource, time_t from, time_t to, double *usage)
 Gets the battery usage in mAh (milli-Ampere hour) by a resource for certain time interval. Data within the last 7 days can be retrieved.

Typedefs

typedef struct
battery_monitor_total_consumption_s * 		battery_usage_data_h
 Handle for battery consumption, either total or summary for the selected application.

Typedef Documentation

typedef struct battery_monitor_total_consumption_s* battery_usage_data_h

Handle for battery consumption, either total or summary for the selected application.

Since :
5.5
See also:
battery_monitor_get_power_usage_by_app_for_all_resources()

Enumeration Type Documentation

enum battery_monitor_error_e

Enumeration for battery monitor error codes.

Since :
5.5
Enumerator:
BATTERY_MONITOR_ERROR_NONE 

Successful

BATTERY_MONITOR_ERROR_OUT_OF_MEMORY 

Out of memory

BATTERY_MONITOR_ERROR_INVALID_PARAMETER 

Invalid parameter

BATTERY_MONITOR_ERROR_NO_DATA 

Empty data

BATTERY_MONITOR_ERROR_PERMISSION_DENIED 

Permission denied

BATTERY_MONITOR_ERROR_NOT_SUPPORTED 

Not supported

BATTERY_MONITOR_ERROR_RECORD_NOT_FOUND 

Related record does not exist

BATTERY_MONITOR_ERROR_DB_FAILED 

DB operation failed

BATTERY_MONITOR_ERROR_DB_NOT_OPENED 

DB is not connected

BATTERY_MONITOR_ERROR_INTERNAL 

Internal error for generic use

enum battery_monitor_resource_id_e

Enumeration for battery consuming features.

Since :
5.5
Enumerator:
BATTERY_MONITOR_RESOURCE_ID_BLE 

Bluetooth

BATTERY_MONITOR_RESOURCE_ID_WIFI 

Wi-Fi

BATTERY_MONITOR_RESOURCE_ID_CPU 

CPU

BATTERY_MONITOR_RESOURCE_ID_DISPLAY 

Display

BATTERY_MONITOR_RESOURCE_ID_DEVICE_NETWORK 

Device Network

BATTERY_MONITOR_RESOURCE_ID_GPS_SENSOR 

GPS Sensor

BATTERY_MONITOR_RESOURCE_ID_MAX 

Use for iterating over enums only

Function Documentation

int battery_monitor_battery_usage_data_destroy ( battery_usage_data_h  result)

Destroys the Battery Consumption handle and releases all its resources.

Since :
5.5
Parameters:
[in]resultBattery usage consumption handle for the application
Returns:
0 on success, otherwise a negative error value
Return values:
BATTERY_MONITOR_ERROR_NONESuccessful
BATTERY_MONITOR_ERROR_NOT_SUPPORTEDFeature Not Supported
BATTERY_MONITOR_ERROR_INVALID_PARAMETERInvalid Parameter
int battery_monitor_get_power_usage_by_app ( const char *  appid,
time_t  from,
time_t  to,
double *  usage 
)

Gets the total battery usage in mAh (milli-Ampere hour) by an application for certain time interval. Data within the last 7 days can be retrieved.

This will be sum of all battery consumed by resources used by application.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/systemmonitor
Parameters:
[in]appidApplication ID of the application for which battery usage is required
[in]fromStart Time for data in Epoch Time (in seconds)
[in]toEnd Time for data in Epoch Time (in seconds)
[out]usageBattery consumption in mAh for the application
Returns:
0 on success, otherwise a negative error value
Return values:
BATTERY_MONITOR_ERROR_NONESuccessful
BATTERY_MONITOR_ERROR_NOT_SUPPORTEDFeature Not Supported
BATTERY_MONITOR_ERROR_PERMISSION_DENIEDPermission Denied
BATTERY_MONITOR_ERROR_INVALID_PARAMETERInvalid Parameter
BATTERY_MONITOR_ERROR_DB_NOT_OPENEDDB not Opened
BATTERY_MONITOR_ERROR_DB_FAILEDDB operation failed
BATTERY_MONITOR_ERROR_RECORD_NOT_FOUNDRecord Not found
BATTERY_MONITOR_ERROR_INTERNALInternal Error
int battery_monitor_get_power_usage_by_app_for_all_resources ( const char *  appid,
time_t  from,
time_t  to,
battery_usage_data_h *  result 
)

Gets the battery_usage_data_h with battery consumption values in mAh (milli-Ampere hour) by the specified application in custom interval. Data within the last 7 days can be retrieved.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/systemmonitor
Remarks:
The result handle should be released using battery_monitor_battery_usage_data_destroy().
Parameters:
[in]appidApplication ID of the application for which battery usage is required
[in]fromStart Time for data in Epoch Time (in seconds)
[in]toEnd Time for data in Epoch Time (in seconds)
[out]resultBattery consumption data handle for the application
Returns:
0 on success, otherwise a negative error value
Return values:
BATTERY_MONITOR_ERROR_NONESuccessful
BATTERY_MONITOR_ERROR_NOT_SUPPORTEDFeature Not Supported
BATTERY_MONITOR_ERROR_PERMISSION_DENIEDPermission Denied
BATTERY_MONITOR_ERROR_INVALID_PARAMETERInvalid Parameter
BATTERY_MONITOR_ERROR_DB_NOT_OPENEDDB not Opened
BATTERY_MONITOR_ERROR_DB_FAILEDDB operation failed
BATTERY_MONITOR_ERROR_RECORD_NOT_FOUNDRecord Not found
BATTERY_MONITOR_ERROR_INTERNALInternal Error
See also:
battery_monitor_usage_data_get_power_usage_per_resource()
int battery_monitor_get_power_usage_by_app_per_resource ( const char *  appid,
battery_monitor_resource_id_e  resource,
time_t  from,
time_t  to,
double *  usage 
)

Gets the battery consumption in mAh (milli-Ampere hour) for the specific resource for the given application in custom interval. Data within the last 7 days can be retrieved.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/systemmonitor
Parameters:
[in]appidApplication ID of the application for which battery usage is required
[in]resourceIdentifier of resource type. BLE, WiFi, CPU etc
[in]fromStart Time for data in Epoch Time (in seconds)
[in]toEnd Time for data in Epoch Time (in seconds)
[out]usageBattery consumption in mAh for the application
Returns:
0 on success, otherwise a negative error value
Return values:
BATTERY_MONITOR_ERROR_NONESuccessful
BATTERY_MONITOR_ERROR_NOT_SUPPORTEDFeature Not Supported
BATTERY_MONITOR_ERROR_PERMISSION_DENIEDPermission Denied
BATTERY_MONITOR_ERROR_INVALID_PARAMETERInvalid Parameter
BATTERY_MONITOR_ERROR_DB_NOT_OPENEDDB not Opened
BATTERY_MONITOR_ERROR_DB_FAILEDDB operation failed
BATTERY_MONITOR_ERROR_RECORD_NOT_FOUNDRecord Not found
BATTERY_MONITOR_ERROR_INTERNALInternal Error
int battery_monitor_get_power_usage_by_resource ( battery_monitor_resource_id_e  resource,
time_t  from,
time_t  to,
double *  usage 
)

Gets the battery usage in mAh (milli-Ampere hour) by a resource for certain time interval. Data within the last 7 days can be retrieved.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/systemmonitor
Parameters:
[in]resourceResource identifier for which battery usage is requested
[in]fromStart Time for data in Epoch Time (in seconds)
[in]toEnd Time for data in Epoch Time (in seconds)
[out]usageBattery consumption in mAh (milli-Ampere hour) for resource
Returns:
0 on success, otherwise a negative error value
Return values:
BATTERY_MONITOR_ERROR_NONESuccessful
BATTERY_MONITOR_ERROR_NOT_SUPPORTEDFeature Not Supported
BATTERY_MONITOR_ERROR_PERMISSION_DENIEDPermission Denied
BATTERY_MONITOR_ERROR_INVALID_PARAMETERInvalid Parameter
BATTERY_MONITOR_ERROR_DB_NOT_OPENEDDB not Opened
BATTERY_MONITOR_ERROR_DB_FAILEDDB operation failed
BATTERY_MONITOR_ERROR_RECORD_NOT_FOUNDRecord Not found
BATTERY_MONITOR_ERROR_INTERNALInternal Error
int battery_monitor_usage_data_get_power_usage_per_resource ( battery_usage_data_h  result,
battery_monitor_resource_id_e  resource,
double *  usage 
)

Gets the battery consumption in mAh (milli-Ampere hour) for specific resource from available data usage handle.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/systemmonitor
Parameters:
[in]resultBattery consumption data usage handle for the application
[in]resourceIdentifier of resource type. BLE, WiFi, CPU etc
[out]usageBattery consumption in mAh for resource
Returns:
0 on success, otherwise a negative error value
Return values:
BATTERY_MONITOR_ERROR_NONESuccessful
BATTERY_MONITOR_ERROR_NOT_SUPPORTEDFeature Not Supported
BATTERY_MONITOR_ERROR_PERMISSION_DENIEDPermission Denied
BATTERY_MONITOR_ERROR_INVALID_PARAMETERInvalid Parameter
Precondition:
call battery_monitor_get_power_usage_by_app_for_all_resources() to get data handle