Tizen Native API  9.0
Runtime information

The Runtime Information API provides functions to obtain runtime information.

Required Header

#include <runtime_info.h>

Overview

The Runtime Information API provides functions to obtain runtime information, containing miscellaneous system preference. The Runtime Information available is stored in key/value pairs, where there may be different data types for the value. The runtime_info_set_changed_cb() registers a callback function for a particular key, which will be invoked by the System Service if the state matching that key changes.

Functions

int runtime_info_get_value_int (runtime_info_key_e key, int *value)
 Gets the integer value of the runtime information.
int runtime_info_get_value_bool (runtime_info_key_e key, bool *value)
 Gets the boolean value from the runtime information.
int runtime_info_get_value_double (runtime_info_key_e key, double *value)
 Gets the double value from the runtime information.
int runtime_info_get_value_string (runtime_info_key_e key, char **value)
 Gets the string value for specified runtime information.
int runtime_info_set_changed_cb (runtime_info_key_e key, runtime_info_changed_cb callback, void *user_data)
 Registers a change event callback for given runtime information key.
int runtime_info_unset_changed_cb (runtime_info_key_e key)
 Unregisters the callback function registered by runtime_info_set_changed_cb().
int runtime_info_get_system_memory_info (runtime_memory_info_s *info)
 Gets system memory information in the form of runtime_memory_info_s.
int runtime_info_get_process_memory_info (int *pid, int size, process_memory_info_s **info)
 Gets memory information per process in the form of process_memory_info_s.
int runtime_info_get_cpu_usage (runtime_cpu_usage_s *usage)
 Gets CPU usgae information in the form of runtime_cpu_usage_s.
int runtime_info_get_process_cpu_usage (int *pid, int size, process_cpu_usage_s **usage)
 Gets CPU usage in the form of process_cpu_usage_s.
int runtime_info_get_processor_count (int *num_core)
 Gets the total number of processors including both online and offline.
int runtime_info_get_processor_current_frequency (int core_idx, int *cpu_freq)
 Gets the current frequency of a specific processor.
int runtime_info_get_processor_max_frequency (int core_idx, int *cpu_freq)
 Gets the maximum frequency of a specific processor.
int runtime_info_get_physical_memory_size (int *size)
 Gets the total physical memory size in kibibyte(KiB).
int runtime_info_app_usage_destroy (app_usage_h handle)
 Destroy app_usage_h that won't be used anymore.
int runtime_info_app_usage_get_count (app_usage_h handle, int *count)
 Gets the number of applications that app_usage_h has retrieved.
int runtime_info_app_usage_get_appid (app_usage_h handle, int index, char **appid)
 Gets an application ID by index from an app_usage_h.
int runtime_info_app_usage_get_usage (app_usage_h handle, int index, unsigned int *usage)
 Gets resource usage of an application by index from an app_usage_h.
int runtime_info_get_all_apps_memory_usage (app_usage_h *usage)
 Gets memory usage of all applications in kilobyte into app_usage_h.
int runtime_info_get_all_apps_cpu_rate (app_usage_h *rate)
 Gets CPU rate of all applications in kilobyte into app_usage_h.

Typedefs

typedef void(* runtime_info_changed_cb )(runtime_info_key_e key, void *user_data)
 Called when the runtime information changes.
typedef struct app_usages_s * app_usage_h
 Handle for app usage information.

Typedef Documentation

typedef struct app_usages_s* app_usage_h

Handle for app usage information.

Since :
4.0
typedef void(* runtime_info_changed_cb)(runtime_info_key_e key, void *user_data)

Called when the runtime information changes.

Since :
2.3
Parameters:
[in]keyThe type of notification
[in]user_dataThe user data passed from the callback registration function
Precondition:
runtime_info_set_changed_cb() will invoke this callback function.
See also:
runtime_info_set_changed_cb()
runtime_info_unset_changed_cb()

Enumeration Type Documentation

Enumeration for audio jack status.

Since :
2.3
Enumerator:
RUNTIME_INFO_AUDIO_JACK_STATUS_UNCONNECTED 

Audio jack is not connected

