include/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
  31 /**
  32  * @addtogroup CAPI_SYSTEM_DEVICE_BATTERY_MODULE
  33  * @{
  34  */
  35
  36
  37 /**
  38  * @brief Enumeration for the battery level status.
  39  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  40  */
  41 typedef enum {
  42     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. */
  43     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. */
  44     DEVICE_BATTERY_LEVEL_LOW, /**< The battery has little charge left. */
  45     DEVICE_BATTERY_LEVEL_HIGH, /**< The battery status is not to be careful. */
  46     DEVICE_BATTERY_LEVEL_FULL, /**< The battery status is fully charged. It means no more charge. */
  47 } device_battery_level_e;
  48
  49
  50 /**
  51  * @brief Enumeration for battery health information.
  52  * @since_tizen 3.0
  53  */
  54 typedef enum {
  55         DEVICE_BATTERY_HEALTH_GOOD, /**< The battery health is good */
  56         DEVICE_BATTERY_HEALTH_COLD, /**< The temperature of the battery is cold */
  57         DEVICE_BATTERY_HEALTH_DEAD, /**< The battery is dead */
  58         DEVICE_BATTERY_HEALTH_OVER_HEAT, /**< The temperature of the battery is high */
  59         DEVICE_BATTERY_HEALTH_OVER_VOLTAGE, /**< The battery is in over voltage state */
  60 } device_battery_health_e;
  61
  62
  63 /**
  64  * @brief Enumeration for power source information.
  65  * @since_tizen 3.0
  66  */
  67 typedef enum {
  68         DEVICE_BATTERY_POWER_SOURCE_NONE, /**< There is no power source */
  69         DEVICE_BATTERY_POWER_SOURCE_AC, /**< AC power cable is connected */
  70         DEVICE_BATTERY_POWER_SOURCE_USB, /**< USB power cable is connected */
  71         DEVICE_BATTERY_POWER_SOURCE_WIRELESS, /**< Power is provided by a wireless source */
  72 } device_battery_power_source_e;
  73
  74
  75 /**
  76  * @brief Enumeration for battery property information.
  77  * @since_tizen 3.0
  78  * @remarks If the fuel gauge hardware does not provide average current or average voltage,
  79             CURRENT_AVERAGE/VOLTAGE_AVERAGE can be substituted by CURRENT_NOW/VOLTAGE_NOW, respectively.
  80  */
  81 typedef enum {
  82         DEVICE_BATTERY_PROPERTY_CAPACITY, /**< The battery capacity (0 ~ 100 %) */
  83         DEVICE_BATTERY_PROPERTY_CURRENT_NOW, /**< The battery current (uA) */
  84         DEVICE_BATTERY_PROPERTY_CURRENT_AVERAGE, /**< The average battery current (uA) */
  85         DEVICE_BATTERY_PROPERTY_VOLTAGE_NOW, /**< The battery voltage (uV) (Since 5.0) */
  86         DEVICE_BATTERY_PROPERTY_VOLTAGE_AVERAGE, /**< The average battery voltage (uV) (Since 5.0) */
  87         DEVICE_BATTERY_PROPERTY_TEMPERATURE, /**< The battery temperature (`C) (Since 5.0) */
  88 } device_battery_property_e;
  89
  90
  91 /**
  92  * @brief Enumeration for battery status information.
  93  * @since_tizen 3.0
  94  */
  95 typedef enum {
  96         DEVICE_BATTERY_STATUS_CHARGING, /**< Battery is charging */
  97         DEVICE_BATTERY_STATUS_DISCHARGING, /**< Battery is discharging */
  98         DEVICE_BATTERY_STATUS_FULL, /**< Battery is fully charged */
  99         DEVICE_BATTERY_STATUS_NOT_CHARGING, /**< Battery is not charging */
 100 } device_battery_status_e;
 101
 102
 103 /**
 104  * @brief Gets the battery charge percentage.
 105  * @details It returns an integer value from @c 0 to @c 100 that indicates remaining battery charge
 106  *          as a percentage of the maximum level.
 107  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 108  * @remarks In order to be notified when the battery state changes, use system_info_set_changed_cb().
 109  * @param[out] percent The remaining battery charge percentage (@c 0 ~ @c 100)
 110  * @return @c 0 on success,
 111  *         otherwise a negative error value
 112  * @retval #DEVICE_ERROR_NONE Successful
 113  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 114  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
 115  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 116  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 117  */
 118 int device_battery_get_percent(int *percent);
 119
 120
 121 /**
 122  * @brief Gets the charging state.
 123  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 124  * @param[out] charging The battery charging state
 125  * @return @c 0 on success,
 126  *         otherwise a negative error value
 127  * @retval #DEVICE_ERROR_NONE Successful
 128  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 129  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 130  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 131  * @see device_add_callback
 132  * @see device_remove_callback
 133  * @see #DEVICE_CALLBACK_BATTERY_CHARGING
 134  */
 135 int device_battery_is_charging(bool *charging);
 136
 137
 138 /**
 139  * @brief Gets the battery level status.
 140  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 141  * @param[out] status The battery level status
 142  * @return @c 0 on success,
 143  *         otherwise a negative error value
 144  * @retval #DEVICE_ERROR_NONE Successful
 145  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 146  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 147  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 148  * @see device_battery_level_e
 149  * @see device_add_callback
 150  * @see device_remove_callback
 151  * @see #DEVICE_CALLBACK_BATTERY_LEVEL
 152  */
 153 int device_battery_get_level_status(device_battery_level_e *status);
 154
 155
 156 /**
 157  * @brief Gets the battery health information.
 158  * @since_tizen 3.0
 159  * @param[out] health The battery health information
 160  * @return @c 0 on success,
 161  *         otherwise a negative error value
 162  * @retval #DEVICE_ERROR_NONE Successful
 163  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 164  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 165  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 166  */
 167 int device_battery_get_health(device_battery_health_e *health);
 168
 169
 170 /**
 171  * @brief Gets the battery power source information.
 172  * @since_tizen 3.0
 173  * @param[out] source The battery power source information
 174  * @return @c 0 on success,
 175  *         otherwise a negative error value
 176  * @retval #DEVICE_ERROR_NONE Successful
 177  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 178  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 179  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 180  */
 181 int device_battery_get_power_source(device_battery_power_source_e *source);
 182
 183
 184 /**
 185  * @brief Gets the battery properties.
 186  * @since_tizen 3.0
 187  * @param[in] property The property type
 188  * @param[out] value The battery information for the property given
 189  * @return @c 0 on success,
 190  *         otherwise a negative error value
 191  * @retval #DEVICE_ERROR_NONE Successful
 192  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 193  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 194  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 195  */
 196 int device_battery_get_property(device_battery_property_e property, int *value);
 197
 198
 199 /**
 200  * @brief Gets the battery status information.
 201  * @since_tizen 3.0
 202  * @param[out] status The battery status information
 203  * @return @c 0 on success,
 204  *         otherwise a negative error value
 205  * @retval #DEVICE_ERROR_NONE Successful
 206  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 207  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 208  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 209  */
 210 int device_battery_get_status(device_battery_status_e *status);
 211
 212
 213 /**
 214  * @}
 215  */
 216
 217
 218 #ifdef __cplusplus
 219 }
 220 #endif
 221
 222
 223 #endif  // __TIZEN_SYSTEM_BATTERY_H__