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  * @addtogroup CAPI_PREFERENCE_MODULE
  29  * @{
  30  */
  31
  32
  33 /**
  34  * @brief Enumerations of error code for Preference.
  35  */
  36 typedef enum
  37 {
  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 */
  43 } preference_error_e;
  44
  45
  46 /**
  47  * @brief       Called when the given key's value in the preference changes.
  48  *
  49  * @details When the @a key is added or removed, this callback function is skipped. (only update can be handled)
  50  *
  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()
  60  */
  61 typedef void (*preference_changed_cb) (const char *key, void *user_data);
  62
  63
  64 /**
  65 * @brief   Called to get key string once for each key-value pair in the preference.
  66 *
  67 * @remarks You should not free @a key returned by this function.
  68 *
  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()
  75 */
  76 typedef bool (*preference_item_cb)(const char *key, void *user_data);
  77
  78
  79 /**
  80  * @brief Sets an integer value in the preference.
  81  *
  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()
  89  *
  90  */
  91 int preference_set_int(const char *key, int value);
  92
  93
  94 /**
  95  * @brief Gets a integer value from the preference.
  96  *
  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()
 105  */
 106 int preference_get_int(const char *key, int *value);
 107
 108
 109 /**
 110  * @brief Sets a double value in the preference.
 111  *
 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()
 119  *
 120  */
 121 int preference_set_double(const char *key, double value);
 122
 123
 124 /**
 125  * @brief Gets a double value from the preference.
 126  *
 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()
 135  *
 136  */
 137 int preference_get_double(const char *key, double *value);
 138
 139
 140 /**
 141  * @brief Sets a string value in the preference.
 142  *
 143  * @details It makes a deep copy of the added string value.
 144  *
 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()
 152  *
 153  */
 154 int preference_set_string(const char *key, const char *value);
 155
 156
 157 /**
 158  * @brief Gets a string value from the preference.
 159  *
 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()
 170  */
 171 int preference_get_string(const char *key, char **value);
 172
 173
 174 /**
 175  * @brief Sets a boolean value in the preference.
 176  *
 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()
 184  */
 185 int preference_set_boolean(const char *key, bool value);
 186
 187
 188 /**
 189  * @brief Gets a boolean value from the preference.
 190  *
 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()
 199  */
 200 int preference_get_boolean(const char *key, bool *value);
 201
 202
 203 /**
 204  * @brief Removes any value with the given @a key from the preference.
 205  *
 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
 211  *
 212  */
 213 int preference_remove(const char *key);
 214
 215
 216 /**
 217  * @brief Checks whether if the given @a key exists in the preference.
 218  *
 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
 225  */
 226 int preference_is_existing(const char *key, bool *existing);
 227
 228
 229 /**
 230  * @brief Removes all key-value pairs from the preference.
 231  *
 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()
 236  */
 237 int preference_remove_all(void);
 238
 239
 240 /**
 241  * @brief Registers a callback function to be invoked when value of the given key in the preference changes.
 242  *
 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()
 255  */
 256 int preference_set_changed_cb(const char *key, preference_changed_cb callback, void *user_data);
 257
 258
 259 /**
 260  * @brief Unregisters the callback function.
 261  *
 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()
 268  */
 269 int preference_unset_changed_cb(const char *key);
 270
 271
 272 /**
 273  * @brief Retrieves all key-value pairs in the preference by invoking the callback function.
 274  *
 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()
 283  */
 284 int preference_foreach_item(preference_item_cb callback, void *user_data);
 285
 286
 287 /**
 288  * @}
 289  */
 290
 291 #ifdef __cplusplus
 292 }
 293 #endif
 294
 295 #endif /* __TIZEN_APPFW_PREFERENCE_H__ */