RUNTIME_INFO_AUDIO_JACK_STATUS_CONNECTED_3WIRE 

3-conductor wire is connected.

RUNTIME_INFO_AUDIO_JACK_STATUS_CONNECTED_4WIRE 

4-conductor wire is connected.

Enumeration for error codes for runtime information.

Since :
2.3
Enumerator:
RUNTIME_INFO_ERROR_NONE 

Successful

RUNTIME_INFO_ERROR_INVALID_PARAMETER 

Invalid parameter

RUNTIME_INFO_ERROR_OUT_OF_MEMORY 

Out of memory

RUNTIME_INFO_ERROR_IO_ERROR 

An input/output error occurred when read value from system

RUNTIME_INFO_ERROR_REMOTE_IO 

Remote I/O error occurred

RUNTIME_INFO_ERROR_PERMISSION_DENIED 

No permission to use the api

RUNTIME_INFO_ERROR_NOT_SUPPORTED 

Not supported parameter

RUNTIME_INFO_ERROR_NO_DATA 

No data available (Since 3.0)

Enumeration for GPS status.

Since :
2.3
Enumerator:
RUNTIME_INFO_GPS_STATUS_DISABLED 

GPS is disabled.

RUNTIME_INFO_GPS_STATUS_SEARCHING 

GPS is searching for satellites.

RUNTIME_INFO_GPS_STATUS_CONNECTED 

GPS connection is established.

Enumeration for keys for runtime information.

Since :
2.3
Remarks:
~10000 : public key
10001~ : product specific key
Enumerator:
RUNTIME_INFO_KEY_BLUETOOTH_ENABLED 

Indicates whether Bluetooth is enabled.

RUNTIME_INFO_KEY_WIFI_HOTSPOT_ENABLED 

Indicates whether Wi-Fi hotspot is enabled.

RUNTIME_INFO_KEY_BLUETOOTH_TETHERING_ENABLED 

Indicates whether Bluetooth tethering is enabled.

RUNTIME_INFO_KEY_USB_TETHERING_ENABLED 

Indicates whether USB tethering is enabled.

RUNTIME_INFO_KEY_PACKET_DATA_ENABLED 

Indicates Whether the packet data through 3G network is enabled.

RUNTIME_INFO_KEY_DATA_ROAMING_ENABLED 

Indicates whether data roaming is enabled.

RUNTIME_INFO_KEY_VIBRATION_ENABLED 

Indicates whether vibration is enabled.

RUNTIME_INFO_KEY_AUDIO_JACK_CONNECTED 

Indicates whether audio jack is connected.

RUNTIME_INFO_KEY_GPS_STATUS 

Indicates the current status of GPS.

RUNTIME_INFO_KEY_BATTERY_IS_CHARGING 

Indicates the battery is currently charging.

RUNTIME_INFO_KEY_TV_OUT_CONNECTED 

Indicates whether TV out is connected.

RUNTIME_INFO_KEY_AUDIO_JACK_STATUS 

Indicates the current status of audio jack.

RUNTIME_INFO_KEY_USB_CONNECTED 

Indicates whether USB is connected.

RUNTIME_INFO_KEY_CHARGER_CONNECTED 

Indicates whether charger is connected.

RUNTIME_INFO_KEY_AUTO_ROTATION_ENABLED 

Indicates whether auto rotation is enabled.

Enumeration for Wi-Fi status.

Since :
2.3
Enumerator:
RUNTIME_INFO_WIFI_STATUS_DISABLED 

Wi-Fi is disabled.

RUNTIME_INFO_WIFI_STATUS_UNCONNECTED 

Wi-Fi is enabled and network connection is not established.

RUNTIME_INFO_WIFI_STATUS_CONNECTED 

Network connection is established in Wi-Fi network.


Function Documentation

Destroy app_usage_h that won't be used anymore.

Destroy app_usage_h acquired by functions runtime_info_get_all_apps_memory_usage() or runtime_info_get_all_apps_cpu_rate().

