include/device.h

   1 /*
   2  * Copyright (c) 2011 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
  19
  20 #ifndef __TIZEN_SYSTEM_DEVICE_H__
  21 #define __TIZEN_SYSTEM_DEVICE_H__
  22
  23 #include <stdbool.h>
  24 #include <tizen_error.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30
  31 /**
  32  * @addtogroup CAPI_SYSTEM_DEVICE_MODULE
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Enumerations of error code for Device.
  38  */
  39 typedef enum
  40 {
  41     DEVICE_ERROR_NONE              = TIZEN_ERROR_NONE,                  /**< Successful */
  42     DEVICE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  43     DEVICE_ERROR_OPERATION_FAILED  = TIZEN_ERROR_SYSTEM_CLASS | 0x12, /**< Operation failed */
  44 } device_error_e;
  45
  46 /**
  47  * @}
  48 */
  49
  50  /**
  51  * @addtogroup CAPI_SYSTEM_DEVICE_MODULE
  52  * @{
  53  */
  54
  55 /**
  56  * @brief Called when an battery charge percentage changed
  57  *
  58  * @param[out] percent       The remaining battery charge percentage (0 ~ 100)
  59  * @param[in]  user_data     The user data passed from the callback registration function
  60  *
  61  */
  62 typedef void (*device_battery_cb)(int percent, void *user_data);
  63
  64 /**
  65  * @brief Gets the battery charge percentage.
  66  * @details It returns integer value from 0 to 100 that indicates remaining battery charge
  67  * as a percentage of the maximum level.
  68  * @remarks In order to be notified when the battery state changes, use system_info_set_changed_cb().
  69  *
  70  * @param[out] percent The remaining battery charge percentage (0 ~ 100)
  71  *
  72  * @return 0 on success, otherwise a negative error value.
  73  * @retval #DEVICE_ERROR_NONE                           Successful
  74  * @retval #DEVICE_ERROR_INVALID_PARAMETER      Invalid parameter
  75  * @retval #DEVICE_ERROR_OPERATION_FAILED       Operation failed
  76  *
  77  * @see device_battery_is_full()
  78  * @see system_info_get_value_int(SYSTEM_INFO_KEY_BATTERY_PERCENTAGE, ...)
  79  * @see system_info_get_value_int(SYSTEM_INFO_KEY_BATTERY_CHARGE, ...)
  80  */
  81 int device_battery_get_percent(int *percent);
  82
  83 /**
  84  * @brief Get charging state
  85  *
  86  * @param[out] charging The battery charging state.
  87  *
  88  * @return 0 on success, otherwise a negative error value.
  89  * @retval #DEVICE_ERROR_NONE                           Successful
  90  * @retval #DEVICE_ERROR_INVALID_PARAMETER      Invalid parameter
  91  * @retval #DEVICE_ERROR_OPERATION_FAILED       Operation failed
  92  *
  93  */
  94 int device_battery_is_charging(bool *charging);
  95
  96 /**
  97  * @brief Set callback to be observing battery charge percentage.
  98  *
  99  * @param[in] callback      The callback function to set
 100  * @param[in] user_data     The user data to be passed to the callback function
 101  *
 102  * @return 0 on success, otherwise a negative error value.
 103  * @retval #DEVICE_ERROR_NONE                           Successful
 104  * @retval #DEVICE_ERROR_INVALID_PARAMETER      Invalid parameter
 105  * @retval #DEVICE_ERROR_OPERATION_FAILED       Operation failed
 106  */
 107 int device_battery_set_cb(device_battery_cb callback, void* user_data);
 108
 109 /**
 110  * @brief Unset battery charge percentage callback function.
 111  *
 112  * @return 0 on success, otherwise a negative error value.
 113  * @retval #DEVICE_ERROR_NONE                           Successful
 114  * @retval #DEVICE_ERROR_OPERATION_FAILED       Operation failed
 115  */
 116 int device_battery_unset_cb(void);
 117
 118 /**
 119  * @brief Checks whether the battery is fully charged.
 120  * @remarks In order to be notified when the battery state changes, use system_info_set_changed_cb().
 121  *
 122  * @param[out] full @c true when the battery is fully charged, otherwise @c false.
 123  *
 124  * @return 0 on success, otherwise a negative error value.
 125  * @retval #DEVICE_ERROR_NONE                           Successful
 126  * @retval #DEVICE_ERROR_INVALID_PARAMETER      Invalid parameter
 127  * @retval #DEVICE_ERROR_OPERATION_FAILED       Operation failed
 128  *
 129  * @see device_battery_get_percent()
 130  * @see system_info_set_changed_cb()
 131  * @see system_info_get_value_int(SYSTEM_INFO_KEY_BATTERY_PERCENTAGE, ...)
 132  * @see system_info_get_value_int(SYSTEM_INFO_KEY_BATTERY_CHARGE, ...)
 133  */
 134 int device_battery_is_full(bool *full);
 135
 136 /**
 137  * @brief Gets the number of display devices.
 138  *
 139  * @return The number of display devices that the device provides.
 140  * @retval #DEVICE_ERROR_NONE                           Successful
 141  * @retval #DEVICE_ERROR_INVALID_PARAMETER      Invalid parameter
 142  *
 143  * @see device_get_brightness()
 144  * @see device_set_brightness()
 145  * @see device_get_max_brightness()
 146  */
 147 int device_get_display_numbers(int* device_number);
 148
 149 /**
 150  * @brief Gets the display brightness value.
 151  *
 152  * @param[in] display_index     The index of the display, it be greater than or equal to 0 and less than \n
 153  *                          the number of displays returned by device_get_display_numbers().\n
 154  *                          The index zero is always assigned to the main display.
 155  * @param[out] brightness       The current brightness value of the display
 156  *
 157  * @return 0 on success, otherwise a negative error value.
 158  * @retval #DEVICE_ERROR_NONE                           Successful
 159  * @retval #DEVICE_ERROR_INVALID_PARAMETER      Invalid parameter
 160  * @retval #DEVICE_ERROR_OPERATION_FAILED       Operation failed
 161  *
 162  * @see device_get_display_numbers()
 163  * @see device_set_brightness()
 164  * @see device_get_max_brightness()
 165  */
 166 int device_get_brightness(int display_index, int *brightness);
 167
 168 /**
 169  * @brief Sets the display brightness value.
 170  *
 171  * @param[in] display_index     The index of the display, it be greater than or equal to 0 and less than \n
 172  *                          the number of displays returned by device_get_display_numbers().\n
 173  *                          The index zero is always assigned to the main display.
 174  * @param[in] brightness        The new brightness value to set \n
 175  *                                                      The maximum value can be represented by device_get_max_brightness()
 176  *
 177  * @return 0 on success, otherwise a negative error value.
 178  * @retval #DEVICE_ERROR_NONE                           Successful
 179  * @retval #DEVICE_ERROR_INVALID_PARAMETER  Invalid parameter
 180  * @retval #DEVICE_ERROR_OPERATION_FAILED   Operation failed
 181  *
 182  * @see device_get_display_numbers()
 183  * @see device_get_max_brightness()
 184  * @see device_get_brightness()
 185  */
 186 int device_set_brightness(int display_index, int brightness);
 187
 188 /**
 189  * @brief Gets the maximum brightness value that can be set.
 190  *
 191  * @param[in] display_index     The index of the display, it be greater than or equal to 0 and less than \n
 192  *                          the number of displays returned by device_get_display_numbers().\n
 193  *                          The index zero is always assigned to the main display.
 194  * @param[out] max_brightness   The maximum brightness value of the display
 195  *
 196  * @return 0 on success, otherwise a negative error value.
 197  * @retval #DEVICE_ERROR_NONE                           Successful
 198  * @retval #DEVICE_ERROR_INVALID_PARAMETER      Invalid parameter
 199  * @retval #DEVICE_ERROR_OPERATION_FAILED       Operation failed
 200  *
 201  * @see device_get_display_numbers()
 202  * @see device_set_brightness()
 203  * @see device_get_brightness()
 204  */
 205 int device_get_max_brightness(int display_index, int *max_brightness);
 206
 207 /**
 208  * @}
 209  */
 210
 211 #ifdef __cplusplus
 212 }
 213 #endif
 214
 215 #endif  // __TIZEN_SYSTEM_DEVICE_H__
 216