Tizen Native API  3.0
Functions | Typedefs
System Settings
System

The System Settings API provides APIs for sharing configuration over a system. system_settings_key_e shows all of the supporting APIs in System-Settings.

Required Header

#include <system_settings.h>

Overview

System Settings API provides functions for getting the system configuration related to user preferences. The main features of the System Settings API include accessing system-wide configurations, such as ringtones, wallpapers, and etc.

For more information on feature, see System Settings Programming Guide.

Functions

int system_settings_set_value_int (system_settings_key_e key, int value)
 Sets the system settings value associated with the given key as an integer.
int system_settings_get_value_int (system_settings_key_e key, int *value)
 Gets the system settings value associated with the given key as an integer.
int system_settings_set_value_bool (system_settings_key_e key, bool value)
 Sets the system settings value associated with the given key as a boolean.
int system_settings_get_value_bool (system_settings_key_e key, bool *value)
 Gets the system settings value associated with the given key as a boolean.
int system_settings_set_value_string (system_settings_key_e key, const char *value)
 Sets the system settings value associated with the given key as a string.
int system_settings_get_value_string (system_settings_key_e key, char **value)
 Gets the system settings value associated with the given key as a string.
int system_settings_set_changed_cb (system_settings_key_e key, system_settings_changed_cb callback, void *user_data)
 Registers a change event callback for the given system settings key.
int system_settings_unset_changed_cb (system_settings_key_e key)
 Unregisters the callback function.
int system_settings_foreach_value_string (system_settings_key_e key, system_settings_iter_cb callback, void *user_value)
 Iterate the system settings value associated with the given key as a string type.
int system_settings_add_value_string (system_settings_key_e key, const char *value)
 Adds the system settings value associated with the given key as a string type if it supports List iteration.
int system_settings_delete_value_string (system_settings_key_e key, const char *value)
 Delete the system settings value associated with the given key as an string type if it supports List iteration.

Typedefs

typedef void(* system_settings_changed_cb )(system_settings_key_e key, void *user_data)
 Called when the system settings changes.
typedef bool(* system_settings_iter_cb )(int index, const char *value, void *cb_data)
 Called to get each string value from string typed list.

Typedef Documentation

typedef void(* system_settings_changed_cb)(system_settings_key_e key, void *user_data)

Called when the system settings changes.

Since :
2.3
Parameters:
[in]keyThe key name of the system settings changed system settings
[in]user_dataThe user data passed from the callback registration function
Precondition:
system_settings_set_changed_cb() will invoke this callback function.
See also:
system_settings_set_changed_cb()
system_settings_unset_changed_cb()
typedef bool(* system_settings_iter_cb)(int index, const char *value, void *cb_data)

Called to get each string value from string typed list.

Warning:
This is not for use by third-party applications.
Since :
3.0
Parameters:
[in]indexzero based number indicating index of node in a list
[in]valuevalue returned from the list
[in]cb_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop, otherwise false to break out of the loop

Enumeration Type Documentation

enum system_settings_error_e

Enumeration for system settings error.

Since :
2.3
Enumerator:
SYSTEM_SETTINGS_ERROR_NONE 

Successful

SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER 

Invalid parameter

SYSTEM_SETTINGS_ERROR_OUT_OF_MEMORY 

Out of memory

SYSTEM_SETTINGS_ERROR_IO_ERROR 

Internal I/O error

SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED 

Permission denied

SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED 

Not supported

SYSTEM_SETTINGS_ERROR_CALL_UNSUPPORTED_API 

Not supported

SYSTEM_SETTINGS_ERROR_LOCKSCREEN_APP_PASSWORD_MODE 

Current lock screen app set 'password' type

enum system_settings_font_size_e

Enumeration for font size.

Since :
2.3
Enumerator:
SYSTEM_SETTINGS_FONT_SIZE_SMALL 

A small size

SYSTEM_SETTINGS_FONT_SIZE_NORMAL 

A normal size

SYSTEM_SETTINGS_FONT_SIZE_LARGE 

A large size

SYSTEM_SETTINGS_FONT_SIZE_HUGE 

A huge size

SYSTEM_SETTINGS_FONT_SIZE_GIANT 

A giant size

enum system_settings_idle_lock_state_e

Enumeration for Idle Lock State.

Since :
2.3.1
Enumerator:
SYSTEM_SETTINGS_LOCK_STATE_UNLOCK 

Device is unlocked