Since :
4.0
Parameters:
[in]handleApp usage handle to free
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
See also:
runtime_info_get_all_apps_memory_usage()
runtime_info_get_all_apps_cpu_rate()
int runtime_info_app_usage_get_appid ( app_usage_h  handle,
int  index,
char **  appid 
)

Gets an application ID by index from an app_usage_h.

Gets only applications that are managed by Application Manager.

Since :
4.0
Remarks:
You must release appid using free().
Parameters:
[in]handleThe app usage handle
[in]indexThe index in the app list; should be between 0 and count - 1 (inclusive),
where count is provided by runtime_info_app_usage_get_count()
[out]appidThe app ID
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
See also:
runtime_info_get_all_apps_memory_usage()
runtime_info_get_all_apps_cpu_rate()
int runtime_info_app_usage_get_count ( app_usage_h  handle,
int *  count 
)

Gets the number of applications that app_usage_h has retrieved.

Gets only applications that are managed by Application Manager.

Since :
4.0
Parameters:
[in]handleThe app usage handle
[out]countThe number of apps on the app list
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
See also:
runtime_info_get_all_apps_memory_usage()
runtime_info_get_all_apps_cpu_rate()
int runtime_info_app_usage_get_usage ( app_usage_h  handle,
int  index,
unsigned int *  usage 
)

Gets resource usage of an application by index from an app_usage_h.

Counts memory that is exclusively used by an application. That is, it doesn't count shared memory of an application such as file or shared library, etc. Gets only applications that are managed by Application Manager.

Since :
4.0
Remarks:
The meaning of usage depends on which function was used to create handle.
Parameters:
[in]handleThe app usage handle
[in]indexThe index in the app list; should be between 0 and count - 1 (inclusive),
where count is provided by runtime_info_app_usage_get_count()
[out]usageResource usage
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
See also:
runtime_info_get_all_apps_memory_usage()
runtime_info_get_all_apps_cpu_rate()

Gets CPU rate of all applications in kilobyte into app_usage_h.

The information is collected from /proc/[pid]/stat. Gets only applications that are managed by Application Manager.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/systemmonitor
Remarks:
You must release rate using runtime_info_app_usage_destroy().
Parameters:
[out]rateAn array of each app's CPU usage rate (%), the values are rounded down.
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_OUT_OF_MEMORYNot able to allocate memory (for output param/other operations)
RUNTIME_INFO_ERROR_REMOTE_IOCall to resource daemon failed (dbus errors/resource daemon errors)
RUNTIME_INFO_ERROR_IO_ERRORAn I/O error during dbus message operations
RUNTIME_INFO_ERROR_PERMISSION_DENIEDProcess not authorized to request app usage info
RUNTIME_INFO_ERROR_NO_DATANo app running
 #include <runtime_info.h>

 void print_cpu_usage(void)
 {
     int i;
     int count;
     app_usage_h cpu_rate_handle;
     char *appid;
     unsigned int rate;

     runtime_info_get_all_apps_cpu_rate(&cpu_rate_handle);
     runtime_info_app_usage_get_count(cpu_rate_handle, &count);

     for (i = 0; i < count; i++) {
         runtime_info_app_usage_get_appid(cpu_rate_handle, i, &appid);
         runtime_info_app_usage_get_usage(cpu_rate_handle, i, &rate);
         printf("appid = %s, rate = %u %%\n", appid, rate);
         free(appid);
     }

     runtime_info_app_usage_destroy(cpu_rate_handle);

 }

Gets memory usage of all applications in kilobyte into app_usage_h.

