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