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  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @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_REMOTE_IO = TIZEN_ERROR_REMOTE_IO,                   /**< Remote I/O error occured */
  42         RUNTIME_INFO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,   /**< No permission to use the api */
  43         RUNTIME_INFO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,                   /**< Not supported parameter */
  44         RUNTIME_INFO_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA /**< No data available (Since 3.0) */
  45 } runtime_info_error_e;
  46
  47 /**
  48  * @brief Enumeration for keys for runtime information..
  49  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  50  */
  51 typedef enum {
  52         RUNTIME_INFO_KEY_BLUETOOTH_ENABLED                                      = 2,    /**<Indicates whether Bluetooth is enabled. */
  53         RUNTIME_INFO_KEY_WIFI_HOTSPOT_ENABLED                           = 3,    /**<Indicates whether Wi-Fi hotspot is enabled. */
  54         RUNTIME_INFO_KEY_BLUETOOTH_TETHERING_ENABLED            = 4,    /**<Indicates whether Bluetooth tethering is enabled. */
  55         RUNTIME_INFO_KEY_USB_TETHERING_ENABLED                          = 5,    /**<Indicates whether USB tethering is enabled. */
  56         RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED                       = 6,    /**<Indicates whether the location service is allowed to use location data from GPS satellites. */
  57         RUNTIME_INFO_KEY_LOCATION_NETWORK_POSITION_ENABLED      = 8,    /**<Indicates whether the location service is allowed to use location data from cellular and Wi-Fi. */
  58         RUNTIME_INFO_KEY_PACKET_DATA_ENABLED                            = 9,    /**<Indicates Whether the packet data through 3G network is enabled. */
  59         RUNTIME_INFO_KEY_DATA_ROAMING_ENABLED                           = 10,   /**<Indicates whether data roaming is enabled. */
  60         RUNTIME_INFO_KEY_VIBRATION_ENABLED                                      = 12,   /**<Indicates whether vibration is enabled. */
  61         RUNTIME_INFO_KEY_AUDIO_JACK_CONNECTED                           = 17,   /**<Indicates whether audio jack is connected. */
  62         RUNTIME_INFO_KEY_GPS_STATUS                                                     = 18,   /**<Indicates the current status of GPS. */
  63         RUNTIME_INFO_KEY_BATTERY_IS_CHARGING                            = 19,   /**<Indicates the battery is currently charging. */
  64         RUNTIME_INFO_KEY_TV_OUT_CONNECTED                                       = 20,   /**<Indicates whether TV out is connected. */
  65         RUNTIME_INFO_KEY_AUDIO_JACK_STATUS                                      = 21,   /**<Indicates the current status of audio jack. */
  66         RUNTIME_INFO_KEY_USB_CONNECTED                                          = 23,   /**<Indicates whether USB is connected. */
  67         RUNTIME_INFO_KEY_CHARGER_CONNECTED                                      = 24,   /**<Indicates whether charger is connected. */
  68         RUNTIME_INFO_KEY_AUTO_ROTATION_ENABLED                          = 26,   /**<Indicates whether auto rotation is enabled. */
  69 } runtime_info_key_e;
  70
  71
  72 /**
  73  * @brief Enumeration for Wi-Fi status.
  74  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  75  */
  76 typedef enum {
  77         RUNTIME_INFO_WIFI_STATUS_DISABLED,                              /**< GPS is disabled. */
  78         RUNTIME_INFO_WIFI_STATUS_UNCONNECTED,                   /**< Wi-Fi is enabled and network connection is not established. */
  79         RUNTIME_INFO_WIFI_STATUS_CONNECTED,                             /**< Network connection is established in Wi-Fi network. */
  80 } runtime_info_wifi_status_e;
  81
  82 /**
  83  * @brief Enumeration for GPS status.
  84  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  85  */
  86 typedef enum {
  87         RUNTIME_INFO_GPS_STATUS_DISABLED,                               /**< GPS is disabled. */
  88         RUNTIME_INFO_GPS_STATUS_SEARCHING,                              /**< GPS is searching for satellites. */
  89         RUNTIME_INFO_GPS_STATUS_CONNECTED,                              /**< GPS connection is established. */
  90 } runtime_info_gps_status_e;
  91
  92 /**
  93  * @brief Enumeration for audio jack status.
  94  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  95  */
  96 typedef enum {
  97         RUNTIME_INFO_AUDIO_JACK_STATUS_UNCONNECTED,             /**< Audio jack is not connected */
  98         RUNTIME_INFO_AUDIO_JACK_STATUS_CONNECTED_3WIRE, /**< 3-conductor wire is connected. */
  99         RUNTIME_INFO_AUDIO_JACK_STATUS_CONNECTED_4WIRE, /**< 4-conductor wire is connected. */
 100 } runtime_info_audio_jack_status_e;
 101
 102
 103 /**
 104  * @brief   Called when the runtime information changes
 105  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
 106  *
 107  * @param[in] key       The type of notification
 108  * @param[in] user_data The user data passed from the callback registration function
 109  *
 110  * @pre runtime_info_set_changed_cb() will invoke this callback function.
 111  *
 112  * @see runtime_info_set_changed_cb()
 113  * @see runtime_info_unset_changed_cb()
 114  */
 115 typedef void (*runtime_info_changed_cb)(runtime_info_key_e key, void *user_data);
 116
 117 /**
 118  * @brief   Gets the integer value of the runtime information.
 119  * @details This function gets current state of the given key which represents specific runtime information.
 120  *
 121  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
 122  *
 123  * @param[in]  key   The runtime information status key from which data should be read
 124  * @param[out] value The current value of the given key
 125  *
 126  * @return  @c 0 on success,
 127  *          otherwise a negative error value
 128  *
 129  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 130  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 131  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 132  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 133  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter
 134  */
 135 int runtime_info_get_value_int(runtime_info_key_e key, int *value);
 136
 137 /**
 138  * @brief   Gets the boolean value from the runtime information.
 139  * @details This function gets current state of the given key which represents specific runtime information.
 140  *
 141  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
 142  *
 143  * @param[in]  key   The runtime information key from which data should be read
 144  * @param[out] value The current value of the given key
 145  *
 146  * @return  @c 0 on success,
 147  *          otherwise a negative error value
 148  *
 149  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 150  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 151  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 152  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 153  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter
 154  */
 155 int runtime_info_get_value_bool(runtime_info_key_e key, bool *value);
 156
 157 /**
 158  * @brief   Gets the double value from the runtime information.
 159  * @details This function gets current state of the given key which represents specific runtime information.
 160  *
 161  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
 162  *
 163  * @param[in]  key   The runtime information key from which data should be read
 164  * @param[out] value The current value of the given key
 165  *
 166  * @return  @c 0 on success,
 167  *          otherwise a negative error value
 168  *
 169  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 170  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 171  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 172  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 173  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter
 174  */
 175 int runtime_info_get_value_double(runtime_info_key_e key, double *value);
 176
 177 /**
 178  * @brief   Gets the string value for specified runtime information.
 179  * @details This function gets current state of the given key which represents specific runtime information.
 180  *
 181  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
 182  *
 183  * @remarks  You must release @a value using free().
 184  *
 185  * @param[in]  key   The runtime information key from which data should be read
 186  * @param[out] value The current value of the given key
 187  *
 188  * @return  @c 0 on success,
 189  *          otherwise a negative error value
 190  *
 191  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 192  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 193  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occurred when read value from system
 194  * @retval  #RUNTIME_INFO_ERROR_OUT_OF_MEMORY     Out of memory
 195  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 196  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter
 197  */
 198 int runtime_info_get_value_string(runtime_info_key_e key, char **value);
 199
 200
 201 /**
 202  * @brief   Registers a change event callback for given runtime information key.
 203  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
 204  *
 205  * @param[in] key       The runtime information type
 206  * @param[in] callback  The callback function to invoke
 207  * @param[in] user_data The user data to be passed to the callback function
 208  *
 209  * @return  @c 0 on success,
 210  *          otherwise a negative error value
 211  *
 212  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 213  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 214  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED No permission to use the api
 215  * @retval  #RUNTIME_INFO_ERROR_NOT_SUPPORTED     Not supported parameter
 216  * @post runtime_info_changed_cb() will be invoked.
 217  *
 218  * @see runtime_info_unset_changed_cb()
 219  * @see runtime_info_changed_cb()
 220 */
 221 int runtime_info_set_changed_cb(runtime_info_key_e key, runtime_info_changed_cb callback, void *user_data);
 222
 223
 224 /**
 225  * @brief   Unregisters the callback function.
 226  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
 227  *
 228  * @param[in] key The runtime information type
 229  *
 230  * @return  @c 0 on success,
 231  *          otherwise a negative error value
 232  *
 233  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 234  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 235  *
 236  * @see runtime_info_set_changed_cb()
 237  */
 238 int runtime_info_unset_changed_cb(runtime_info_key_e key);
 239
 240 /**
 241  * @brief Structure for memory information.
 242  * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
 243  */
 244 typedef struct {
 245         int total;  /**< Total memory (KiB) */
 246         int used;   /**< Used memory (KiB) */
 247         int free;   /**< Free memory (KiB) */
 248         int cache;  /**< Cache memory (KiB) */
 249         int swap;   /**< Swap memory (KiB) */
 250 } runtime_memory_info_s;
 251
 252 /**
 253  * @brief   Gets system memory information
 254  * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
 255  *
 256  * @param[out] info The system memory information structure
 257  *
 258  * @return  @c 0 on success,
 259  *          otherwise a negative error value
 260  *
 261  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 262  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 263  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An Input/Output error occured while reading from system
 264  *
 265  * @see runtime_info_get_process_memory_info()
 266  */
 267 int runtime_info_get_system_memory_info(runtime_memory_info_s *info);
 268
 269 /**
 270  * @brief Structure for memory information per processes.
 271  * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
 272  */
 273 typedef struct {
 274         int vsz;            /**< Virtual memory size (KiB) */
 275         int rss;            /**< Resident set size (KiB) */
 276         int pss;            /**< Proportional set size (KiB) */
 277         int shared_clean;   /**< Not modified and mapped by other processes (KiB) */
 278         int shared_dirty;   /**< Modified and mapped by other processes (KiB) */
 279         int private_clean;  /**< Not modified and available only to that process (KiB) */
 280         int private_dirty;  /**< Modified and available only to that process (KiB) */
 281 } process_memory_info_s;
 282
 283 /**
 284  * @brief   Gets memory information per processes
 285  * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
 286  * @privlevel public
 287  * @privilege %http://tizen.org/privilege/systemmonitor
 288  *
 289  * @remarks You must release @a s value using free(). \n
 290  *          The size of @a s is the same with @a size.
 291  *
 292  * @param[in]  pid The process unique id array
 293  * @param[in]  size The size of pid array
 294  * @param[out] info The memory information structure array of the processes
 295  *
 296  * @return  @c 0 on success,
 297  *          otherwise a negative error value
 298  *
 299  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 300  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 301  * @retval  #RUNTIME_INFO_ERROR_OUT_OF_MEMORY     Not able to allocate memory (for output param/other operations)
 302  * @retval  #RUNTIME_INFO_ERROR_REMOTE_IO         Call to resource daemon failed (dbus errors/resource daemon errors)
 303  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An I/O error during dbus message operations
 304  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED Process not authorized to request process usage info
 305  *
 306  * @see runtime_info_get_system_memory_info()
 307  */
 308 int runtime_info_get_process_memory_info(int *pid, int size, process_memory_info_s **info);
 309
 310 /**
 311  * @brief Structure for cpu usage.
 312  * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
 313  */
 314 typedef struct {
 315         double user;   /**< Time running un-niced user processes (Percent) */
 316         double system; /**< Time running kernel processes (Percent) */
 317         double nice;   /**< Time running niced user processes (Percent) */
 318         double iowait; /**< Time waiting for I/O completion (Percent) */
 319 } runtime_cpu_usage_s;
 320
 321 /**
 322  * @brief   Gets cpu information
 323  * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
 324  *
 325  * @param[out] usage The cpu usage structure
 326  *
 327  * @return  @c 0 on success,
 328  *          otherwise a negative error value
 329  *
 330  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 331  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 332  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An input/output error occured while reading from system
 333  *
 334  * @see runtime_info_get_process_cpu_usage()
 335  */
 336 int runtime_info_get_cpu_usage(runtime_cpu_usage_s *usage);
 337
 338 /**
 339  * @brief Structure for cpu usage per processes.
 340  * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
 341  */
 342 typedef struct {
 343         int utime;    /**< Amount of time that this process has been scheduled in user mode (clock ticks) */
 344         int stime;    /**< Amount of time that this process has been scheduled in kernel mode (clock ticks) */
 345 } process_cpu_usage_s;
 346
 347 /**
 348  * @brief   Gets cpu usage per processes
 349  * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
 350  * @privlevel public
 351  * @privilege %http://tizen.org/privilege/systemmonitor
 352  *
 353  * @remarks You must release @a s value using free(). \n
 354  *          The size of @a s is the same with @a size.
 355  *
 356  * @param[in]  pid The process unique id array
 357  * @param[in]  size The size of pid array
 358  * @param[out] usage The cpu usage structure array of the processes
 359  *
 360  * @return  @c 0 on success,
 361  *          otherwise a negative error value
 362  *
 363  * @retval  #RUNTIME_INFO_ERROR_NONE              Successful
 364  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER Invalid parameter
 365  * @retval  #RUNTIME_INFO_ERROR_OUT_OF_MEMORY     Not able to allocate memory (for output param/other operations)
 366  * @retval  #RUNTIME_INFO_ERROR_REMOTE_IO         Call to resource daemon failed (dbus errors/resource daemon errors)
 367  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR          An I/O error occured (during dbus message operations/other IO operations)
 368  * @retval  #RUNTIME_INFO_ERROR_PERMISSION_DENIED Process not authorized to request process usage info
 369  *
 370  * @see runtime_info_get_cpu_usage()
 371  */
 372 int runtime_info_get_process_cpu_usage(int *pid, int size, process_cpu_usage_s **usage);
 373
 374 /**
 375  * @brief  Gets the number of processors
 376  * @since_tizen @if MOBILE 2.4 @else 3.0 @endif
 377  *
 378  * @param[out]  num_core The number of whole processors
 379  *
 380  * @retval  #RUNTIME_INFO_ERROR_NONE  Successful
 381  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER  Invalid parameter
 382  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR  An I/O error occurred (during file open operation)
 383  */
 384 int runtime_info_get_processor_count(int *num_core);
 385
 386 /**
 387  * @brief  Gets the current frequency of processor
 388  * @since_tizen @if MOBILE 2.4 @else 3.0 @endif
 389  *
 390  * @param[in]  core_idx The index (from 0) of CPU core that you want to know the frequency
 391  * @param[out]  cpu_freq The current frequency(MHz) of processor
 392  *
 393  * @retval  #RUNTIME_INFO_ERROR_NONE  Successful
 394  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER  Invalid parameter
 395  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR  An I/O error occurred (during file open operation)
 396  * @retval  #RUNTIME_INFO_ERROR_NO_DATA  No data available (Since 3.0)
 397  */
 398 int runtime_info_get_processor_current_frequency(int core_idx, int *cpu_freq);
 399
 400 /**
 401  * @brief  Gets the max frequency of processor
 402  * @since_tizen @if MOBILE 2.4 @else 3.0 @endif
 403  *
 404  * @param[in]  core_idx The index (from 0) of CPU core that you want to know the frequency
 405  * @param[out]  cpu_freq The max frequency(MHz) of processor
 406  *
 407  * @retval  #RUNTIME_INFO_ERROR_NONE  Successful
 408  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER  Invalid parameter
 409  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR  An I/O error occurred (during file open operation)
 410  * @retval  #RUNTIME_INFO_ERROR_NO_DATA  No data available (Since 3.0)
 411  */
 412 int runtime_info_get_processor_max_frequency(int core_idx, int *cpu_freq);
 413
 414 /**
 415  * @brief  Gets the physical memory size.
 416  * @since_tizen 4.0
 417  *
 418  * @param[out]  size Physical memory size (KiB)
 419  *
 420  * @retval  #RUNTIME_INFO_ERROR_NONE  Successful
 421  * @retval  #RUNTIME_INFO_ERROR_INVALID_PARAMETER  Invalid parameter
 422  * @retval  #RUNTIME_INFO_ERROR_IO_ERROR  An I/O error occurred (during file open operation)
 423  */
 424 int runtime_info_get_physical_memory_size(int *size);
 425
 426 /**
 427  * @}
 428  */
 429
 430 #ifdef __cplusplus
 431 }
 432 #endif
 433
 434 #endif /** __TIZEN_SYSTEM_RUNTIME_INFO_H__ */