Tizen Native API
5.5
|
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.
Related Features
This API is related with the following features:
- http://tizen.org/feature/systemsetting
- http://tizen.org/feature/systemsetting.home_screen
- http://tizen.org/feature/systemsetting.lock_screen
- http://tizen.org/feature/systemsetting.incoming_call
- http://tizen.org/feature/systemsetting.notification_email
- http://tizen.org/feature/systemsetting.font
- http://tizen.org/feature/network.wifi
- http://tizen.org/feature/network.telephony
- http://tizen.org/feature/accessibility.grayscale
- http://tizen.org/feature/accessibility.negative
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information,thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
The table below shows additional related features on which System Settings keys depend.
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) |
Sets a change event callback for the given system settings key. | |
int | system_settings_unset_changed_cb (system_settings_key_e key) |
Unsets the callback function. | |
int | system_settings_foreach_value_string (system_settings_key_e key, system_settings_iter_cb callback, void *user_data) |
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. | |
int | system_settings_add_changed_cb (system_settings_key_e key, system_settings_changed_cb callback, void *user_data) |
Adds a change event callback for the given system settings key. | |
int | system_settings_remove_changed_cb (system_settings_key_e key, system_settings_changed_cb callback) |
Removes a change event callback function. | |
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] key The key name of the system settings changed system settings [in] user_data The user data passed from the callback registration function
- Precondition:
- system_settings_set_changed_cb() will invoke this callback function.
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] index zero based number indicating index of node in a list [in] value value returned from the list [in] cb_data The 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
Enumeration for system settings error.
- Since :
- 2.3
- Enumerator:
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 2.4)
SYSTEM_SETTINGS_KEY_3G_DATA_NETWORK_ENABLED (bool) Indicates whether the 3G data network is enabled (Since 2.4)
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)
SYSTEM_SETTINGS_KEY_ULTRA_DATA_SAVE (int) Indicates Ultra Data Save status, one of system_settings_uds_state_e values (Since 4.0)
SYSTEM_SETTINGS_KEY_ULTRA_DATA_SAVE_PKG_LIST (string) Indicates Ultra Data Save Package List (Since 4.0), the list is a string containing whitelisted package names separated with semicolons (;)
SYSTEM_SETTINGS_KEY_ACCESSIBILITY_TTS GET (bool) Indicates whether the accessibility TTS is enabled on the device. (Since 4.0)
SYSTEM_SETTINGS_KEY_VIBRATION (bool) Indicates whether vibration is enabled on the device. (Since 4.0)
SYSTEM_SETTINGS_KEY_AUTOMATIC_TIME_UPDATE (bool) Indicates whether updating time automatically is enabled on the device. (Since 5.0)
SYSTEM_SETTINGS_KEY_DEVELOPER_OPTION_STATE (bool) Indicates whether developer option state is enabled on the device. (Since 5.0)
SYSTEM_SETTINGS_KEY_ACCESSIBILITY_GRAYSCALE (bool) Indicates whether accessibility grayscale is enabled on the device. (Since 5.5)
SYSTEM_SETTINGS_KEY_ACCESSIBILITY_NEGATIVE_COLOR (bool) Indicates whether accessibility negative color is enabled on the device. (Since 5.5)
SYSTEM_SETTINGS_KEY_ROTARY_EVENT_ENABLED (bool) Indicates whether rotary event is enabled on the device. (Since 5.5)
Function Documentation
int system_settings_add_changed_cb | ( | system_settings_key_e | key, |
system_settings_changed_cb | callback, | ||
void * | user_data | ||
) |
Adds a change event callback for the given system settings key.
The difference between this function and system_settings_set_changed_cb() is that system_settings_set_changed_cb() can set only one callback for a given key, while system_settings_add_changed_cb() can set multiple callbacks for a given key.
- Since :
- 5.0
- Remarks:
- The key cannot be SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE. When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [in] callback The callback function to invoke [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- Postcondition:
- system_settings_changed_cb() will be invoked.
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
- Remarks:
- When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [in] value string typed value to be appended
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
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
- Remarks:
- When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [in] value string typed value to be removed
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
int system_settings_foreach_value_string | ( | system_settings_key_e | key, |
system_settings_iter_cb | callback, | ||
void * | user_data | ||
) |
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
- Remarks:
- When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [in] callback The callback-function name for iteration [in] user_data The user data passed from caller-side
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
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
- Remarks:
- When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [out] value The current system settings value of the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- Warning:
- http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this function 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
- Remarks:
- When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [out] value The current system settings value of the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- Warning:
- http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this function 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(). When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [out] value The current system settings value of the given key
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- Warning:
- http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this function since 2.3.1.
int system_settings_remove_changed_cb | ( | system_settings_key_e | key, |
system_settings_changed_cb | callback | ||
) |
Removes a change event callback function.
The difference between this function and system_settings_unset_changed_cb() is that system_settings_unset_changed_cb() unsets the callback set with system_settings_set_changed_cb(), while system_settings_remove_changed_cb() removes callbacks added with system_settings_add_changed_cb()
- Since :
- 5.0
- Remarks:
- The key cannot be SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE. When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [in] callback The callback function to be removed
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- See also:
- system_settings_add_changed_cb()
int system_settings_set_changed_cb | ( | system_settings_key_e | key, |
system_settings_changed_cb | callback, | ||
void * | user_data | ||
) |
Sets 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. When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [in] callback The callback function to invoke [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- Postcondition:
- system_settings_changed_cb() will be invoked.
- Warning:
- http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this function 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
- Remarks:
- When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [out] value The new system settings value of the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
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
- Remarks:
- When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [out] value The new system settings value of the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
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. When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings [out] value The new system settings value of the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
Unsets the callback function.
- Since :
- 2.3
- Remarks:
- SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb. When the feature related to the key is not supported on the device, SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
- Parameters:
-
[in] key The key name of the system settings
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
SYSTEM_SETTINGS_ERROR_NONE Successful SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- See also:
- system_settings_set_changed_cb()
- Warning:
- http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT be declared to use this function since 2.3.1.