Counts memory that is exclusively used by an application. That is, it doesn't count shared memory of an application such as file or shared library, etc. Gets only applications that are managed by Application Manager.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/systemmonitor
Remarks:
You must release usage using runtime_info_app_usage_destroy().
Parameters:
[out]usageAn array of each app's memory usage (KB)
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_OUT_OF_MEMORYNot able to allocate memory (for output param/other operations)
RUNTIME_INFO_ERROR_REMOTE_IOCall to resource daemon failed (dbus errors/resource daemon errors)
RUNTIME_INFO_ERROR_IO_ERRORAn I/O error during dbus message operations
RUNTIME_INFO_ERROR_PERMISSION_DENIEDProcess not authorized to request app usage info
RUNTIME_INFO_ERROR_NO_DATANo app running
 #include <runtime_info.h>

 void print_memory_usage(void)
 {
     int i;
     int count;
     app_usage_h mem_usage_handle;
     char *appid;
     unsigned int usage;

     runtime_info_get_all_apps_memory_usage(&mem_usage_handle);
     runtime_info_app_usage_get_count(mem_usage_handle, &count);

     for (i = 0; i < count; i++) {
         runtime_info_app_usage_get_appid(mem_usage_handle, i, &appid);
         runtime_info_app_usage_get_usage(mem_usage_handle, i, &usage);
         printf("appid = %s, usage = %u KB\n", appid, usage);
         free(appid);
     }

     runtime_info_app_usage_destroy(mem_usage_handle);

 }

Gets CPU usgae information in the form of runtime_cpu_usage_s.

The information is collected from /proc/stat.

Since :
2.4
Parameters:
[out]usageThe CPU usage structure
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn input/output error occurred while reading from system
See also:
runtime_info_get_process_cpu_usage()

Gets the total physical memory size in kibibyte(KiB).

The information is collected from /proc/zoneinfo.

Since :
4.0
Parameters:
[out]sizePhysical memory size (KiB)
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn I/O error occurred (during file open operation)
int runtime_info_get_process_cpu_usage ( int *  pid,
int  size,
process_cpu_usage_s **  usage 
)

Gets CPU usage in the form of process_cpu_usage_s.

The information is collected from /proc/[pid]/stat.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/systemmonitor
Remarks:
You must release s value using free().
The size of s is the same with size.
Parameters:
[in]pidThe process unique id array
[in]sizeThe size of pid array
[out]usageThe CPU usage structure array of the processes
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_OUT_OF_MEMORYNot able to allocate memory (for output param/other operations)
RUNTIME_INFO_ERROR_REMOTE_IOCall to resource daemon failed (dbus errors/resource daemon errors)
RUNTIME_INFO_ERROR_IO_ERRORAn I/O error occurred (during dbus message operations/other IO operations)
RUNTIME_INFO_ERROR_PERMISSION_DENIEDProcess not authorized to request process usage info
See also:
runtime_info_get_cpu_usage()
int runtime_info_get_process_memory_info ( int *  pid,
int  size,
process_memory_info_s **  info 
)

Gets memory information per process in the form of process_memory_info_s.

The information is collected from /proc/[pid]/stat and /proc/[pid]/smaps.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/systemmonitor
Remarks:
You must release s value using free().
The size of s is the same with size.
Parameters:
[in]pidThe process unique id array
[in]sizeThe size of pid array
[out]infoThe memory information structure array of the processes
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_OUT_OF_MEMORYNot able to allocate memory (for output param/other operations)
RUNTIME_INFO_ERROR_REMOTE_IOCall to resource daemon failed (dbus errors/resource daemon errors)
RUNTIME_INFO_ERROR_IO_ERRORAn I/O error during dbus message operations
RUNTIME_INFO_ERROR_PERMISSION_DENIEDProcess not authorized to request process usage info
See also:
runtime_info_get_system_memory_info()
int runtime_info_get_processor_count ( int *  num_core)

Gets the total number of processors including both online and offline.

The information is collected from /sys/devices/system/cpu/possible.

Since :
3.0
Parameters:
[out]num_coreThe number of whole processors
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn I/O error occurred (during file open operation)
int runtime_info_get_processor_current_frequency ( int  core_idx,
int *  cpu_freq 
)

Gets the current frequency of a specific processor.

The information is collected from /sys/devices/system/cpu/cpu[idx]/cpufreq/scaling_cur_freq.

Since :
3.0
Parameters:
[in]core_idxThe index (from 0) of CPU core that you want to know the frequency
[out]cpu_freqThe current frequency(MHz) of processor
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn I/O error occurred (during file open operation)
RUNTIME_INFO_ERROR_NO_DATANo data available (Since 3.0)
int runtime_info_get_processor_max_frequency ( int  core_idx,
int *  cpu_freq 
)

Gets the maximum frequency of a specific processor.

