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