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 * @file app_preference.h
32 * @addtogroup CAPI_PREFERENCE_MODULE
38 * @brief Enumeration for Preference Error.
43 PREFERENCE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
44 PREFERENCE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
45 PREFERENCE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
46 PREFERENCE_ERROR_NO_KEY = TIZEN_ERROR_APPLICATION | 0x30, /**< Required key not available */
47 PREFERENCE_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR , /**< Internal I/O Error */
52 * @brief Called when the given key's value in the preference changes.
54 * @details When the @a key is added or removed, this callback function is skipped(only update can be handled).
57 * @param[in] key The name of the key in the preference
58 * @param[in] user_data The user data passed from the callback registration function
59 * @pre This function is invoked when the value of the key is overwritten after you register this callback using preference_set_changed_cb().
60 * @see preference_set_changed_cb()
61 * @see preference_unset_changed_cb()
62 * @see preference_set_boolean()
63 * @see preference_set_int()
64 * @see preference_set_string()
65 * @see preference_set_double()
67 typedef void (*preference_changed_cb) (const char *key, void *user_data);
71 * @brief Called to get key string, once for each key-value pair in the preference.
74 * @remarks You should not free the @a key returned by this function.
76 * @param[in] key The key of the value added to the preference
77 * @param[in] value The value associated with the key
78 * @param[in] user_data The user data passed from the foreach function
79 * @return @c true to continue with the next iteration of the loop,
80 * otherwise @c false to break out of the loop
81 * @pre preference_foreach_item() will invoke this callback function.
82 * @see preference_foreach_item()
84 typedef bool (*preference_item_cb)(const char *key, void *user_data);
88 * @brief Sets an integer value in the preference.
91 * @param[in] key The name of the key to modify
92 * @param[in] value The new @c int value for the given key
93 * @return @c 0 on success,
94 * otherwise a negative error value
95 * @retval #PREFERENCE_ERROR_NONE Successful
96 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
97 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
98 * @see preference_get_int()
100 int preference_set_int(const char *key, int value);
104 * @brief Gets an integer value from the preference.
107 * @param[in] key The name of the key to retrieve
108 * @param[out] value The @c int value for the given key
109 * @return @c 0 on success,
110 * otherwise a negative error value
111 * @retval #PREFERENCE_ERROR_NONE Successful
112 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
113 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
114 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
115 * @see preference_set_int()
117 int preference_get_int(const char *key, int *value);
121 * @brief Sets a double value in the preference.
124 * @param[in] key The name of the key to modify
125 * @param[in] value The new @c double value associated with the given key
126 * @return @c 0 on success,
127 * otherwise a negative error value
128 * @retval #PREFERENCE_ERROR_NONE Successful
129 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
130 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
131 * @see preference_get_double()
133 int preference_set_double(const char *key, double value);
137 * @brief Gets a double value from the preference.
140 * @param[in] key The name of the key to retrieve
141 * @param[out] value The @c double value associated with the given key
142 * @return @c 0 on success,
143 * otherwise a negative error value
144 * @retval #PREFERENCE_ERROR_NONE Successful
145 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
146 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
147 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
148 * @see preference_set_double()
150 int preference_get_double(const char *key, double *value);
154 * @brief Sets a string value in the preference.
156 * @details It makes a deep copy of the added string value.
159 * @param[in] key The name of the key to modify
160 * @param[in] value The new @c string value associated with the given key
161 * @return @c 0 on success,
162 * otherwise a negative error value
163 * @retval #PREFERENCE_ERROR_NONE Successful
164 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
165 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
166 * @see preference_get_string()
168 int preference_set_string(const char *key, const char *value);
172 * @brief Gets a string value from the preference.
175 * @remarks @a value must be released using free().
176 * @param[in] key The name of the key to retrieve
177 * @param[out] value The @c string value associated with the given key
178 * @return @c 0 on success,
179 * otherwise a negative error value
180 * @retval #PREFERENCE_ERROR_NONE Successful
181 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
182 * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
183 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
184 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
185 * @see preference_set_string()
187 int preference_get_string(const char *key, char **value);
191 * @brief Sets a boolean value in the preference.
194 * @param[in] key The name of the key to modify
195 * @param[in] value The new @c boolean value associated with the given key
196 * @return @c 0 on success,
197 * otherwise a negative error value
198 * @retval #PREFERENCE_ERROR_NONE Successful
199 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
200 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
201 * @see preference_get_boolean()
203 int preference_set_boolean(const char *key, bool value);
207 * @brief Gets a boolean value from the preference.
210 * @param[in] key The name of the key to retrieve
211 * @param[out] value The @c boolean value associated with the given key
212 * @return @c 0 on success,
213 * otherwise a negative error value
214 * @retval #PREFERENCE_ERROR_NONE Successful
215 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
216 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
217 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
218 * @see preference_set_boolean()
220 int preference_get_boolean(const char *key, bool *value);
224 * @brief Removes any value with the given @a key from the preference.
227 * @param[in] key The name of the key to remove
228 * @return @c 0 on success,
229 * otherwise a negative error value
230 * @retval #PREFERENCE_ERROR_NONE Successful
231 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
232 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
234 int preference_remove(const char *key);
238 * @brief Checks whether the given @a key exists in the preference.
241 * @param[in] key The name of the key to check
242 * @param[out] existing If @c true the @a key exists in the preference,
244 * @return @c 0 on success,
245 * otherwise a negative error value
246 * @retval #PREFERENCE_ERROR_NONE Successful
247 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
248 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
250 int preference_is_existing(const char *key, bool *existing);
254 * @brief Removes all key-value pairs from the preference.
257 * @return @c 0 on success,
258 * otherwise a negative error value
259 * @retval #PREFERENCE_ERROR_NONE Successful
260 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
261 * @see preference_remove()
263 int preference_remove_all(void);
267 * @brief Registers a callback function to be invoked when value of the given key in the preference changes.
270 * @param[in] key The name of the key to monitor
271 * @param[in] callback The callback function to register
272 * @param[in] user_data The user data to be passed to the callback function
273 * @return @c 0 on success,
274 * otherwise a negative error value
275 * @retval #PREFERENCE_ERROR_NONE Successful
276 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
277 * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
278 * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
279 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
280 * @post preference_changed_cb() will be invoked.
281 * @see preference_unset_changed_cb()
282 * @see preference_changed_cb()
284 int preference_set_changed_cb(const char *key, preference_changed_cb callback, void *user_data);
288 * @brief Unregisters the callback function.
291 * @param[in] key The name of the key to monitor
292 * @return @c 0 on success,
293 * otherwise a negative error value
294 * @retval #PREFERENCE_ERROR_NONE Successful
295 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
296 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
297 * @see preference_set_changed_cb()
299 int preference_unset_changed_cb(const char *key);
303 * @brief Retrieves all key-value pairs in the preference by invoking the callback function.
306 * @param[in] callback The callback function to get key value once for each key-value pair in the preference
307 * @param[in] user_data The user data to be passed to the callback function
308 * @return @c 0 on success,
309 * otherwise a negative error value
310 * @retval #PREFERENCE_ERROR_NONE Successful
311 * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
312 * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
313 * @post This function invokes preference_item_cb() repeatedly to get each key-value pair in the preference.
314 * @see preference_item_cb()
316 int preference_foreach_item(preference_item_cb callback, void *user_data);
327 #endif /* __TIZEN_APPFW_PREFERENCE_H__ */