The information is collected from /sys/devices/system/cpu/cpu[idx]/cpufreq/scaling_max_freq.

Since :
3.0
Parameters:
[in]core_idxThe index (from 0) of CPU core that you want to know the frequency
[out]cpu_freqThe max frequency(MHz) of processor
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn I/O error occurred (during file open operation)
RUNTIME_INFO_ERROR_NO_DATANo data available (Since 3.0)

Gets system memory information in the form of runtime_memory_info_s.

The information is collected from /proc/meminfo.

Since :
2.4
Parameters:
[out]infoThe system memory information structure
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn Input/Output error occurred while reading from system
See also:
runtime_info_get_process_memory_info()
int runtime_info_get_value_bool ( runtime_info_key_e  key,
bool *  value 
)

Gets the boolean value from the runtime information.

This function gets current state of the given key which represents specific runtime information.

Since :
2.3
Parameters:
[in]keyThe runtime information key from which data should be read
[out]valueThe current value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn input/output error occurred when read value from system
RUNTIME_INFO_ERROR_PERMISSION_DENIEDNo permission to use the api
RUNTIME_INFO_ERROR_NOT_SUPPORTEDNot supported parameter
int runtime_info_get_value_double ( runtime_info_key_e  key,
double *  value 
)

Gets the double value from the runtime information.

This function gets current state of the given key which represents specific runtime information.

Since :
2.3
Parameters:
[in]keyThe runtime information key from which data should be read
[out]valueThe current value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn input/output error occurred when read value from system
RUNTIME_INFO_ERROR_PERMISSION_DENIEDNo permission to use the api
RUNTIME_INFO_ERROR_NOT_SUPPORTEDNot supported parameter
int runtime_info_get_value_int ( runtime_info_key_e  key,
int *  value 
)

Gets the integer value of the runtime information.

This function gets current state of the given key which represents specific runtime information.

Since :
2.3
Parameters:
[in]keyThe runtime information status key from which data should be read
[out]valueThe current value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn input/output error occurred when read value from system
RUNTIME_INFO_ERROR_PERMISSION_DENIEDNo permission to use the api
RUNTIME_INFO_ERROR_NOT_SUPPORTEDNot supported parameter
int runtime_info_get_value_string ( runtime_info_key_e  key,
char **  value 
)

Gets the string value for specified runtime information.

This function gets current state of the given key which represents specific runtime information.

Since :
2.3
Remarks:
You must release value using free().
Parameters:
[in]keyThe runtime information key from which data should be read
[out]valueThe current value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_IO_ERRORAn input/output error occurred when read value from system
RUNTIME_INFO_ERROR_OUT_OF_MEMORYOut of memory
RUNTIME_INFO_ERROR_PERMISSION_DENIEDNo permission to use the api
RUNTIME_INFO_ERROR_NOT_SUPPORTEDNot supported parameter
int runtime_info_set_changed_cb ( runtime_info_key_e  key,
runtime_info_changed_cb  callback,
void *  user_data 
)

Registers a change event callback for given runtime information key.

Only the last registered callback will be operational if it is called multiple times on a same key. That is, it replaces previously registered one, if any.

Since :
2.3
Remarks:
You must release callback using runtime_info_unset_changed_cb().
Parameters:
[in]keyThe runtime information type
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
RUNTIME_INFO_ERROR_PERMISSION_DENIEDNo permission to use the api
RUNTIME_INFO_ERROR_NOT_SUPPORTEDNot supported parameter
Postcondition:
runtime_info_changed_cb() will be invoked.
See also:
runtime_info_unset_changed_cb()
runtime_info_changed_cb()

Unregisters the callback function registered by runtime_info_set_changed_cb().

Unregisters the callback function registered by runtime_info_set_changed_cb() on the key.

Since :
2.3
Parameters:
[in]keyThe runtime information type
Returns:
0 on success, otherwise a negative error value
Return values:
RUNTIME_INFO_ERROR_NONESuccessful
RUNTIME_INFO_ERROR_INVALID_PARAMETERInvalid parameter
See also:
runtime_info_set_changed_cb()