SYSTEM_SETTINGS_LOCK_STATE_LOCK 

Device is locked

SYSTEM_SETTINGS_LOCK_STATE_LAUNCHING_LOCK 

Device is being locked

enum system_settings_key_e

Enumeration for System Settings Key.

Since :
2.3
Enumerator:
SYSTEM_SETTINGS_KEY_INCOMING_CALL_RINGTONE 

(string) The file path of the current ringtone

SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN 

(string) The file path of the current home screen wallpaper

SYSTEM_SETTINGS_KEY_WALLPAPER_LOCK_SCREEN 

(string) The file path of the current lock screen wallpaper

SYSTEM_SETTINGS_KEY_FONT_SIZE 

(int) The current system font size

SYSTEM_SETTINGS_KEY_FONT_TYPE 

(string) The current system font type

SYSTEM_SETTINGS_KEY_MOTION_ACTIVATION 

(bool) Indicates whether the motion service is activated

SYSTEM_SETTINGS_KEY_EMAIL_ALERT_RINGTONE 

(string) The file path of the current email alert ringtone

SYSTEM_SETTINGS_KEY_USB_DEBUGGING_ENABLED 

(bool) Indicates whether the USB debugging is enabled (Since 3.0)

SYSTEM_SETTINGS_KEY_3G_DATA_NETWORK_ENABLED 

bool) Indicates whether the 3G data network is enabled (Since 3.0)

SYSTEM_SETTINGS_KEY_LOCKSCREEN_APP 

(string) Indicates lockscreen app pkg name

SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE 

(string) The current system default font type (only support Get)

SYSTEM_SETTINGS_KEY_LOCALE_COUNTRY 

(string) Indicates the current country setting in the <LANGUAGE>_<REGION> syntax. The country setting is in the ISO 639-2 format, and the region setting is in the ISO 3166-1 alpha-2 format

SYSTEM_SETTINGS_KEY_LOCALE_LANGUAGE 

(string) Indicates the current language setting in the <LANGUAGE>_<REGION> syntax. The language setting is in the ISO 639-2 format and the region setting is in the ISO 3166-1 alpha-2 format.

SYSTEM_SETTINGS_KEY_LOCALE_TIMEFORMAT_24HOUR 

(bool) Indicates whether the 24-hour clock is used. If the value is false, the 12-hour clock is used.

SYSTEM_SETTINGS_KEY_LOCALE_TIMEZONE 

(string) Indicates the current time zone.

SYSTEM_SETTINGS_KEY_TIME_CHANGED 

(int) Once System changes time, this event occurs to notify time change.

SYSTEM_SETTINGS_KEY_SOUND_LOCK 

GET (bool) Indicates whether the screen lock sound is enabled on the device. ex) LCD on/off sound

SYSTEM_SETTINGS_KEY_SOUND_SILENT_MODE 

GET (bool) Indicates whether the device is in the silent mode.

SYSTEM_SETTINGS_KEY_SOUND_TOUCH 

GET (bool) Indicates whether the screen touch sound is enabled on the device.

SYSTEM_SETTINGS_KEY_DISPLAY_SCREEN_ROTATION_AUTO 

GET (bool) Indicates whether rotation control is automatic.

SYSTEM_SETTINGS_KEY_DEVICE_NAME 

GET (string) Indicates device name.

SYSTEM_SETTINGS_KEY_MOTION_ENABLED 

GET (bool) Indicates whether the device user has enabled the motion feature.

SYSTEM_SETTINGS_KEY_NETWORK_WIFI_NOTIFICATION 

GET (bool) Indicates whether Wi-Fi-related notifications are enabled on the device.

SYSTEM_SETTINGS_KEY_NETWORK_FLIGHT_MODE 

GET (bool) Indicates whether the device is in the flight mode.

SYSTEM_SETTINGS_KEY_SCREEN_BACKLIGHT_TIME 

(int) Indicates the backlight time (in seconds).

SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION 

(string) Indicates the file path of the current notification tone set by the user.

SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION_REPETITION_PERIOD 

(int) Indicates the time period for notification repetitions.

SYSTEM_SETTINGS_KEY_LOCK_STATE 

(int) Indicates the current lock state

SYSTEM_SETTINGS_KEY_ADS_ID 

(string) Indicates Ads ID for each device (Since 3.0)

Function Documentation

int system_settings_add_value_string ( system_settings_key_e  key,
const char *  value 
)

