include/hal-battery.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_SYSTEM_BATTERY_H__
  19 #define __TIZEN_SYSTEM_BATTERY_H__
  20
  21
  22 #include <stdbool.h>
  23 #include "device-error.h"
  24
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #define BATTERY_INFO_MAX 32
  31
  32 /**
  33  * @addtogroup CAPI_SYSTEM_DEVICE_BATTERY_MODULE
  34  * @{
  35  */
  36
  37
  38 /**
  39  * @brief Enumeration for the battery level status.
  40  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  41  */
  42 typedef enum {
  43     DEVICE_BATTERY_LEVEL_EMPTY = 0, /**< The battery goes empty. Prepare for the safe termination of the application, because the device starts a shutdown process soon after entering this level. */
  44     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. */
  45     DEVICE_BATTERY_LEVEL_LOW, /**< The battery has little charge left. */
  46     DEVICE_BATTERY_LEVEL_HIGH, /**< The battery status is not to be careful. */
  47     DEVICE_BATTERY_LEVEL_FULL, /**< The battery status is fully charged. It means no more charge. */
  48 } device_battery_level_e;
  49
  50
  51 /**
  52  * @brief Enumeration for battery health information.
  53  * @since_tizen 3.0
  54  */
  55 typedef enum {
  56         DEVICE_BATTERY_HEALTH_GOOD, /**< The battery health is good */
  57         DEVICE_BATTERY_HEALTH_COLD, /**< The temperature of the battery is cold */
  58         DEVICE_BATTERY_HEALTH_DEAD, /**< The battery is dead */
  59         DEVICE_BATTERY_HEALTH_OVER_HEAT, /**< The temperature of the battery is high */
  60         DEVICE_BATTERY_HEALTH_OVER_VOLTAGE, /**< The battery is in over voltage state */
  61 } device_battery_health_e;
  62
  63
  64 /**
  65  * @brief Enumeration for power source information.
  66  * @since_tizen 3.0
  67  */
  68 typedef enum {
  69         DEVICE_BATTERY_POWER_SOURCE_NONE, /**< There is no power source */
  70         DEVICE_BATTERY_POWER_SOURCE_AC, /**< AC power cable is connected */
  71         DEVICE_BATTERY_POWER_SOURCE_USB, /**< USB power cable is connected */
  72         DEVICE_BATTERY_POWER_SOURCE_WIRELESS, /**< Power is provided by a wireless source */
  73 } device_battery_power_source_e;
  74
  75
  76 /**
  77  * @brief Enumeration for battery property information.
  78  * @since_tizen 3.0
  79  */
  80 typedef enum {
  81         DEVICE_BATTERY_PROPERTY_CAPACITY, /**< The battery capacity (0 ~ 100 %) */
  82         DEVICE_BATTERY_PROPERTY_CURRENT_NOW, /**< The battery current (uA) */
  83         DEVICE_BATTERY_PROPERTY_CURRENT_AVERAGE, /**< The average battery current (uA) */
  84         DEVICE_BATTERY_PROPERTY_VOLTAGE_NOW, /**< The battery voltage (uV) (Since 5.0) */
  85         DEVICE_BATTERY_PROPERTY_VOLTAGE_AVERAGE, /**< The average battery voltage (uV) (Since 5.0) */
  86         DEVICE_BATTERY_PROPERTY_TEMPERATURE, /**< The battery temperature (`C) (Since 5.0) */
  87 } device_battery_property_e;
  88
  89
  90 /**
  91  * @brief Enumeration for battery status information.
  92  * @since_tizen 3.0
  93  */
  94 typedef enum {
  95         DEVICE_BATTERY_STATUS_CHARGING, /**< Battery is charging */
  96         DEVICE_BATTERY_STATUS_DISCHARGING, /**< Battery is discharging */
  97         DEVICE_BATTERY_STATUS_FULL, /**< Battery is fully charged */
  98         DEVICE_BATTERY_STATUS_NOT_CHARGING, /**< Battery is not charging */
  99 } device_battery_status_e;
 100
 101
 102 struct device_battery_info {
 103         char status[BATTERY_INFO_MAX];
 104         char health[BATTERY_INFO_MAX];
 105         char power_source[BATTERY_INFO_MAX];
 106         int online;
 107         int present;
 108         int capacity;
 109         int current_now;
 110         int current_average;
 111         int voltage_now;
 112         int voltage_average;
 113         int temperature;
 114 };
 115
 116 /**
 117  * @brief Gets the battery charge percentage.
 118  * @details It returns an integer value from @c 0 to @c 100 that indicates remaining battery charge
 119  *          as a percentage of the maximum level.
 120  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 121  * @remarks In order to be notified when the battery state changes, use system_info_set_changed_cb().
 122  * @param[out] percent The remaining battery charge percentage (@c 0 ~ @c 100)
 123  * @return @c 0 on success,
 124  *         otherwise a negative error value
 125  * @retval #DEVICE_ERROR_NONE Successful
 126  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 127  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
 128  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 129  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 130  */
 131 int device_battery_get_percent(int *percent);
 132
 133
 134 /**
 135  * @brief Gets the charging state.
 136  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 137  * @param[out] charging The battery charging state
 138  * @return @c 0 on success,
 139  *         otherwise a negative error value
 140  * @retval #DEVICE_ERROR_NONE Successful
 141  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 142  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 143  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 144  * @see device_add_callback
 145  * @see device_remove_callback
 146  * @see #DEVICE_CALLBACK_BATTERY_CHARGING
 147  */
 148 int device_battery_is_charging(bool *charging);
 149
 150
 151 /**
 152  * @brief Gets the battery level status.
 153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 154  * @param[out] status The battery level status
 155  * @return @c 0 on success,
 156  *         otherwise a negative error value
 157  * @retval #DEVICE_ERROR_NONE Successful
 158  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 159  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 160  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 161  * @see device_battery_level_e
 162  * @see device_add_callback
 163  * @see device_remove_callback
 164  * @see #DEVICE_CALLBACK_BATTERY_LEVEL
 165  */
 166 int device_battery_get_level_status(device_battery_level_e *status);
 167
 168
 169 /**
 170  * @brief Gets the battery health information.
 171  * @since_tizen 3.0
 172  * @param[out] health The battery health information
 173  * @return @c 0 on success,
 174  *         otherwise a negative error value
 175  * @retval #DEVICE_ERROR_NONE Successful
 176  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 177  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 178  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 179  */
 180 int device_battery_get_health(device_battery_health_e *health);
 181
 182
 183 /**
 184  * @brief Gets the battery power source information.
 185  * @since_tizen 3.0
 186  * @param[out] source The battery power source information
 187  * @return @c 0 on success,
 188  *         otherwise a negative error value
 189  * @retval #DEVICE_ERROR_NONE Successful
 190  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 191  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 192  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 193  */
 194 int device_battery_get_power_source(device_battery_power_source_e *source);
 195
 196
 197 /**
 198  * @brief Gets the battery properties.
 199  * @since_tizen 3.0
 200  * @param[in] property The property type
 201  * @param[out] value The battery information for the property given
 202  * @return @c 0 on success,
 203  *         otherwise a negative error value
 204  * @retval #DEVICE_ERROR_NONE Successful
 205  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 206  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 207  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 208  */
 209 int device_battery_get_property(device_battery_property_e property, int *value);
 210
 211
 212 /**
 213  * @brief Gets the battery status information.
 214  * @since_tizen 3.0
 215  * @param[out] status The battery status information
 216  * @return @c 0 on success,
 217  *         otherwise a negative error value
 218  * @retval #DEVICE_ERROR_NONE Successful
 219  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 220  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 221  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 222  */
 223 int device_battery_get_status(device_battery_status_e *status);
 224
 225
 226 /**
 227  * @}
 228  */
 229
 230
 231 #ifdef __cplusplus
 232 }
 233 #endif
 234
 235
 236 #endif  // __TIZEN_SYSTEM_BATTERY_H__