include/runtime_info.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 #ifndef __TIZEN_SYSTEM_RUNTIME_INFO_H__
  18 #define __TIZEN_SYSTEM_RUNTIME_INFO_H__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27  /**
  28  * @addtogroup CAPI_SYSTEM_RUNTIME_INFO_MODULE
  29  * @{
  30  */
  31
  32 /**
  33  * @brief Enumeration for error codes for runtime information.
  34  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  35  */
  36 typedef enum {
  37         RUNTIME_INFO_ERROR_NONE = TIZEN_ERROR_NONE,                                                             /**< Successful */
  38         RUNTIME_INFO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  39         RUNTIME_INFO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,                   /**< Out of memory */
  40         RUNTIME_INFO_ERROR_IO_ERROR =  TIZEN_ERROR_IO_ERROR,                                    /**< An input/output error occurred when read value from system */
  41         RUNTIME_INFO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,   /**< No permission to use the api */
  42         RUNTIME_INFO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,                   /**< Not supported parameter @if MOBILE (Since 2.3.1) @endif */
  43 } runtime_info_error_e;
  44
  45 /**
  46  * @brief Enumeration for keys for runtime information.
  47  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  48  */
  49 typedef enum {
  50         RUNTIME_INFO_KEY_FLIGHT_MODE_ENABLED,                                   /**<@internal Indicates whether the device is in flight mode. */
  51         RUNTIME_INFO_KEY_WIFI_STATUS,                                                   /**<@internal Indicates the current status of Wi-Fi. */
  52         RUNTIME_INFO_KEY_BLUETOOTH_ENABLED,                                             /**<Indicates whether Bluetooth is enabled. */
  53         RUNTIME_INFO_KEY_WIFI_HOTSPOT_ENABLED,                                  /**<Indicates whether Wi-Fi hotspot is enabled. */
  54         RUNTIME_INFO_KEY_BLUETOOTH_TETHERING_ENABLED,                   /**<Indicates whether Bluetooth tethering is enabled. */
  55         RUNTIME_INFO_KEY_USB_TETHERING_ENABLED,                                 /**<Indicates whether USB tethering is enabled. */
  56         RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED,                              /**<Indicates whether the location service is allowed to use location data from GPS satellites. */
  57         RUNTIME_INFO_KEY_LOCATION_ADVANCED_GPS_ENABLED,                 /**<@internal Indicates whether the location service is allowed to download location data for GPS operation. */
  58         RUNTIME_INFO_KEY_LOCATION_NETWORK_POSITION_ENABLED,             /**<Indicates whether the location service is allowed to use location data from cellular and Wi-Fi. */
  59         RUNTIME_INFO_KEY_PACKET_DATA_ENABLED,                                   /**<Indicates Whether the packet data through 3G network is enabled. */
  60         RUNTIME_INFO_KEY_DATA_ROAMING_ENABLED,                                  /**<Indicates whether data roaming is enabled. */
  61         RUNTIME_INFO_KEY_SILENT_MODE_ENABLED,                                   /**<@internal Indicates whether the device is in silent mode. */
  62         RUNTIME_INFO_KEY_VIBRATION_ENABLED,                                             /**<Indicates whether vibration is enabled. */
  63         RUNTIME_INFO_KEY_24HOUR_CLOCK_FORMAT_ENABLED,                   /**<@internal Indicates whether 24-hour clock is enabled. */
  64         RUNTIME_INFO_KEY_FIRST_DAY_OF_WEEK,                                             /**<@internal Indicates the first day of week. */
  65         RUNTIME_INFO_KEY_LANGUAGE,                                                              /**<@internal Indicates the current language setting. */
  66         RUNTIME_INFO_KEY_REGION,                                                                /**<@internal Indicates the current region setting. */
  67         RUNTIME_INFO_KEY_AUDIO_JACK_CONNECTED,                                  /**<Indicates whether audio jack is connected. */
  68         RUNTIME_INFO_KEY_GPS_STATUS,                                                    /**<Indicates the current status of GPS. */
  69         RUNTIME_INFO_KEY_BATTERY_IS_CHARGING,                                   /**<Indicates the battery is currently charging. */
  70         RUNTIME_INFO_KEY_TV_OUT_CONNECTED,                                              /**<Indicates whether TV out is connected. */
  71         RUNTIME_INFO_KEY_AUDIO_JACK_STATUS,                                             /**<Indicates the current status of audio jack. */
  72         RUNTIME_INFO_KEY_SLIDING_KEYBOARD_OPENED,                               /**<@internal Indicates whether sliding keyboard is opened. */
  73         RUNTIME_INFO_KEY_USB_CONNECTED,                                                 /**<Indicates whether USB is connected. */
  74         RUNTIME_INFO_KEY_CHARGER_CONNECTED,                                             /**<Indicates whether charger is connected. */
  75         RUNTIME_INFO_KEY_VIBRATION_LEVEL_HAPTIC_FEEDBACK,               /**<@internal Indicates the current vibration level of haptic feedback. */
  76         RUNTIME_INFO_KEY_AUTO_ROTATION_ENABLED,                                 /**<Indicates whether auto rotation is enabled. */
  77 } runtime_info_key_e;
  78
  79
  80 /**
  81  * @internal
  82  * @brief Enumeration for Wi-Fi status.
  83  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  84  */
  85 typedef enum {
  86         RUNTIME_INFO_WIFI_STATUS_DISABLED,                              /**< @internal GPS is disabled. */
  87         RUNTIME_INFO_WIFI_STATUS_UNCONNECTED,                   /**< @internal Wi-Fi is enabled and network connection is not established. */
  88         RUNTIME_INFO_WIFI_STATUS_CONNECTED,                             /**< @internal Network connection is established in Wi-Fi network. */
  89 } runtime_info_wifi_status_e;
  90
  91 /**
  92  * @brief Enumeration for GPS status.
  93  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  94  */
  95 typedef enum {
  96         RUNTIME_INFO_GPS_STATUS_DISABLED,                               /**< GPS is disabled. */
  97         RUNTIME_INFO_GPS_STATUS_SEARCHING,                              /**< GPS is searching for satellites. */
  98         RUNTIME_INFO_GPS_STATUS_CONNECTED,                              /**< GPS connection is established. */
  99 } runtime_info_gps_status_e;
 100
 101 /**
 102  * @internal
 103  * @brief Enumeration for first day of week.
 104  */
 105 typedef enum {
 106         RUNTIME_INFO_FIRST_DAY_OF_WEEK_SUNDAY,                  /**< @internal Sunday */
 107         RUNTIME_INFO_FIRST_DAY_OF_WEEK_MONDAY,                  /**< @internal Monday */
 108         RUNTIME_INFO_FIRST_DAY_OF_WEEK_TUESDAY,                 /**< @internal Tuesday */
 109         RUNTIME_INFO_FIRST_DAY_OF_WEEK_WEDNESDAY,               /**< @internal Wednesday */
 110         RUNTIME_INFO_FIRST_DAY_OF_WEEK_THURSDAY,                /**< @internal Thursday */
 111         RUNTIME_INFO_FIRST_DAY_OF_WEEK_FRIDAY,                  /**< @internal Friday */
 112         RUNTIME_INFO_FIRST_DAY_OF_WEEK_SATURDAY,                /**< @internal Saturday */
 113 } runtime_info_first_day_of_week_e;
 114
 115 /**
 116  * @brief Enumeration for audio jack status.
 117  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 118  */
 119 typedef enum {
 120         RUNTIME_INFO_AUDIO_JACK_STATUS_UNCONNECTED,             /**< Audio jack is not connected */
 121         RUNTIME_INFO_AUDIO_JACK_STATUS_CONNECTED_3WIRE, /**< 3-conductor wire is connected. */
 122         RUNTIME_INFO_AUDIO_JACK_STATUS_CONNECTED_4WIRE, /**< 4-conductor wire is connected. */
 123 } runtime_info_audio_jack_status_e;
 124
 125
 126 /**
 127  * @brief   Called when the runtime information changes
 128  *
 129  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 130  *
 131  * @param[in] key       The type of notification
 132  * @param[in] user_data The user data passed from the callback registration function
 133  *
 134  * @pre runtime_info_set_changed_cb() will invoke this callback function.
 135  *
 136  * @see runtime_info_set_changed_cb()
 137  * @see runtime_info_unset_changed_cb()
 138  */
 139 typedef void (*runtime_info_changed_cb)(runtime_info_key_e key, void *user_data);
 140
 141 /**
 142  * @brief   Gets the integer value of the runtime information.
 143  * @details This function gets current state of the given key which represents specific runtime information.
 144  *
 145  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 146  *
 147  * @param[in]  key   The runtime information status key from which data should be read
 148  * @param[out] value The current value of the given key
 149  *
 150  * @return  @c 0 on success,
 151  *          otherwise a negative error value
 152  *
 153  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 154  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 155  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 156  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 157  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 158  */
 159 int runtime_info_get_value_int(runtime_info_key_e key, int *value);
 160
 161 /**
 162  * @brief   Gets the boolean value from the runtime information.
 163  * @details This function gets current state of the given key which represents specific runtime information.
 164  *
 165  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 166  *
 167  * @param[in]  key   The runtime information key from which data should be read
 168  * @param[out] value The current value of the given key
 169  *
 170  * @return  @c 0 on success,
 171  *          otherwise a negative error value
 172  *
 173  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 174  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 175  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 176  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 177  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 178  */
 179 int runtime_info_get_value_bool(runtime_info_key_e key, bool *value);
 180
 181 /**
 182  * @brief   Gets the double value from the runtime information.
 183  * @details This function gets current state of the given key which represents specific runtime information.
 184  *
 185  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 186  *
 187  * @param[in]  key   The runtime information key from which data should be read
 188  * @param[out] value The current value of the given key
 189  *
 190  * @return  @c 0 on success,
 191  *          otherwise a negative error value
 192  *
 193  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 194  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 195  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 196  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 197  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 198  */
 199 int runtime_info_get_value_double(runtime_info_key_e key, double *value);
 200
 201 /**
 202  * @brief   Gets the string value for specified runtime information.
 203  * @details This function gets current state of the given key which represents specific runtime information.
 204  *
 205  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 206  *
 207  * @remarks  You must release @a value using free().
 208  *
 209  * @param[in]  key   The runtime information key from which data should be read
 210  * @param[out] value The current value of the given key
 211  *
 212  * @return  @c 0 on success,
 213  *          otherwise a negative error value
 214  *
 215  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 216  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 217  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 218  * @retval  #RUNTIME_INFO_ERROR_OUT_OF_MEMORY     Out of memory
 219  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 220  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 221  */
 222 int runtime_info_get_value_string(runtime_info_key_e key, char **value);
 223
 224
 225 /**
 226  * @brief   Registers a change event callback for given runtime information key.
 227  *
 228  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 229  *
 230  * @param[in] key       The runtime information type
 231  * @param[in] callback  The callback function to invoke
 232  * @param[in] user_data The user data to be passed to the callback function
 233  *
 234  * @return  @c 0 on success,
 235  *          otherwise a negative error value
 236  *
 237  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 238  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 239  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 240  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 241  * @post runtime_info_changed_cb() will be invoked.
 242  *
 243  * @see runtime_info_unset_changed_cb()
 244  * @see runtime_info_changed_cb()
 245 */
 246 int runtime_info_set_changed_cb(runtime_info_key_e key, runtime_info_changed_cb callback, void *user_data);
 247
 248
 249 /**
 250  * @brief   Unregisters the callback function.
 251  *
 252  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 253  *
 254  * @param[in] key The runtime information type
 255  *
 256  * @return  @c 0 on success,
 257  *          otherwise a negative error value
 258  *
 259  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 260  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 261  *
 262  * @see runtime_info_set_changed_cb()
 263  */
 264 int runtime_info_unset_changed_cb(runtime_info_key_e key);
 265
 266 /**
 267  * @}
 268  */
 269
 270 #ifdef __cplusplus
 271 }
 272 #endif
 273
 274 #endif /* __TIZEN_SYSTEM_RUNTIME_INFO_H__ */