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.

Copyright (c) 2011 - 2015 Samsung Electronics Co., Ltd All Rights Reserved

Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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

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

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