Added SYSTEM_SETTINGS_KEY_ACCESSIBILITY_TTS
[platform/core/api/system-settings.git] / include / system_settings.h
1 /* * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
2  *
3  * Licensed under the Apache License, Version 2.0 (the License);
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an AS IS BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15
16 #ifndef __TIZEN_SYSTEM_SYSTEM_SETTINGS_H__
17 #define __TIZEN_SYSTEM_SYSTEM_SETTINGS_H__
18
19 #include <tizen.h>
20
21 #ifdef __cplusplus
22 extern "C"
23 {
24 #endif
25
26 /**
27  * @file system_settings.h
28  */
29
30 /**
31  * @addtogroup CAPI_SYSTEM_SYSTEM_SETTINGS_MODULE
32  * @{
33  */
34
35
36 /**
37  * @brief Enumeration for system settings error.
38  * @since_tizen 2.3
39  */
40 typedef enum {
41         SYSTEM_SETTINGS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
42         SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
43         SYSTEM_SETTINGS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
44         SYSTEM_SETTINGS_ERROR_IO_ERROR =  TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */
45         SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED =  TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
46         SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED =  TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported @if MOBILE (Since 2.3.1) @endif */
47         SYSTEM_SETTINGS_ERROR_CALL_UNSUPPORTED_API = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported @if MOBILE (Since 2.3.1) @endif */
48
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 */
51 }
52 system_settings_error_e;
53
54
55 /**
56  * @brief Enumeration for System Settings Key.
57  * @since_tizen 2.3
58  */
59 typedef enum {
60         SYSTEM_SETTINGS_KEY_INCOMING_CALL_RINGTONE, /**< (string) The file path of the current ringtone */
61         SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN, /**< (string) The file path of the current home screen wallpaper */
62         SYSTEM_SETTINGS_KEY_WALLPAPER_LOCK_SCREEN, /**< (string) The file path of the current lock screen wallpaper */
63         SYSTEM_SETTINGS_KEY_FONT_SIZE, /**< (int) The current system font size */
64         SYSTEM_SETTINGS_KEY_FONT_TYPE, /**< (string) The current system font type */
65         SYSTEM_SETTINGS_KEY_MOTION_ACTIVATION, /**< (bool) Indicates whether the motion service is activated */
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 (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
68         SYSTEM_SETTINGS_KEY_3G_DATA_NETWORK_ENABLED,  /**< (bool) Indicates whether the 3G data network is enabled (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
69         SYSTEM_SETTINGS_KEY_LOCKSCREEN_APP = SYSTEM_SETTINGS_KEY_3G_DATA_NETWORK_ENABLED+2,      /**< (string) Indicates lockscreen app pkg name  */
70         SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE,/**< (string) The current system default font type (only support Get) */
71         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 */
72         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. */
73         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. */
74         SYSTEM_SETTINGS_KEY_LOCALE_TIMEZONE,    /**< (string) Indicates the current time zone. */
75         SYSTEM_SETTINGS_KEY_TIME_CHANGED,               /**< (int) Once System changes time, this event occurs to notify time change. */
76         SYSTEM_SETTINGS_KEY_SOUND_LOCK,                                 /**< GET (bool) Indicates whether the screen lock sound is enabled on the device. ex) LCD on/off sound */
77         SYSTEM_SETTINGS_KEY_SOUND_SILENT_MODE,                  /**< GET (bool) Indicates whether the device is in the silent mode. */
78         SYSTEM_SETTINGS_KEY_SOUND_TOUCH,                                /**< GET (bool) Indicates whether the screen touch sound is enabled on the device. */
79         SYSTEM_SETTINGS_KEY_DISPLAY_SCREEN_ROTATION_AUTO,       /**< GET (bool) Indicates whether rotation control is automatic.*/
80         SYSTEM_SETTINGS_KEY_DEVICE_NAME,                                        /**< GET (string) Indicates device name. */
81         SYSTEM_SETTINGS_KEY_MOTION_ENABLED,                                     /**< GET (bool) Indicates whether the device user has enabled the motion feature. */
82         SYSTEM_SETTINGS_KEY_NETWORK_WIFI_NOTIFICATION,          /**< GET (bool) Indicates whether Wi-Fi-related notifications are enabled on the device. */
83         SYSTEM_SETTINGS_KEY_NETWORK_FLIGHT_MODE,                        /**< GET (bool) Indicates whether the device is in the flight mode. */
84         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. */
85         SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION,                         /**< (string) Indicates the file path of the current notification tone set by the user. */
86         SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION_REPETITION_PERIOD,       /**< (int) Indicates the time period for notification repetitions. */
87         SYSTEM_SETTINGS_KEY_LOCK_STATE,         /**< (int) Indicates the current lock state */
88         SYSTEM_SETTINGS_KEY_ADS_ID, /**< (string) Indicates Ads ID for each device (Since 3.0) */
89         SYSTEM_SETTINGS_KEY_ULTRA_DATA_SAVE, /**< (int) Indicates Ultra Data Save status, one of #system_settings_uds_state_e values (Since 4.0) */
90         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 (;) */
91         SYSTEM_SETTINGS_KEY_ACCESSIBILITY_TTS,                          /**< GET (bool) Indicates whether the accessibility TTS is enabled on the device. (Since 4.0) */
92         SYSTEM_SETTINGS_KEY_MAX,
93 } system_settings_key_e;
94
95 /**
96  * @brief Enumeration for Idle Lock State
97  * @since_tizen 2.3.1
98  */
99 typedef enum {
100         SYSTEM_SETTINGS_LOCK_STATE_UNLOCK = 0, /**< Device is unlocked */
101         SYSTEM_SETTINGS_LOCK_STATE_LOCK, /**< Device is locked */
102         SYSTEM_SETTINGS_LOCK_STATE_LAUNCHING_LOCK /**< Device is being locked */
103 } system_settings_idle_lock_state_e;
104
105
106 /**
107  * @brief Enumeration for font size.
108  * @since_tizen 2.3
109  */
110 typedef enum {
111         SYSTEM_SETTINGS_FONT_SIZE_SMALL = 0, /**< A small size */
112         SYSTEM_SETTINGS_FONT_SIZE_NORMAL, /**< A normal size */
113         SYSTEM_SETTINGS_FONT_SIZE_LARGE, /**< A large size */
114         SYSTEM_SETTINGS_FONT_SIZE_HUGE, /**< A huge size */
115         SYSTEM_SETTINGS_FONT_SIZE_GIANT, /**< A giant size */
116 } system_settings_font_size_e;
117
118 /**
119  * @brief Enumeration for Ultra Data Save
120  * @since_tizen 4.0
121  */
122 typedef enum {
123         SYSTEM_SETTINGS_UDS_OFF = 0,                    /**< OFF */
124         SYSTEM_SETTINGS_UDS_ON,                                 /**< ON */
125         SYSTEM_SETTINGS_UDS_ON_WHITELISTED,             /**< UDS on and the app is whitelisted */
126 } system_settings_uds_state_e;
127
128
129
130 /**
131  * @brief Called when the system settings changes.
132  * @since_tizen 2.3
133  * @param[in] key The key name of the system settings changed system settings
134  * @param[in] user_data The user data passed from the callback registration function
135  * @pre system_settings_set_changed_cb() will invoke this callback function.
136  * @see system_settings_set_changed_cb()
137  * @see system_settings_unset_changed_cb()
138  */
139 typedef void (*system_settings_changed_cb)(system_settings_key_e key, void *user_data);
140
141 /**
142  * @platform
143  * @brief Sets the system settings value associated with the given key as an integer.
144  * @since_tizen 2.3
145  * @privlevel platform
146  * @privilege %http://tizen.org/privilege/systemsettings.admin
147  * @remarks When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
148  * @param[in] key The key name of the system settings
149  * @param[out] value The new system settings value of the given key
150  * @return @c 0 on success, otherwise a negative error value
151  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
152  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
153  * @retval      #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
154  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
155  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
156  */
157 int system_settings_set_value_int(system_settings_key_e key, int value);
158
159 /**
160  * @brief Gets the system settings value associated with the given key as an integer.
161  * @since_tizen 2.3
162  * @remarks When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
163  * @param[in] key The key name of the system settings
164  * @param[out] value The current system settings value of the given key
165  * @return @c 0 on success, otherwise a negative error value
166  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
167  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
168  * @retval      #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
169  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
170  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
171  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
172  */
173 int system_settings_get_value_int(system_settings_key_e key, int *value);
174
175
176 /**
177  * @platform
178  * @brief Sets the system settings value associated with the given key as a boolean.
179  * @since_tizen 2.3
180  * @privlevel platform
181  * @privilege %http://tizen.org/privilege/systemsettings.admin
182  * @remarks When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
183  * @param[in] key The key name of the system settings
184  * @param[out] value The new system settings value of the given key
185  * @return @c 0 on success, otherwise a negative error value
186  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
187  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
188  * @retval      #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
189  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
190  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
191  */
192 int system_settings_set_value_bool(system_settings_key_e key, bool value);
193
194 /**
195  * @brief Gets the system settings value associated with the given key as a boolean.
196  * @since_tizen 2.3
197  * @remarks When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
198  * @param[in] key The key name of the system settings
199  * @param[out] value The current system settings value of the given key
200  * @return @c 0 on success, otherwise a negative error value
201  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
202  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
203  * @retval      #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
204  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
205  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
206  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
207  */
208 int system_settings_get_value_bool(system_settings_key_e key, bool *value);
209
210 /**
211  * @platform
212  * @brief Sets the system settings value associated with the given key as a string.
213  * @since_tizen 2.3
214  * @privlevel platform
215  * @privilege %http://tizen.org/privilege/systemsettings.admin
216  * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for setting. When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
217  * @param[in] key The key name of the system settings
218  * @param[out] value The new system settings value of the given key
219  * @return @c 0 on success, otherwise a negative error value
220  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
221  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
222  * @retval      #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
223  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
224  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
225  */
226 int system_settings_set_value_string(system_settings_key_e key, const char *value);
227
228 /**
229  * @brief Gets the system settings value associated with the given key as a string.
230  * @since_tizen 2.3
231  * @remarks You must release @a value using free(). When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
232  * @param[in] key The key name of the system settings
233  * @param[out] value The current system settings value of the given key
234  * @return      0 on success, otherwise a negative error value
235  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
236  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
237  * @retval      #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
238  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
239  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
240  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
241  */
242 int system_settings_get_value_string(system_settings_key_e key, char **value);
243
244 /**
245  * @brief Registers a change event callback for the given system settings key.
246  * @since_tizen 2.3
247  * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb. When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
248  * @param[in] key The key name of the system settings
249  * @param[in] callback The callback function to invoke
250  * @param[in] user_data The user data to be passed to the callback function
251  * @return      0 on success, otherwise a negative error value
252  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
253  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
254  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
255  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
256  * @post system_settings_changed_cb() will be invoked.
257  *
258  * @see system_settings_unset_changed_cb()
259  * @see system_settings_changed_cb()
260  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
261  *
262 */
263 int system_settings_set_changed_cb(system_settings_key_e key, system_settings_changed_cb callback, void *user_data);
264
265 /**
266  * @brief Unregisters the callback function.
267  * @since_tizen 2.3
268  * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb. When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
269  * @param[in] key The key name of the system settings
270  * @return      0 on success, otherwise a negative error value
271  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
272  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
273  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
274  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
275  *
276  * @see system_settings_set_changed_cb()
277  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
278  */
279 int system_settings_unset_changed_cb(system_settings_key_e key);
280
281
282 /**
283  * @platform
284  * @brief Called to get each string value from string typed list.
285  * @since_tizen 3.0
286  * @param[in] index zero based number indicating index of node in a list
287  * @param[in] value value returned from the list
288  * @param[in] cb_data  The user data passed from the foreach function
289  * @return @c true to continue with the next iteration of the loop, otherwise false to break out of the loop
290  */
291 typedef bool (*system_settings_iter_cb)(int index, const char* value, void *cb_data);
292
293 /**
294  * @platform
295  * @brief Iterate the system settings value associated with the given key as a string type.
296  * @since_tizen 3.0
297  * @privlevel platform
298  * @privilege %http://tizen.org/privilege/systemsettings.admin
299  * @remarks When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
300  * @param[in] key The key name of the system settings
301  * @param[in] callback The callback-function name for iteration
302  * @param[in] user_data  The user data passed from caller-side
303  * @return @c 0 on success, otherwise a negative error value
304  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
305  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
306  * @retval      #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
307  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
308  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
309  */
310 int system_settings_foreach_value_string(system_settings_key_e key, system_settings_iter_cb callback, void *user_data);
311
312 /**
313  * @platform
314  * @brief Adds the system settings value associated with the given key as a string type if it supports List iteration.
315  * @since_tizen 3.0
316  * @privlevel platform
317  * @privilege %http://tizen.org/privilege/systemsettings.admin
318  * @remarks When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
319  * @param[in] key The key name of the system settings
320  * @param[in] value string typed value to be appended
321  * @return @c 0 on success, otherwise a negative error value
322  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
323  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
324  * @retval      #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
325  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
326  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
327  */
328 int system_settings_add_value_string(system_settings_key_e key, const char *value);
329
330 /**
331  * @platform
332  * @brief Delete the system settings value associated with the given key as an string type if it supports List iteration.
333  * @since_tizen 3.0
334  * @privlevel platform
335  * @privilege %http://tizen.org/privilege/systemsettings.admin
336  * @remarks When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
337  * @param[in] key The key name of the system settings
338  * @param[in] value string typed value to be removed
339  * @return @c 0 on success, otherwise a negative error value
340  * @retval      #SYSTEM_SETTINGS_ERROR_NONE Successful
341  * @retval      #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
342  * @retval      #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
343  * @retval      #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
344  * @retval      #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
345  */
346 int system_settings_delete_value_string(system_settings_key_e key, const char *value);
347
348 /**
349  * @}
350  */
351
352
353 #ifdef __cplusplus
354 }
355 #endif
356
357 #endif /* __TIZEN_SYSTEM_SYSTEM_SETTINGS_H__ */