include/app_preference.h

   1 /*
   2  * Copyright (c) 2011 - 2016 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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  40  */
  41 typedef enum {
  42         PREFERENCE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  43         PREFERENCE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  44         PREFERENCE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  45         PREFERENCE_ERROR_NO_KEY = TIZEN_ERROR_APPLICATION | 0x30, /**< Required key not available */
  46         PREFERENCE_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR , /**< Internal I/O Error */
  47 } preference_error_e;
  48
  49
  50 /**
  51  * @brief Called when the given key's value in the preference changes.
  52  *
  53  * @details When the @a key is added or removed, this callback function is skipped(only update can be handled).
  54  *
  55  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  56  * @param[in] key The name of the key in the preference
  57  * @param[in] user_data The user data passed from the callback registration function
  58  * @pre This function is invoked when the value of the key is overwritten after you register this callback using preference_set_changed_cb().
  59  * @see preference_set_changed_cb()
  60  * @see preference_unset_changed_cb()
  61  * @see preference_set_boolean()
  62  * @see preference_set_int()
  63  * @see preference_set_string()
  64  * @see preference_set_double()
  65  */
  66 typedef void (*preference_changed_cb) (const char *key, void *user_data);
  67
  68
  69 /**
  70  * @brief Called to get key string, once for each key-value pair in the preference.
  71  *
  72  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  73  * @remarks You should not free the @a key returned by this function.
  74  *
  75  * @param[in] key The key of the value added to the preference
  76  * @param[in] value The value associated with the key
  77  * @param[in] user_data The user data passed from the foreach function
  78  * @return @c true to continue with the next iteration of the loop,
  79  *         otherwise @c false to break out of the loop
  80  * @pre         preference_foreach_item() will invoke this callback function.
  81  * @see         preference_foreach_item()
  82  */
  83 typedef bool (*preference_item_cb)(const char *key, void *user_data);
  84
  85
  86 /**
  87  * @brief Sets an integer value in the preference.
  88  *
  89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  90  * @param[in] key The name of the key to modify
  91  * @param[in] value  The new @c int value for the given key
  92  * @return @c 0 on success,
  93  *         otherwise a negative error value
  94  * @retval #PREFERENCE_ERROR_NONE Successful
  95  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
  96  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  97  * @see preference_get_int()
  98  */
  99 int preference_set_int(const char *key, int value);
 100
 101
 102 /**
 103  * @brief Gets an integer value from the preference.
 104  *
 105  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 106  * @param[in] key The name of the key to retrieve
 107  * @param[out] value The @c int value for the given key
 108  * @return @c 0 on success,
 109  *         otherwise a negative error value
 110  * @retval #PREFERENCE_ERROR_NONE Successful
 111  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER  Invalid parameter
 112  * @retval #PREFERENCE_ERROR_NO_KEY     Required key not available
 113  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 114  * @see preference_set_int()
 115  */
 116 int preference_get_int(const char *key, int *value);
 117
 118
 119 /**
 120  * @brief Sets a double value in the preference.
 121  *
 122  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 123  * @param[in] key The name of the key to modify
 124  * @param[in] value  The new @c double value associated with the given key
 125  * @return @c 0 on success,
 126  *         otherwise a negative error value
 127  * @retval #PREFERENCE_ERROR_NONE       Successful
 128  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER  Invalid parameter
 129  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 130  * @see preference_get_double()
 131  */
 132 int preference_set_double(const char *key, double value);
 133
 134
 135 /**
 136  * @brief Gets a double value from the preference.
 137  *
 138  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 139  * @param[in] key The name of the key to retrieve
 140  * @param[out] value  The @c double value associated with the given key
 141  * @return @c 0 on success,
 142  *         otherwise a negative error value
 143  * @retval #PREFERENCE_ERROR_NONE       Successful
 144  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER  Invalid parameter
 145  * @retval #PREFERENCE_ERROR_NO_KEY     Required key not available
 146  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 147  * @see preference_set_double()
 148  */
 149 int preference_get_double(const char *key, double *value);
 150
 151
 152 /**
 153  * @brief Sets a string value in the preference.
 154  *
 155  * @details It makes a deep copy of the added string value.
 156  *
 157  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 158  * @param[in] key The name of the key to modify
 159  * @param[in] value  The new @c string value associated with the given key
 160  * @return @c 0 on success,
 161  *         otherwise a negative error value
 162  * @retval #PREFERENCE_ERROR_NONE       Successful
 163  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER  Invalid parameter
 164  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 165  * @see preference_get_string()
 166  */
 167 int preference_set_string(const char *key, const char *value);
 168
 169
 170 /**
 171  * @brief Gets a string value from the preference.
 172  *
 173  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 174  * @remarks @a value must be released using free().
 175  * @param[in] key The name of the key to retrieve
 176  * @param[out] value The @c string value associated with the given key
 177  * @return @c 0 on success,
 178  *         otherwise a negative error value
 179  * @retval #PREFERENCE_ERROR_NONE Successful
 180  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER  Invalid parameter
 181  * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY      Out of memory
 182  * @retval #PREFERENCE_ERROR_NO_KEY     Required key not available
 183  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 184  * @see preference_set_string()
 185  */
 186 int preference_get_string(const char *key, char **value);
 187
 188
 189 /**
 190  * @brief Sets a boolean value in the preference.
 191  *
 192  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 193  * @param[in] key The name of the key to modify
 194  * @param[in] value The new @c boolean value associated with the given key
 195  * @return @c 0 on success,
 196  *         otherwise a negative error value
 197  * @retval #PREFERENCE_ERROR_NONE       Successful
 198  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER  Invalid parameter
 199  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 200  * @see preference_get_boolean()
 201  */
 202 int preference_set_boolean(const char *key, bool value);
 203
 204
 205 /**
 206  * @brief Gets a boolean value from the preference.
 207  *
 208  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 209  * @param[in] key The name of the key to retrieve
 210  * @param[out] value  The @c boolean value associated with the given key
 211  * @return @c 0 on success,
 212  *         otherwise a negative error value
 213  * @retval #PREFERENCE_ERROR_NONE       Successful
 214  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER  Invalid parameter
 215  * @retval #PREFERENCE_ERROR_NO_KEY     Required key not available
 216  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 217  * @see preference_set_boolean()
 218  */
 219 int preference_get_boolean(const char *key, bool *value);
 220
 221
 222 /**
 223  * @brief Removes any value with the given @a key from the preference.
 224  *
 225  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 226  * @param[in] key The name of the key to remove
 227  * @return @c 0 on success,
 228  *         otherwise a negative error value
 229  * @retval #PREFERENCE_ERROR_NONE Successful
 230  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 231  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 232  */
 233 int preference_remove(const char *key);
 234
 235
 236 /**
 237  * @brief Checks whether the given @a key exists in the preference.
 238  *
 239  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 240  * @param[in] key The name of the key to check
 241  * @param[out] existing  If @c true the @a key exists in the preference,
 242  *                       otherwise @c false
 243  * @return @c 0 on success,
 244  *         otherwise a negative error value
 245  * @retval #PREFERENCE_ERROR_NONE Successful
 246  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 247  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 248  */
 249 int preference_is_existing(const char *key, bool *existing);
 250
 251
 252 /**
 253  * @brief Removes all key-value pairs from the preference.
 254  *
 255  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 256  * @return @c 0 on success,
 257  *         otherwise a negative error value
 258  * @retval #PREFERENCE_ERROR_NONE Successful
 259  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 260  * @see preference_remove()
 261  */
 262 int preference_remove_all(void);
 263
 264
 265 /**
 266  * @brief Registers a callback function to be invoked when value of the given key in the preference changes.
 267  *
 268  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 269  * @param[in] key The name of the key to monitor
 270  * @param[in] callback The callback function to register
 271  * @param[in] user_data The user data to be passed to the callback function
 272  * @return @c 0 on success,
 273  *         otherwise a negative error value
 274  * @retval #PREFERENCE_ERROR_NONE Successful
 275  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 276  * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
 277  * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
 278  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 279  * @post        preference_changed_cb() will be invoked.
 280  * @see preference_unset_changed_cb()
 281  * @see preference_changed_cb()
 282  */
 283 int preference_set_changed_cb(const char *key, preference_changed_cb callback, void *user_data);
 284
 285
 286 /**
 287  * @brief Unregisters the callback function.
 288  *
 289  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 290  * @param[in] key The name of the key to monitor
 291  * @return @c 0 on success,
 292  *         otherwise a negative error value
 293  * @retval #PREFERENCE_ERROR_NONE Successful
 294  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 295  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 296  * @see preference_set_changed_cb()
 297  */
 298 int preference_unset_changed_cb(const char *key);
 299
 300
 301 /**
 302  * @brief Retrieves all key-value pairs in the preference by invoking the callback function.
 303  *
 304  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 305  * @param[in] callback The callback function to get key value once for each key-value pair in the preference
 306  * @param[in] user_data The user data to be passed to the callback function
 307  * @return @c 0 on success,
 308  *         otherwise a negative error value
 309  * @retval #PREFERENCE_ERROR_NONE Successful
 310  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 311  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
 312  * @post This function invokes preference_item_cb() repeatedly to get each key-value pair in the preference.
 313  * @see preference_item_cb()
 314  */
 315 int preference_foreach_item(preference_item_cb callback, void *user_data);
 316
 317
 318 /**
 319  * @}
 320  */
 321
 322 #ifdef __cplusplus
 323 }
 324 #endif
 325
 326 #endif /* __TIZEN_APPFW_PREFERENCE_H__ */
 327