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.
18 #ifndef __TIZEN_APPFW_PREFERENCE_H__
19 #define __TIZEN_APPFW_PREFERENCE_H__
28 * @addtogroup CAPI_PREFERENCE_MODULE
34 * @brief Enumerations of error code for Preference.
38 PREFERENCE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
39 PREFERENCE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
40 PREFERENCE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
41 PREFERENCE_ERROR_NO_KEY = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Required key not available */
42 PREFERENCE_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR , /**< Internal I/O Error */
47 * @brief Called when the given key's value in the preference changes.
49 * @details When the @a key is added or removed, this callback function is skipped. (only update can be handled)
51 * @param [in] key The name of the key in the preference
52 * @param [in] user_data The user data passed from the callback registration function
53 * @pre This function is invoked when the value of the key is overwritten after you register this callback using preference_set_changed_cb()
54 * @see preference_set_changed_cb()
55 * @see preference_unset_changed_cb()
56 * @see preference_set_boolean()
57 * @see preference_set_int()
58 * @see preference_set_string()
59 * @see preference_set_double()
61 typedef void (*preference_changed_cb) (const char *key, void *user_data);
65 * @brief Called to get key string once for each key-value pair in the preference.
67 * @remarks You should not free @a key returned by this function.
69 * @param [in] key The key of the value added to the preference
70 * @param [in] value The value associated with the key
71 * @param [in] user_data The user data passed from the foreach function
72 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
73 * @pre preference_foreach_item() will invoke this callback function.
74 * @see preference_foreach_item()
76 typedef bool (*preference_item_cb)(const char *key, void *user_data);
80 * @brief Sets an integer value in the preference.
82 * @param [in] key The name of the key to modify
83 * @param [in] value The new @c int value for the given key
84 * @return 0 on success, otherwise a negative error value.
85 * @retval #PREFERENCE_ERROR_NONE Successful
86 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
87 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
88 * @see preference_get_int()
91 int preference_set_int(const char *key, int value);
95 * @brief Gets a integer value from the preference.
97 * @param [in] key The name of the key to retrieve
98 * @param [out] value The @c int value for the given key
99 * @return 0 on success, otherwise a negative error value.
100 * @retval #PREFERENCE_ERROR_NONE Successful
101 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
102 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
103 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
104 * @see preference_set_int()
106 int preference_get_int(const char *key, int *value);
110 * @brief Sets a double value in the preference.
112 * @param [in] key The name of the key to modify
113 * @param [in] value The new @c double value associated with given key
114 * @return 0 on success, otherwise a negative error value.
115 * @retval #PREFERENCE_ERROR_NONE Successful
116 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
117 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
118 * @see preference_get_double()
121 int preference_set_double(const char *key, double value);
125 * @brief Gets a double value from the preference.
127 * @param [in] key The name of the key to retrieve
128 * @param [out] value The @c double value associated with given key
129 * @return 0 on success, otherwise a negative error value.
130 * @retval #PREFERENCE_ERROR_NONE Successful
131 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
132 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
133 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
134 * @see preference_set_double()
137 int preference_get_double(const char *key, double *value);
141 * @brief Sets a string value in the preference.
143 * @details It makes a deep copy of the added string value.
145 * @param [in] key The name of the key to modify
146 * @param [in] value The new @c string value associated with given key
147 * @return 0 on success, otherwise a negative error value.
148 * @retval #PREFERENCE_ERROR_NONE Successful
149 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
150 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
151 * @see preference_get_string()
154 int preference_set_string(const char *key, const char *value);
158 * @brief Gets a string value from the preference.
160 * @remarks @a value must be released with free() by you.
161 * @param [in] key The name of the key to retrieve
162 * @param [out] value The @c string value associated with given key
163 * @return 0 on success, otherwise a negative error value.
164 * @retval #PREFERENCE_ERROR_NONE Successful
165 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
166 * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
167 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
168 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
169 * @see preference_set_string()
171 int preference_get_string(const char *key, char **value);
175 * @brief Sets a boolean value in the preference.
177 * @param [in] key The name of the key to modify
178 * @param [in] value The new boolean @c value associated with given key
179 * @return 0 on success, otherwise a negative error value.
180 * @retval #PREFERENCE_ERROR_NONE Successful
181 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
182 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
183 * @see preference_get_boolean()
185 int preference_set_boolean(const char *key, bool value);
189 * @brief Gets a boolean value from the preference.
191 * @param [in] key The name of the key to retrieve
192 * @param [out] value The boolean @c value associated with given key
193 * @return 0 on success, otherwise a negative error value.
194 * @retval #PREFERENCE_ERROR_NONE Successful
195 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
196 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
197 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
198 * @see preference_set_boolean()
200 int preference_get_boolean(const char *key, bool *value);
204 * @brief Removes any value with the given @a key from the preference.
206 * @param [in] key The name of the key to remove
207 * @return 0 on success, otherwise a negative error value.
208 * @retval #PREFERENCE_ERROR_NONE Successful
209 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
210 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
213 int preference_remove(const char *key);
217 * @brief Checks whether if the given @a key exists in the preference.
219 * @param [in] key The name of the key to check
220 * @param [out] existing @c true if the @a key exists in the preference, otherwise @c false
221 * @return 0 on success, otherwise a negative error value.
222 * @retval #PREFERENCE_ERROR_NONE Successful
223 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
224 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
226 int preference_is_existing(const char *key, bool *existing);
230 * @brief Removes all key-value pairs from the preference.
232 * @return 0 on success, otherwise a negative error value.
233 * @retval #PREFERENCE_ERROR_NONE Successful
234 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
235 * @see preference_remove()
237 int preference_remove_all(void);
241 * @brief Registers a callback function to be invoked when value of the given key in the preference changes.
243 * @param [in] key The name of the key to monitor
244 * @param [in] callback The callback function to register
245 * @param [in] user_data The user data to be passed to the callback function
246 * @return 0 on success, otherwise a negative error value.
247 * @retval #PREFERENCE_ERROR_NONE Successful
248 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
249 * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
250 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
251 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
252 * @post preference_changed_cb() will be invoked.
253 * @see preference_unset_changed_cb()
254 * @see preference_changed_cb()
256 int preference_set_changed_cb(const char *key, preference_changed_cb callback, void *user_data);
260 * @brief Unregisters the callback function.
262 * @param [in] key The name of the key to monitor
263 * @return 0 on success, otherwise a negative error value.
264 * @retval #PREFERENCE_ERROR_NONE Successful
265 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
266 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
267 * @see preference_set_changed_cb()
269 int preference_unset_changed_cb(const char *key);
273 * @brief Retrieves all key-value pairs in the preference by invoking the callback function.
275 * @param [in] callback The callback function to get key value once for each key-value pair in the preference
276 * @param [in] user_data The user data to be passed to the callback function
277 * @return 0 on success, otherwise a negative error value.
278 * @retval #PREFERENCE_ERROR_NONE Successful
279 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
280 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
281 * @post This function invokes preference_item_cb() repeatedly to get each key-value pair in the preference.
282 * @see preference_item_cb()
284 int preference_foreach_item(preference_item_cb callback, void *user_data);
295 #endif /* __TIZEN_APPFW_PREFERENCE_H__ */