include/app_preference.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17
  18 #ifndef __TIZEN_APPFW_PREFERENCE_H__
  19 #define __TIZEN_APPFW_PREFERENCE_H__
  20
  21 #include <tizen.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file app_preference.h
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_PREFERENCE_MODULE
  33  * @{
  34  */
  35
  36
  37 /**
  38  * @brief Enumeration for Preference Error.
  39  * @since_tizen 2.3
  40  */
  41 typedef enum
  42 {
  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 */
  48 } preference_error_e;
  49
  50
  51 /**
  52  * @brief Called when the given key's value in the preference changes.
  53  *
  54  * @details When the @a key is added or removed, this callback function is skipped(only update can be handled).
  55  *
  56  * @since_tizen 2.3
  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()
  66  */
  67 typedef void (*preference_changed_cb) (const char *key, void *user_data);
  68
  69
  70 /**
  71  * @brief Called to get key string, once for each key-value pair in the preference.
  72  *
  73  * @since_tizen 2.3
  74  * @remarks You should not free the @a key returned by this function.
  75  *
  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()
  83  */
  84 typedef bool (*preference_item_cb)(const char *key, void *user_data);
  85
  86
  87 /**
  88  * @brief Sets an integer value in the preference.
  89  *
  90  * @since_tizen 2.3
  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()
  99  */
 100 int preference_set_int(const char *key, int value);
 101
 102
 103 /**
 104  * @brief Gets an integer value from the preference.
 105  *
 106  * @since_tizen 2.3
 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()
 116  */
 117 int preference_get_int(const char *key, int *value);
 118
 119
 120 /**
 121  * @brief Sets a double value in the preference.
 122  *
 123  * @since_tizen 2.3
 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()
 132  */
 133 int preference_set_double(const char *key, double value);
 134
 135
 136 /**
 137  * @brief Gets a double value from the preference.
 138  *
 139  * @since_tizen 2.3
 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()
 149  */
 150 int preference_get_double(const char *key, double *value);
 151
 152
 153 /**
 154  * @brief Sets a string value in the preference.
 155  *
 156  * @details It makes a deep copy of the added string value.
 157  *
 158  * @since_tizen 2.3
 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()
 167  */
 168 int preference_set_string(const char *key, const char *value);
 169
 170
 171 /**
 172  * @brief Gets a string value from the preference.
 173  *
 174  * @since_tizen 2.3
 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()
 186  */
 187 int preference_get_string(const char *key, char **value);
 188
 189
 190 /**
 191  * @brief Sets a boolean value in the preference.
 192  *
 193  * @since_tizen 2.3
 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()
 202  */
 203 int preference_set_boolean(const char *key, bool value);
 204
 205
 206 /**
 207  * @brief Gets a boolean value from the preference.
 208  *
 209  * @since_tizen 2.3
 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()
 219  */
 220 int preference_get_boolean(const char *key, bool *value);
 221
 222
 223 /**
 224  * @brief Removes any value with the given @a key from the preference.
 225  *
 226  * @since_tizen 2.3
 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
 233  */
 234 int preference_remove(const char *key);
 235
 236
 237 /**
 238  * @brief Checks whether the given @a key exists in the preference.
 239  *
 240  * @since_tizen 2.3
 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,
 243  *                       otherwise @c false
 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
 249  */
 250 int preference_is_existing(const char *key, bool *existing);
 251
 252
 253 /**
 254  * @brief Removes all key-value pairs from the preference.
 255  *
 256  * @since_tizen 2.3
 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()
 262  */
 263 int preference_remove_all(void);
 264
 265
 266 /**
 267  * @brief Registers a callback function to be invoked when value of the given key in the preference changes.
 268  *
 269  * @since_tizen 2.3
 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()
 283  */
 284 int preference_set_changed_cb(const char *key, preference_changed_cb callback, void *user_data);
 285
 286
 287 /**
 288  * @brief Unregisters the callback function.
 289  *
 290  * @since_tizen 2.3
 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()
 298  */
 299 int preference_unset_changed_cb(const char *key);
 300
 301
 302 /**
 303  * @brief Retrieves all key-value pairs in the preference by invoking the callback function.
 304  *
 305  * @since_tizen 2.3
 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()
 315  */
 316 int preference_foreach_item(preference_item_cb callback, void *user_data);
 317
 318
 319 /**
 320  * @}
 321  */
 322
 323 #ifdef __cplusplus
 324 }
 325 #endif
 326
 327 #endif /* __TIZEN_APPFW_PREFERENCE_H__ */