Tizen Native API  5.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.
int runtime_info_get_system_memory_info (runtime_memory_info_s *info)
 Gets system memory information.
int runtime_info_get_process_memory_info (int *pid, int size, process_memory_info_s **info)
 Gets memory information per process.
int runtime_info_get_cpu_usage (runtime_cpu_usage_s *usage)
 Gets CPU information.
int runtime_info_get_process_cpu_usage (int *pid, int size, process_cpu_usage_s **usage)
 Gets CPU usage per process.
int runtime_info_get_processor_count (int *num_core)
 Gets the number of processors.
int runtime_info_get_processor_current_frequency (int core_idx, int *cpu_freq)
 Gets the current frequency of processor.
int runtime_info_get_processor_max_frequency (int core_idx, int *cpu_freq)
 Gets the max frequency of processor.
int runtime_info_get_physical_memory_size (int *size)
 Gets the physical memory size.
int runtime_info_app_usage_destroy (app_usage_h handle)
 Frees an app usage handle.
int runtime_info_app_usage_get_count (app_usage_h handle, int *count)
 Gets the app count from an app usage handle.
int runtime_info_app_usage_get_appid (app_usage_h handle, int index, char **appid)
 Gets the app ID from an app usage handle.
int runtime_info_app_usage_get_usage (app_usage_h handle, int index, unsigned int *usage)
 Gets resource usage from an app usage handle.
int runtime_info_get_all_apps_memory_usage (app_usage_h *usage)
 Gets memory usage of all apps.
int runtime_info_get_all_apps_cpu_rate (app_usage_h *rate)
 Gets CPU rate of all apps.

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.1
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.1
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.1
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.1
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.1
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_LOCATION_SERVICE_ENABLED 

Indicates whether the location service is allowed to use location data from GPS satellites. (Deprecated since 4.0)

RUNTIME_INFO_KEY_LOCATION_NETWORK_POSITION_ENABLED 

Indicates whether the location service is allowed to use location data from cellular and Wi-Fi. (Deprecated since 4.0)

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.1
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

Frees an app usage handle.

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
int runtime_info_app_usage_get_appid ( app_usage_h  handle,
int  index,
char **  appid 
)

Gets the app ID from an app usage handle.

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 app count from an app usage handle.

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 from an app usage handle.

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 apps.

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 apps.

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 information.

Since :
3.0
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 physical memory size.

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 per process.

Since :
3.0
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.

Since :
3.0
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 number of processors.

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 processor.

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 max frequency of processor.

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.

Since :
3.0
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.1
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.1
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.1
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.1
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.

Since :
2.3.1
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.

Since :
2.3.1
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()