2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef __TIZEN_SYSTEM_SYSTEM_SETTINGS_H__
18 #define __TIZEN_SYSTEM_SYSTEM_SETTINGS_H__
28 * @file system_settings.h
32 * @addtogroup CAPI_SYSTEM_SYSTEM_SETTINGS_MODULE
38 * @brief Enumeration for system settings error.
42 SYSTEM_SETTINGS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
43 SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
44 SYSTEM_SETTINGS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
45 SYSTEM_SETTINGS_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */
46 SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permition denied */
47 SYSTEM_SETTINGS_ERROR_CALL_UNSUPPORTED_API = TIZEN_ERROR_INVALID_PARAMETER, /**< Permition denied */
49 /* lock screen app error code */
50 SYSTEM_SETTINGS_ERROR_LOCKSCREEN_APP_PASSWORD_MODE = TIZEN_ERROR_SYSTEM_SETTING | 0x01, /**< Current lock screen app set 'password' type */
52 system_settings_error_e;
56 * @brief Enumeration for System Settings Key.
59 SYSTEM_SETTINGS_KEY_INCOMING_CALL_RINGTONE, /**< (string) The file path of the current ringtone */
60 SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN, /**< (string) The file path of the current home screen wallpaper */
61 SYSTEM_SETTINGS_KEY_WALLPAPER_LOCK_SCREEN, /**< (string) The file path of the current lock screen wallpaper */
62 SYSTEM_SETTINGS_KEY_FONT_SIZE, /**< (int) The current system font size */
63 SYSTEM_SETTINGS_KEY_FONT_TYPE, /**< (string) The current system font type */
64 SYSTEM_SETTINGS_KEY_MOTION_ACTIVATION, /**< (bool) Indicates whether the motion service is activated */
65 SYSTEM_SETTINGS_KEY_MOTION_ENABLED = SYSTEM_SETTINGS_KEY_MOTION_ACTIVATION, /**< @internal GET (bool) Indicates whether the device user has enabled the motion feature. */
66 SYSTEM_SETTINGS_KEY_EMAIL_ALERT_RINGTONE, /**< (string) The file path of the current email alert ringtone */
67 SYSTEM_SETTINGS_KEY_USB_DEBUGGING_ENABLED, /**< (bool) Indicates whether the USB debugging is enabled */
68 SYSTEM_SETTINGS_KEY_3G_DATA_NETWORK_ENABLED, /**< @internal (bool) Indicates whether the 3G data network is enabled */
69 SYSTEM_SETTINGS_KEY_TAP_AND_HOLD_DELAY, /**< @internal (int) Indicates delaying time of 'tab and hold' (sec) */
70 SYSTEM_SETTINGS_KEY_LOCKSCREEN_APP, /**< (string) Indicates lockscreen app pkg name */
71 SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE,/**< (string) The current system default font type (only support Get) */
73 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 */
74 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. */
76 SYSTEM_SETTINGS_KEY_LOCALE_TIMEFORMAT_24HOUR, /**< (bool) Indicates whether the 24-hour clock is used. If the value is @c false, the 12-hour clock is used. */
77 SYSTEM_SETTINGS_KEY_LOCALE_TIMEZONE, /**< (string) Indicates the current time zone. */
78 SYSTEM_SETTINGS_KEY_TIME_CHANGED, /**< (int) Once System changes time, this event occurs to notify time change. */
80 SYSTEM_SETTINGS_KEY_SOUND_LOCK, /**< GET (bool) Indicates whether the screen lock sound is enabled on the device. ex) LCD on/off sound */
81 SYSTEM_SETTINGS_KEY_SOUND_SILENT_MODE, /**< GET (bool) Indicates whether the device is in the silent mode. */
82 SYSTEM_SETTINGS_KEY_SOUND_TOUCH, /**< GET (bool) Indicates whether the screen touch sound is enabled on the device. */
84 SYSTEM_SETTINGS_KEY_DISPLAY_SCREEN_ROTATION_AUTO, /**< GET (bool) Indicates whether rotation control is automatic.*/
86 SYSTEM_SETTINGS_KEY_DEVICE_NAME, /**< GET (string) Indicates device name. */
87 SYSTEM_SETTINGS_KEY_NETWORK_WIFI_NOTIFICATION, /**< GET (bool) Indicates whether Wi-Fi-related notifications are enabled on the device. */
88 SYSTEM_SETTINGS_KEY_NETWORK_FLIGHT_MODE, /**< GET (bool) Indicates whether the device is in the flight mode. */
90 SYSTEM_SETTINGS_KEY_SCREEN_BACKLIGHT_TIME, /**< (int) Indicates the backlight time (in seconds). @internal The following values can be used: 15, 30, 60, 120, 300, and 600. */
92 SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION, /**< (string) Indicates the file path of the current notification tone set by the user. */
93 SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION_REPETITION_PERIOD, /**< (int) Indicates the time period for notification repetitions. */
94 SYSTEM_SETTINGS_KEY_MAX,
96 } system_settings_key_e;
100 * @brief Enumeration for tap and hold delay.
103 SYSTEM_SETTINGS_TAP_AND_HOLD_DELAY_SHORT = 500, /**< @internal 500 msec */
104 SYSTEM_SETTINGS_TAP_AND_HOLD_DELAY_MEDIUM = 1000, /**< @internal 1000 msec */
105 SYSTEM_SETTINGS_TAP_AND_HOLD_DELAY_LONG = 1500, /**< @internal 1500 msec */
106 } system_settings_tap_and_hold_delay_e;
109 * @brief Enumeration for font size.
112 SYSTEM_SETTINGS_FONT_SIZE_SMALL = 0, /**< A small size */
113 SYSTEM_SETTINGS_FONT_SIZE_NORMAL, /**< A normal size */
114 SYSTEM_SETTINGS_FONT_SIZE_LARGE, /**< A large size */
115 SYSTEM_SETTINGS_FONT_SIZE_HUGE, /**< A huge size */
116 SYSTEM_SETTINGS_FONT_SIZE_GIANT, /**< A giant size */
117 } system_settings_font_size_e;
121 * @brief Called when the system settings changes.
123 * @param[in] key The key name of the system settings changed system settings
124 * @param[in] user_data The user data passed from the callback registration function
125 * @pre system_settings_set_changed_cb() will invoke this callback function.
126 * @see system_settings_set_changed_cb()
127 * @see system_settings_unset_changed_cb()
129 typedef void (*system_settings_changed_cb)(system_settings_key_e key, void *user_data);
133 * @brief Sets the system settings value associated with the given key as an integer.
135 * @privlevel platform
136 * @privilege %http://tizen.org/privilege/systemsettings.admin
137 * @param[in] key The key name of the system settings changed
138 * @param[in] key The key name of the system settings
139 * @param[out] value The new system settings value of the given key
140 * @return @c 0 on success, otherwise a negative error value
141 * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
142 * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
143 * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
144 * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
146 int system_settings_set_value_int(system_settings_key_e key, int value);
149 * @brief Gets the system settings value associated with the given key as an integer.
152 * @privilege %http://tizen.org/privilege/systemsettings
153 * @param[in] key The key name of the system settings
154 * @param[out] value The current system settings value of the given key
155 * @return @c 0 on success, otherwise a negative error value
156 * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
157 * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
158 * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
159 * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
161 int system_settings_get_value_int(system_settings_key_e key, int *value);
166 * @brief Sets the system settings value associated with the given key as a boolean.
168 * @privlevel platform
169 * @privilege %http://tizen.org/privilege/systemsettings.admin
170 * @param[in] key The key name of the system settings
171 * @param[out] value The new system settings value of the given key
172 * @return @c 0 on success, otherwise a negative error value
173 * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
174 * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
175 * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
176 * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
178 int system_settings_set_value_bool(system_settings_key_e key, bool value);
181 * @brief Gets the system settings value associated with the given key as a boolean.
184 * @privilege %http://tizen.org/privilege/systemsettings
185 * @param[in] key The key name of the system settings
186 * @param[out] value The current system settings value of the given key
187 * @return @c 0 on success, otherwise a negative error value
188 * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
189 * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
190 * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
191 * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
193 int system_settings_get_value_bool(system_settings_key_e key, bool *value);
197 * @brief Sets the system settings value associated with the given key as a string.
199 * @privlevel platform
200 * @privilege %http://tizen.org/privilege/systemsettings.admin
201 * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for setting.
202 * @param[in] key The key name of the system settings
203 * @param[out] value The new system settings value of the given key
204 * @return @c 0 on success, otherwise a negative error value
205 * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
206 * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
207 * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
208 * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
210 int system_settings_set_value_string(system_settings_key_e key, const char *value);
213 * @brief Gets the system settings value associated with the given key as a string.
216 * @privilege %http://tizen.org/privilege/systemsettings
217 * @remarks You must release @a value using free().
218 * @param[in] key The key name of the system settings
219 * @param[out] value The current system settings value of the given key
220 * @return 0 on success, otherwise a negative error value
221 * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
222 * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
223 * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
224 * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
226 int system_settings_get_value_string(system_settings_key_e key, char **value);
229 * @brief Registers a change event callback for the given system settings key.
232 * @privilege %http://tizen.org/privilege/systemsettings
233 * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb.
234 * @param[in] key The key name of the system settings
235 * @param[in] callback The callback function to invoke
236 * @param[in] user_data The user data to be passed to the callback function
237 * @return 0 on success, otherwise a negative error value
238 * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
239 * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
240 * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
241 * @post system_settings_changed_cb() will be invoked.
243 * @see system_settings_unset_changed_cb()
244 * @see system_settings_changed_cb()
247 int system_settings_set_changed_cb(system_settings_key_e key, system_settings_changed_cb callback, void *user_data);
250 * @brief Unregisters the callback function.
253 * @privilege %http://tizen.org/privilege/systemsettings
254 * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb.
255 * @param[in] key The key name of the system settings
256 * @return 0 on success, otherwise a negative error value
257 * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
258 * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
259 * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
261 * @see system_settings_set_changed_cb()
263 int system_settings_unset_changed_cb(system_settings_key_e key);
275 #endif /* __TIZEN_SYSTEM_SYSTEM_SETTINGS_H__ */