include/runtime_info.h

   1 /*
   2  * Copyright (c) 2011 - 2015 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  */
  35 typedef enum {
  36         RUNTIME_INFO_ERROR_NONE = TIZEN_ERROR_NONE,                             /**< Successful */
  37         RUNTIME_INFO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  38         RUNTIME_INFO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,           /**< Out of memory */
  39         RUNTIME_INFO_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR,                     /**< An input/output error occurred when read value from system */
  40         RUNTIME_INFO_ERROR_REMOTE_IO = TIZEN_ERROR_REMOTE_IO,                   /**< Remote I/O error occured */
  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  */
  48 typedef enum {
  49         RUNTIME_INFO_KEY_FLIGHT_MODE_ENABLED,                                   /**<@internal Indicates whether the device is in flight mode. */
  50         RUNTIME_INFO_KEY_WIFI_STATUS,                                                   /**<@internal Indicates the current status of Wi-Fi. */
  51         RUNTIME_INFO_KEY_BLUETOOTH_ENABLED,                                             /**<Indicates whether Bluetooth is enabled. */
  52         RUNTIME_INFO_KEY_WIFI_HOTSPOT_ENABLED,                                  /**<Indicates whether Wi-Fi hotspot is enabled. */
  53         RUNTIME_INFO_KEY_BLUETOOTH_TETHERING_ENABLED,                   /**<Indicates whether Bluetooth tethering is enabled. */
  54         RUNTIME_INFO_KEY_USB_TETHERING_ENABLED,                                 /**<Indicates whether USB tethering is enabled. */
  55         RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED,                              /**<Indicates whether the location service is allowed to use location data from GPS satellites. */
  56         RUNTIME_INFO_KEY_LOCATION_ADVANCED_GPS_ENABLED,                 /**<@internal Indicates whether the location service is allowed to download location data for GPS operation. */
  57         RUNTIME_INFO_KEY_LOCATION_NETWORK_POSITION_ENABLED,             /**<Indicates whether the location service is allowed to use location data from cellular and Wi-Fi. */
  58         RUNTIME_INFO_KEY_PACKET_DATA_ENABLED,                                   /**<Indicates Whether the packet data through 3G network is enabled. */
  59         RUNTIME_INFO_KEY_DATA_ROAMING_ENABLED,                                  /**<Indicates whether data roaming is enabled. */
  60         RUNTIME_INFO_KEY_SILENT_MODE_ENABLED,                                   /**<@internal Indicates whether the device is in silent mode. */
  61         RUNTIME_INFO_KEY_VIBRATION_ENABLED,                                             /**<Indicates whether vibration is enabled. */
  62         RUNTIME_INFO_KEY_24HOUR_CLOCK_FORMAT_ENABLED,                   /**<@internal Indicates whether 24-hour clock is enabled. */
  63         RUNTIME_INFO_KEY_FIRST_DAY_OF_WEEK,                                             /**<@internal Indicates the first day of week. */
  64         RUNTIME_INFO_KEY_LANGUAGE,                                                              /**<@internal Indicates the current language setting. */
  65         RUNTIME_INFO_KEY_REGION,                                                                /**<@internal Indicates the current region setting. */
  66         RUNTIME_INFO_KEY_AUDIO_JACK_CONNECTED,                                  /**<Indicates whether audio jack is connected. */
  67         RUNTIME_INFO_KEY_GPS_STATUS,                                                    /**<Indicates the current status of GPS. */
  68         RUNTIME_INFO_KEY_BATTERY_IS_CHARGING,                                   /**<Indicates the battery is currently charging. */
  69         RUNTIME_INFO_KEY_TV_OUT_CONNECTED,                                              /**<Indicates whether TV out is connected. */
  70         RUNTIME_INFO_KEY_AUDIO_JACK_STATUS,                                             /**<Indicates the current status of audio jack. */
  71         RUNTIME_INFO_KEY_SLIDING_KEYBOARD_OPENED,                               /**<@internal Indicates whether sliding keyboard is opened. */
  72         RUNTIME_INFO_KEY_USB_CONNECTED,                                                 /**<Indicates whether USB is connected. */
  73         RUNTIME_INFO_KEY_CHARGER_CONNECTED,                                             /**<Indicates whether charger is connected. */
  74         RUNTIME_INFO_KEY_VIBRATION_LEVEL_HAPTIC_FEEDBACK,               /**<@internal Indicates the current vibration level of haptic feedback. */
  75         RUNTIME_INFO_KEY_AUTO_ROTATION_ENABLED,                                 /**<Indicates whether auto rotation is enabled. */
  76 } runtime_info_key_e;
  77
  78
  79 /**
  80  * @brief Enumeration for Wi-Fi status.
  81  */
  82 typedef enum {
  83         RUNTIME_INFO_WIFI_STATUS_DISABLED,                              /**< GPS is disabled. */
  84         RUNTIME_INFO_WIFI_STATUS_UNCONNECTED,                   /**< Wi-Fi is enabled and network connection is not established. */
  85         RUNTIME_INFO_WIFI_STATUS_CONNECTED,                             /**< Network connection is established in Wi-Fi network. */
  86 } runtime_info_wifi_status_e;
  87
  88 /**
  89  * @brief Enumeration for GPS status.
  90  */
  91 typedef enum {
  92         RUNTIME_INFO_GPS_STATUS_DISABLED,                               /**< GPS is disabled. */
  93         RUNTIME_INFO_GPS_STATUS_SEARCHING,                              /**< GPS is searching for satellites. */
  94         RUNTIME_INFO_GPS_STATUS_CONNECTED,                              /**< GPS connection is established. */
  95 } runtime_info_gps_status_e;
  96
  97 /**
  98  * @internal
  99  * @brief Enumeration for first day of week.
 100  */
 101 typedef enum {
 102         RUNTIME_INFO_FIRST_DAY_OF_WEEK_SUNDAY,                  /**< Sunday */
 103         RUNTIME_INFO_FIRST_DAY_OF_WEEK_MONDAY,                  /**< Monday */
 104         RUNTIME_INFO_FIRST_DAY_OF_WEEK_TUESDAY,                 /**< Tuesday */
 105         RUNTIME_INFO_FIRST_DAY_OF_WEEK_WEDNESDAY,               /**< Wednesday */
 106         RUNTIME_INFO_FIRST_DAY_OF_WEEK_THURSDAY,                /**< Thursday */
 107         RUNTIME_INFO_FIRST_DAY_OF_WEEK_FRIDAY,                  /**< Friday */
 108         RUNTIME_INFO_FIRST_DAY_OF_WEEK_SATURDAY,                /**< Saturday */
 109 } runtime_info_first_day_of_week_e;
 110
 111 /**
 112  * @brief Enumeration for audio jack status.
 113  */
 114 typedef enum {
 115         RUNTIME_INFO_AUDIO_JACK_STATUS_UNCONNECTED,             /**< Audio jack is not connected */
 116         RUNTIME_INFO_AUDIO_JACK_STATUS_CONNECTED_3WIRE, /**< 3-conductor wire is connected. */
 117         RUNTIME_INFO_AUDIO_JACK_STATUS_CONNECTED_4WIRE, /**< 4-conductor wire is connected. */
 118 } runtime_info_audio_jack_status_e;
 119
 120
 121 /**
 122  * @brief   Called when the runtime information changes
 123  * @since_tizen 2.3
 124  *
 125  * @param[in] key       The type of notification
 126  * @param[in] user_data The user data passed from the callback registration function
 127  *
 128  * @pre runtime_info_set_changed_cb() will invoke this callback function.
 129  *
 130  * @see runtime_info_set_changed_cb()
 131  * @see runtime_info_unset_changed_cb()
 132  */
 133 typedef void (*runtime_info_changed_cb)(runtime_info_key_e key, void *user_data);
 134
 135 /**
 136  * @brief   Gets the integer value of the runtime information.
 137  * @details This function gets current state of the given key which represents specific runtime information.
 138  *
 139  * @since_tizen 2.3
 140  *
 141  * @param[in]  key   The runtime information status key from which data should be read
 142  * @param[out] value The current value of the given key
 143  *
 144  * @return  @c 0 on success,
 145  *          otherwise a negative error value
 146  *
 147  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 148  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 149  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 150  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 151  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 152  */
 153 int runtime_info_get_value_int(runtime_info_key_e key, int *value);
 154
 155 /**
 156  * @brief   Gets the boolean value from the runtime information.
 157  * @details This function gets current state of the given key which represents specific runtime information.
 158  *
 159  * @since_tizen 2.3
 160  *
 161  * @param[in]  key   The runtime information key from which data should be read
 162  * @param[out] value The current value of the given key
 163  *
 164  * @return  @c 0 on success,
 165  *          otherwise a negative error value
 166  *
 167  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 168  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 169  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 170  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 171  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 172  */
 173 int runtime_info_get_value_bool(runtime_info_key_e key, bool *value);
 174
 175 /**
 176  * @brief   Gets the double value from the runtime information.
 177  * @details This function gets current state of the given key which represents specific runtime information.
 178  *
 179  * @since_tizen 2.3
 180  *
 181  * @param[in]  key   The runtime information key from which data should be read
 182  * @param[out] value The current value of the given key
 183  *
 184  * @return  @c 0 on success,
 185  *          otherwise a negative error value
 186  *
 187  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 188  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 189  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 190  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 191  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 192  */
 193 int runtime_info_get_value_double(runtime_info_key_e key, double *value);
 194
 195 /**
 196  * @brief   Gets the string value for specified runtime information.
 197  * @details This function gets current state of the given key which represents specific runtime information.
 198  *
 199  * @since_tizen 2.3
 200  *
 201  * @remarks  You must release @a value using free().
 202  *
 203  * @param[in]  key   The runtime information key from which data should be read
 204  * @param[out] value The current value of the given key
 205  *
 206  * @return  @c 0 on success,
 207  *          otherwise a negative error value
 208  *
 209  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 210  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 211  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 212  * @retval  #RUNTIME_INFO_ERROR_OUT_OF_MEMORY     Out of memory
 213  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 214  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 215  */
 216 int runtime_info_get_value_string(runtime_info_key_e key, char **value);
 217
 218
 219 /**
 220  * @brief   Registers a change event callback for given runtime information key.
 221  * @since_tizen 2.3
 222  *
 223  * @param[in] key       The runtime information type
 224  * @param[in] callback  The callback function to invoke
 225  * @param[in] user_data The user data to be passed to the callback function
 226  *
 227  * @return  @c 0 on success,
 228  *          otherwise a negative error value
 229  *
 230  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 231  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 232  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 233  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter @if MOBILE (Since 2.3.1) @endif
 234  * @post runtime_info_changed_cb() will be invoked.
 235  *
 236  * @see runtime_info_unset_changed_cb()
 237  * @see runtime_info_changed_cb()
 238 */
 239 int runtime_info_set_changed_cb(runtime_info_key_e key, runtime_info_changed_cb callback, void *user_data);
 240
 241
 242 /**
 243  * @brief   Unregisters the callback function.
 244  * @since_tizen 2.3
 245  *
 246  * @param[in] key The runtime information type
 247  *
 248  * @return  @c 0 on success,
 249  *          otherwise a negative error value
 250  *
 251  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 252  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 253  *
 254  * @see runtime_info_set_changed_cb()
 255  */
 256 int runtime_info_unset_changed_cb(runtime_info_key_e key);
 257
 258 /**
 259  * @brief Structure for memory information.
 260  * @since_tizen 2.4
 261  */
 262 typedef struct {
 263         int total;  /**< Total memory (KiB) */
 264         int used;   /**< Used memory (KiB) */
 265         int free;   /**< Free memory (KiB) */
 266         int cache;  /**< Cache memory (KiB) */
 267         int swap;   /**< Swap memory (KiB) */
 268 } runtime_memory_info_s;
 269
 270 /**
 271  * @brief   Gets system memory information
 272  * @since_tizen 2.4
 273  *
 274  * @param[out] info The system memory information structure
 275  *
 276  * @return  @c 0 on success,
 277  *          otherwise a negative error value
 278  *
 279  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 280  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 281  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An Input/Output error occured while reading from system
 282  *
 283  * @see runtime_info_get_process_memory_info()
 284  */
 285 int runtime_info_get_system_memory_info(runtime_memory_info_s *info);
 286
 287 /**
 288  * @brief Structure for memory information per processes.
 289  * @since_tizen 2.4
 290  */
 291 typedef struct {
 292         int vsz;            /**< Virtual memory size (KiB) */
 293         int rss;            /**< Resident set size (KiB) */
 294         int pss;            /**< Proportional set size (KiB) */
 295         int shared_clean;   /**< Not modified and mapped by other processes (KiB) */
 296         int shared_dirty;   /**< Modified and mapped by other processes (KiB) */
 297         int private_clean;  /**< Not modified and available only to that process (KiB) */
 298         int private_dirty;  /**< Modified and available only to that process (KiB) */
 299 } process_memory_info_s;
 300
 301 /**
 302  * @brief   Gets memory information per processes
 303  * @since_tizen 2.4
 304  * @privlevel public
 305  * @privilege %http://tizen.org/privilege/systemmonitor
 306  *
 307  * @remarks You must release @a s value using free(). \n
 308  *          The size of @a s is the same with @a size.
 309  *
 310  * @param[in]  pid The process unique id array
 311  * @param[in]  size The size of pid array
 312  * @param[out] info The memory information structure array of the processes
 313  *
 314  * @return  @c 0 on success,
 315  *          otherwise a negative error value
 316  *
 317  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 318  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 319  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED Permission denied
 320  *
 321  * @see runtime_info_get_system_memory_info()
 322  */
 323 int runtime_info_get_process_memory_info(int *pid, int size, process_memory_info_s **info);
 324
 325 /**
 326  * @brief Structure for cpu usage.
 327  * @since_tizen 2.4
 328  */
 329 typedef struct {
 330         double user;   /**< Time running un-niced user processes (Percent) */
 331         double system; /**< Time running kernel processes (Percent) */
 332         double nice;   /**< Time running niced user processes (Percent) */
 333         double iowait; /**< Time waiting for I/O completion (Percent) */
 334 } runtime_cpu_usage_s;
 335
 336 /**
 337  * @brief   Gets cpu information
 338  * @since_tizen 2.4
 339  *
 340  * @param[out] usage The cpu usage structure
 341  *
 342  * @return  @c 0 on success,
 343  *          otherwise a negative error value
 344  *
 345  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 346  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 347  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occured while reading from system
 348  *
 349  * @see runtime_info_get_process_cpu_usage()
 350  */
 351 int runtime_info_get_cpu_usage(runtime_cpu_usage_s *usage);
 352
 353 /**
 354  * @brief Structure for cpu usage per processes.
 355  * @since_tizen 2.4
 356  */
 357 typedef struct {
 358         int utime;    /**< Amount of time that this process has been scheduled in user mode (clock ticks) */
 359         int stime;    /**< Amount of time that this process has been scheduled in kernel mode (clock ticks) */
 360 } process_cpu_usage_s;
 361
 362 /**
 363  * @brief   Gets cpu usage per processes
 364  * @since_tizen 2.4
 365  * @privlevel public
 366  * @privilege %http://tizen.org/privilege/systemmonitor
 367  *
 368  * @remarks You must release @a s value using free(). \n
 369  *          The size of @a s is the same with @a size.
 370  *
 371  * @param[in]  pid The process unique id array
 372  * @param[in]  size The size of pid array
 373  * @param[out] usage The cpu usage structure array of the processes
 374  *
 375  * @return  @c 0 on success,
 376  *          otherwise a negative error value
 377  *
 378  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 379  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 380  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED Permission denied
 381  *
 382  * @see runtime_info_get_cpu_usage()
 383  */
 384 int runtime_info_get_process_cpu_usage(int *pid, int size, process_cpu_usage_s **usage);
 385
 386 /**
 387  * @}
 388  */
 389
 390 #ifdef __cplusplus
 391 }
 392 #endif
 393
 394 #endif /* __TIZEN_SYSTEM_RUNTIME_INFO_H__ */