Adds the system settings value associated with the given key as a string type if it supports List iteration.

Warning:
This is not for use by third-party applications.
Since :
3.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/systemsettings.admin
Parameters:
[in]keyThe key name of the system settings
[in]valuestring typed value to be appended
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_IO_ERRORInternal I/O error
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
int system_settings_delete_value_string ( system_settings_key_e  key,
const char *  value 
)

Delete the system settings value associated with the given key as an string type if it supports List iteration.

Warning:
This is not for use by third-party applications.
Since :
3.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/systemsettings.admin
Parameters:
[in]keyThe key name of the system settings
[in]valuestring typed value to be removed
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_IO_ERRORInternal I/O error
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
int system_settings_foreach_value_string ( system_settings_key_e  key,
system_settings_iter_cb  callback,
void *  user_value 
)

Iterate the system settings value associated with the given key as a string type.

Warning:
This is not for use by third-party applications.
Since :
3.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/systemsettings.admin
Parameters:
[in]keyThe key name of the system settings
[in]callbackThe callback-function name for iteration
[in]user_dataThe user data passed from caller-side
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_IO_ERRORInternal I/O error
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
int system_settings_get_value_bool ( system_settings_key_e  key,
bool *  value 
)

Gets the system settings value associated with the given key as a boolean.

Since :
2.3
Parameters:
[in]keyThe key name of the system settings
[out]valueThe current system settings value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_IO_ERRORInternal I/O error
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
Warning:
http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this API since 2.3.1.
int system_settings_get_value_int ( system_settings_key_e  key,
int *  value 
)

Gets the system settings value associated with the given key as an integer.

Since :
2.3
Parameters:
[in]keyThe key name of the system settings
[out]valueThe current system settings value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_IO_ERRORInternal I/O error
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
Warning:
http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this API since 2.3.1.
int system_settings_get_value_string ( system_settings_key_e  key,
char **  value 
)

Gets the system settings value associated with the given key as a string.

Since :
2.3
Remarks:
You must release value using free().
Parameters:
[in]keyThe key name of the system settings
[out]valueThe current system settings value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_IO_ERRORInternal I/O error
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
Warning:
http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this API since 2.3.1.
int system_settings_set_changed_cb ( system_settings_key_e  key,
system_settings_changed_cb  callback,
void *  user_data 
)

Registers a change event callback for the given system settings key.

Since :
2.3
Remarks:
SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb.
Parameters:
[in]keyThe key name of the system settings
[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:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
Postcondition:
system_settings_changed_cb() will be invoked.
See also:
system_settings_unset_changed_cb()
system_settings_changed_cb()
Warning:
http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this API since 2.3.1.
int system_settings_set_value_bool ( system_settings_key_e  key,
bool  value 
)

Sets the system settings value associated with the given key as a boolean.

Warning:
This is not for use by third-party applications.
Since :
2.3
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/systemsettings.admin
Parameters:
[in]keyThe key name of the system settings
[out]valueThe new system settings value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_IO_ERRORInternal I/O error
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
int system_settings_set_value_int ( system_settings_key_e  key,
int  value 
)

Sets the system settings value associated with the given key as an integer.

Warning:
This is not for use by third-party applications.
Since :
2.3
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/systemsettings.admin
Parameters:
[in]keyThe key name of the system settings changed
[in]keyThe key name of the system settings
[out]valueThe new system settings value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_IO_ERRORInternal I/O error
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
int system_settings_set_value_string ( system_settings_key_e  key,
const char *  value 
)

Sets the system settings value associated with the given key as a string.

Warning:
This is not for use by third-party applications.
Since :
2.3
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/systemsettings.admin
Remarks:
SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for setting.
Parameters:
[in]keyThe key name of the system settings
[out]valueThe new system settings value of the given key
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_IO_ERRORInternal I/O error
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
int system_settings_unset_changed_cb ( system_settings_key_e  key)

Unregisters the callback function.

Since :
2.3
Remarks:
SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb.
Parameters:
[in]keyThe key name of the system settings
Returns:
0 on success, otherwise a negative error value
Return values:
SYSTEM_SETTINGS_ERROR_NONESuccessful
SYSTEM_SETTINGS_ERROR_INVALID_PARAMETERInvalid parameter
SYSTEM_SETTINGS_ERROR_PERMISSION_DENIEDPermission violation error
See also:
system_settings_set_changed_cb()
Warning:
http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this API since 2.3.1.