include/vconf-buxton.h

   1 /*
   2  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   3  * Copyright (C) 2014 Intel Corporation
   4  *
   5  * Author: José Bollo <jose.bollo@open.eurogiciel.org>
   6  * Author: Hakjoo Ko <hakjoo.ko@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22 #ifndef __VCONF_BUXTON_H__
  23 #define __VCONF_BUXTON_H__
  24
  25 #define VCONF_BUXTON  "1.0"
  26
  27 /**
  28  * @addtogroup APPLICATION_FRAMEWORK
  29  * @{
  30  *
  31  * @defgroup    VCONF VConf
  32  * @author      Sangjung Woo (sangjung.woo@samsung.com)
  33  * @version     0.2
  34  * @brief       A library for reading/writing Configuration Data
  35  *
  36  * @section Header To use Them:
  37  * @code
  38  * #include <vconf.h>
  39  * @endcode
  40  *
  41  * @section Properties
  42  * - Convenient API
  43  * - Guarantee Transaction(db backend only)
  44  * - Apply Key-List concept
  45  * - Changeable Backend
  46  * - Simple Notification based on inotify
  47  *
  48  * @section Backend key has below backend.
  49  * - db => use libsqlfs ex) db/a/b
  50  * \n Lowest speed, highest robustness, correctly sync
  51  * - memory => use tmpfs ex) memory/a/b
  52  * \n Highest speed, volitile
  53  * - file => use basic file system(not support atomicity) ex) file/a/b
  54  * \n Higher speed, lower robustness(Not guarantee atomicity)
  55  *
  56  * @section example Simple Example
  57  * @code
  58  #include <stdio.h>
  59  #include <vconf.h>
  60
  61  const char *key1_name="db/test/key1";
  62
  63  int main(int argc, char **argv)
  64  {
  65    int key1_value;
  66
  67    if(vconf_set_int(key1_name,1))
  68       fprintf(stderr, "vconf_set_int FAIL\n");
  69    else
  70       printf("vconf_set_int OK\n");
  71
  72    if(vconf_get_int(key1_name, &key1_value))
  73       fprintf(stderr, "vconf_get_int FAIL\n");
  74    else
  75       printf("vconf_get_int OK(key1 value is %d)\n", key1_value);
  76
  77    return 0;
  78  }
  79  * @endcode
  80  *
  81  */
  82
  83 /**
  84  * @addtogroup VCONF
  85  * @{
  86  */
  87
  88 #include <errno.h>
  89 #include "vconf-buxton-keys.h"
  90
  91 #ifdef __cplusplus
  92 extern          "C" {
  93 #endif
  94
  95 #define VCONF_OK                 0
  96 #define VCONF_ERROR             -1
  97 #define VCONF_ERROR_FILE_NO_ENT -ENOENT
  98 #define VCONF_ERROR_FILE_PERM   -EPERM
  99
 100 /**
 101  * @brief Enumeration for uses of vconf_get().
 102  * @since_tizen 2.3
 103  * @see vconf_get()
 104  */
 105     enum get_option_t {
 106         VCONF_GET_KEY = 0,
 107             /**< get only keys */
 108         VCONF_GET_ALL,
 109             /**< get keys and directorys */
 110         VCONF_GET_DIR,
 111            /**< get only directorys */
 112         VCONF_REFRESH_ONLY,
 113             /**< get only keys */
 114         VCONF_GET_KEY_REC,
 115             /**< get only keys recursively */
 116         VCONF_GET_ALL_REC,
 117             /**< get keys and directorys recursively */
 118         VCONF_GET_DIR_REC
 119            /**< get only directorys recursively */
 120     };
 121
 122 /**
 123  * @brief  Enumeration for Definition for Enumeration type.
 124  * @since_tizen 2.3
 125  *
 126  */
 127 typedef enum get_option_t get_option_t;
 128
 129 /**
 130  * @brief Enumeration for vconf_t.
 131  * @since_tizen 2.3
 132  *
 133  */
 134     enum vconf_t {
 135         VCONF_TYPE_NONE = 0,
 136                    /**< Vconf none type for Error detection */
 137         VCONF_TYPE_STRING = 40,
 138                    /**< Vconf string type */
 139         VCONF_TYPE_INT = 41,
 140                    /**< Vconf integer type */
 141         VCONF_TYPE_DOUBLE = 42,
 142                    /**< Vconf double type */
 143         VCONF_TYPE_BOOL = 43,
 144                    /**< Vconf boolean type */
 145         VCONF_TYPE_DIR
 146                    /**< Vconf directory type */
 147     };
 148
 149
 150 /**
 151  * @brief The structure type for an opaque type. It must be used via accessor functions.
 152  * @since_tizen 2.3
 153  *
 154  * @see vconf_keynode_get_name()
 155  * @see vconf_keynode_get_type()
 156  * @see vconf_keynode_get_bool()
 157  * @see vconf_keynode_get_dbl()
 158  * @see vconf_keynode_get_int()
 159  * @see vconf_keynode_get_str()
 160  */
 161     typedef struct _keynode_t keynode_t;
 162
 163 /**
 164  * @brief The structure type for opaque type. It must be used via accessor functions.
 165  * @since_tizen 2.3
 166  *
 167  * @see vconf_keylist_new()
 168  * @see vconf_keylist_free()
 169  * @see vconf_keylist_add_bool()
 170  * @see vconf_keylist_add_str()
 171  * @see vconf_keylist_add_dbl()
 172  * @see vconf_keylist_add_int()
 173  * @see vconf_keylist_del()
 174  * @see vconf_keylist_add_null()
 175  * @see vconf_keylist_lookup()
 176  * @see vconf_keylist_nextnode()
 177  * @see vconf_keylist_rewind()
 178  */
 179     typedef struct _keylist_t keylist_t;
 180
 181
 182 /**
 183  * @brief  Called when the key is set handle.
 184  * @details  This is the signature of a callback function added with vconf_notify_key_changed() handle.
 185  *
 186  * @since_tizen 2.3
 187  *
 188  * @see keynode_t
 189  */
 190     typedef void (*vconf_callback_fn) (keynode_t *node, void *user_data);
 191
 192 /************************************************
 193  * keynode handling APIs                        *
 194  ************************************************/
 195
 196 /**
 197  * @brief Gets the key name of a keynode.
 198  *
 199  * @since_tizen 2.3
 200  *
 201  * @param[in] keynode The Key
 202  *
 203  * @return  The key name of the keynode
 204  *
 205  * @see vconf_notify_key_changed()
 206  * @see vconf_keynode_get_bool()
 207  * @see vconf_keynode_get_type()
 208  * @see vconf_keynode_get_str()
 209  * @see vconf_keynode_get_int()
 210  * @see vconf_keynode_get_dbl()
 211  * @see keynode_t
 212  * @see vconf_t
 213  */
 214     const char *vconf_keynode_get_name(keynode_t *keynode);
 215
 216 /**
 217  * @brief Gets the value type of a keynode.
 218  *
 219  * @since_tizen 2.3
 220  *
 221  * @param[in] keynode The Key
 222  *
 223  * @return  The type of the keynode
 224  *
 225  * @see vconf_notify_key_changed()
 226  * @see vconf_keynode_get_name()
 227  * @see vconf_keynode_get_bool()
 228  * @see vconf_keynode_get_str()
 229  * @see vconf_keynode_get_int()
 230  * @see vconf_keynode_get_dbl()
 231  * @see keynode_t
 232  * @see vconf_t
 233  */
 234     int vconf_keynode_get_type(keynode_t *keynode);
 235
 236 /**
 237  * @brief Gets the integer value of a keynode.
 238  *
 239  * @since_tizen 2.3
 240  *
 241  * @param[in] keynode The Key
 242  *
 243  * @return  The integer value,
 244  *          otherwise @c 0 if no value is obtained
 245  *
 246  * @see vconf_notify_key_changed()
 247  * @see vconf_keynode_get_name()
 248  * @see vconf_keynode_get_bool()
 249  * @see vconf_keynode_get_type()
 250  * @see vconf_keynode_get_str()
 251  * @see vconf_keynode_get_dbl()
 252  * @see keynode_t
 253  * @see vconf_t
 254  */
 255     int vconf_keynode_get_int(keynode_t *keynode);
 256
 257 /**
 258  * @brief Gets the double value of a keynode.
 259  *
 260  * @since_tizen 2.3
 261  *
 262  * @param[in] keynode The Key
 263  *
 264  * @return  The double value,
 265  *          otherwise @c 0.0 if no value is obtained
 266  *
 267  * @see vconf_notify_key_changed()
 268  * @see vconf_keynode_get_name()
 269  * @see vconf_keynode_get_bool()
 270  * @see vconf_keynode_get_type()
 271  * @see vconf_keynode_get_str()
 272  * @see vconf_keynode_get_int()
 273  * @see keynode_t
 274  * @see vconf_t
 275  */
 276     double vconf_keynode_get_dbl(keynode_t *keynode);
 277
 278 /**
 279  * @brief Gets the boolean value of a keynode.
 280  *
 281  * @since_tizen 2.3
 282  *
 283  * @param[in] keynode The Key
 284  *
 285  * @return  The boolean value,
 286  *          otherwise @c -1 on error \n
 287  *          Integer value  @c 1 is 'True', and @c 0 is 'False'.
 288  *
 289  * @see vconf_notify_key_changed()
 290  * @see vconf_keynode_get_name()
 291  * @see vconf_keynode_get_type()
 292  * @see vconf_keynode_get_str()
 293  * @see vconf_keynode_get_int()
 294  * @see vconf_keynode_get_dbl()
 295  * @see keynode_t
 296  * @see vconf_t
 297  */
 298     int vconf_keynode_get_bool(keynode_t *keynode);
 299
 300 /**
 301  * @brief Gets the string value of a keynode.
 302  *
 303  * @since_tizen 2.3
 304  *
 305  * @param[in] keynode The Key
 306  *
 307  * @return  The string value,
 308  *          otherwise @c NULL if no value is obtained
 309  *
 310  * @see vconf_notify_key_changed()
 311  * @see vconf_keynode_get_name()
 312  * @see vconf_keynode_get_bool()
 313  * @see vconf_keynode_get_type()
 314  * @see vconf_keynode_get_int()
 315  * @see vconf_keynode_get_dbl()
 316  * @see keynode_t
 317  * @see vconf_t
 318  */
 319     char *vconf_keynode_get_str(keynode_t *keynode);
 320
 321
 322 /************************************************
 323  * keylist handling APIs
 324  ************************************************/
 325
 326 /**
 327  * @brief Allocates, initializes and returns a new keylist object.
 328  * @details You must release the return value keylist_t* pointer using vconf_keylist_free().
 329  *
 330  * @since_tizen 2.3
 331  *
 332  * @return  The pointer of New keylist,
 333  *          otherwise @c NULL on error
 334  *
 335  * @see vconf_set()
 336  * @see vconf_get()
 337  * @see vconf_keylist_new()
 338  * @see vconf_keylist_free()
 339  */
 340     keylist_t *vconf_keylist_new(void);
 341
 342 /**
 343  * @brief Moves the current keynode position to the first item.
 344  *
 345  * @since_tizen 2.3
 346  *
 347  * @param[in] keylist  The Key List
 348  *
 349  * @return  @c 0 on success,
 350  *          otherwise -1 on error
 351  *
 352  * @see vconf_set()
 353  * @see vconf_get()
 354  * @see vconf_keylist_nextnode()
 355  * @see vconf_keylist_rewind()
 356  * @see vconf_keylist_nextnode()
 357  *
 358  * @par example
 359  * @code
 360     int r =0;
 361     keylist_t* pKeyList = NULL;
 362     pKeyList = vconf_keylist_new();
 363
 364     r = vconf_get(pKeyList, KEY_PARENT, VCONF_GET_KEY);
 365     if (r) {
 366     tet_infoline("vconf_get() failed in positive test case");
 367     tet_result(TET_FAIL);
 368     return;
 369     }
 370
 371     vconf_keylist_nextnode(pKeyList);
 372     vconf_keylist_nextnode(pKeyList);
 373
 374     // Move first position from KeyList
 375     r = vconf_keylist_rewind(pKeyList);
 376     if (r<0) {
 377     tet_infoline("vconf_keylist_rewind() failed in positive test case");
 378     tet_result(TET_FAIL);
 379     return;
 380     }
 381
 382     while(vconf_keylist_nextnode(pKeyList)) ;
 383  * @endcode
 384  */
 385     int vconf_keylist_rewind(keylist_t *keylist);
 386
 387 /**
 388  * @brief Destroys a keylist.
 389  * @details After calling vconf_keylist_new(), you must call this function to release internal memory.
 390  *
 391  * @since_tizen 2.3
 392  *
 393  * @param[in] keylist  The Key List
 394  *
 395  * @return  @c 0 on success,
 396  *          otherwise @c -1 on error
 397  *
 398  * @see vconf_set()
 399  * @see vconf_get()
 400  * @see vconf_keylist_new()
 401  */
 402     int vconf_keylist_free(keylist_t *keylist);
 403
 404 /**
 405  * @brief Looks for a keynode contained in a keylist that matches the keyname.
 406  *
 407  * @since_tizen 2.3
 408  *
 409  * @param[in]  keylist      The Key List
 410  * @param[in]  keyname      The key to find
 411  * @param[out] return_node  The pointer of the keynode to set
 412  *
 413  * @return  The type of the found key that is vconf_t enumeration value
 414  *
 415  * @see vconf_set()
 416  * @see vconf_get()
 417  * @see keynode_t
 418  * @see vconf_t
 419  * @par example
 420  * @code
 421 #include <stdio.h>
 422 #include <vconf.h>
 423
 424 int main()
 425 {
 426     int r = 0;
 427     int nResult = 0;
 428     keylist_t* pKeyList = NULL;
 429     keynode_t *pKeyNode;
 430
 431     pKeyList = vconf_keylist_new();
 432     r = vconf_get(pKeyList, KEY_PARENT, VCONF_GET_KEY);
 433     if (r<0) {
 434         printf("vconf_get() failed in positive test case");
 435         return -1;
 436     }
 437
 438     r = vconf_keylist_lookup(pKeyList, KEY_02, &pKeyNode);
 439     if (r<0) {
 440         printf("vconf_get() failed in positive test case");
 441         return -1;
 442     }
 443
 444     nResult = vconf_keynode_get_int(pKeyNode);
 445     if(nResult !=KEY_02_INT_VALUE)
 446     {
 447         printf("vconf_get() failed in positive test case");
 448         return -1;
 449
 450     }
 451
 452     vconf_keylist_free(pKeyList);
 453     return 0;
 454 }
 455  * @endcode
 456  */
 457     int vconf_keylist_lookup(keylist_t *keylist, const char *keyname,
 458                  keynode_t **return_node);
 459
 460 /**
 461  * @brief Gets the next key in a keylist.
 462  * @details The next key is known by the keylist internal cursor.
 463  *
 464  * @since_tizen 2.3
 465  *
 466  * @param[in] keylist  The Key List
 467  *
 468  * @return  The next Keynode,
 469  *          otherwise @c NULL on error
 470  *
 471  * @see vconf_set()
 472  * @see vconf_get()
 473  * @see vconf_keylist_rewind()
 474  * @see vconf_keylist_nextnode()
 475  * @see keynode_t
 476  */
 477     keynode_t *vconf_keylist_nextnode(keylist_t *keylist);
 478
 479 /**
 480  * @brief Appends a new keynode containing an integer value to a keylist.
 481  * @details If the same keyname exists, the keynode will change.
 482  *
 483  * @since_tizen 2.3
 484  *
 485  * @param[in] keylist  The Key List
 486  * @param[in] keyname  The key
 487  * @param[in] value    The integer value
 488  *
 489  * @return  The number of keynode included in the keylist,
 490  *          otherwise @c -1 on error
 491  *
 492  * @see vconf_set()
 493  * @see vconf_get()
 494  */
 495     int vconf_keylist_add_int(keylist_t *keylist, const char *keyname,
 496                   const int value);
 497
 498 /**
 499  * @brief Appends a new keynode containing a boolean value to a keylist.
 500  * @details If the same keyname exist, the keynode will change.
 501  *
 502  * @since_tizen 2.3
 503  *
 504  * @param[in] keylist  The Key List
 505  * @param[in] keyname  The key
 506  * @param[in] value    The boolean value
 507  *
 508  * @return  The number of keynodes included in the keylist,
 509  *          otherwise @c -1 on error
 510  *
 511  * @see vconf_set()
 512  * @see vconf_get()
 513  * @see vconf_keylist_add_int()
 514  * @see vconf_keylist_add_str()
 515  * @see vconf_keylist_add_dbl()
 516  * @see vconf_keylist_add_bool()
 517  * @see vconf_keylist_del()
 518  * @see vconf_keylist_add_null()
 519  */
 520     int vconf_keylist_add_bool(keylist_t *keylist, const char *keyname,
 521                    const int value);
 522
 523 /**
 524  * @brief Appends a new keynode containing a double value to a keylist.
 525  * @details If the same keyname exist, the keynode will change.
 526  *
 527  * @since_tizen 2.3
 528  *
 529  * @param[in] keylist  The Key List
 530  * @param[in] keyname  The key
 531  * @param[in] value    The double value
 532  *
 533  * @return  The number of the keynodes included in the keylist,
 534  *          otherwise @c -1 on error
 535  *
 536  * @see vconf_set()
 537  * @see vconf_get()
 538  * @see vconf_keylist_add_int()
 539  * @see vconf_keylist_add_str()
 540  * @see vconf_keylist_add_dbl()
 541  * @see vconf_keylist_add_bool()
 542  * @see vconf_keylist_del()
 543  * @see vconf_keylist_add_null()
 544  */
 545     int vconf_keylist_add_dbl(keylist_t *keylist, const char *keyname,
 546                   const double value);
 547
 548 /**
 549  * @brief Appends a new keynode containing a string to a keylist.
 550  * @details If the same keyname exist, the keynode will change.
 551  *
 552  * @since_tizen 2.3
 553  *
 554  * @remarks The size limit of value is 4K.
 555  *
 556  * @param[in] keylist  The Key List
 557  * @param[in] keyname  The key
 558  * @param[in] value    The pointer of string value
 559  *
 560  * @return  The number of keynodes included in the keylist,
 561  *          otherwise @c -1 on error
 562  *
 563  * @see vconf_set()
 564  * @see vconf_get()
 565  * @see vconf_keylist_add_int()
 566  * @see vconf_keylist_add_str()
 567  * @see vconf_keylist_add_dbl()
 568  * @see vconf_keylist_add_bool()
 569  * @see vconf_keylist_del()
 570  * @see vconf_keylist_add_null()
 571  */
 572     int vconf_keylist_add_str(keylist_t *keylist, const char *keyname,
 573                   const char *value);
 574
 575 /**
 576  * @brief Appends a new keynode to a keylist without a value.
 577  * @details Uses for vconf_get().
 578  *
 579  * @since_tizen 2.3
 580  *
 581  * @param[in] keylist  The Key List
 582  * @param[in] keyname  The key
 583  *
 584  * @return  The number of the keynodes included in the keylist,
 585  *          otherwise @c -1 on error
 586  *
 587  * @see vconf_set()
 588  * @see vconf_get()
 589  * @see vconf_keylist_add_int()
 590  * @see vconf_keylist_add_str()
 591  * @see vconf_keylist_add_dbl()
 592  * @see vconf_keylist_add_bool()
 593  * @see vconf_keylist_del()
 594  * @see vconf_keylist_add_null()
 595  */
 596     int vconf_keylist_add_null(keylist_t *keylist, const char *keyname);
 597
 598 /**
 599  * @brief Removes the keynode that matches the given keyname.
 600  *
 601  * @since_tizen 2.3
 602  *
 603  * @param[in] keylist The keylist containing the keyname
 604  * @param[in] keyname The key
 605  *
 606  * @return  @c 0 on success,
 607  *          @c -1 if invalid parameter),
 608  *          otherwise @c -2 (Not exist keyname in keylist) on error
 609  *
 610  * @see vconf_set()
 611  * @see vconf_get()
 612  * @see vconf_keylist_add_int()
 613  * @see vconf_keylist_add_str()
 614  * @see vconf_keylist_add_dbl()
 615  * @see vconf_keylist_add_bool()
 616  * @see vconf_keylist_del()
 617  * @see vconf_keylist_add_null()
 618  */
 619     int vconf_keylist_del(keylist_t *keylist, const char *keyname);
 620
 621 /************************************************
 622  * setting APIs                                 *
 623  ************************************************/
 624
 625 /**
 626  * @brief Sets the keys included in a keylist.
 627  * @details If you use DB backend, the keylist is handled as one transaction.
 628  *
 629  * @since_tizen 2.3
 630  *
 631  * @param[in] keylist  The keylist which should contain changed keys
 632  *
 633  * @return  @c 0 on success,
 634  *          otherwise @c -1 on error
 635  *
 636  * @see vconf_set()
 637  * @see vconf_get()
 638  * @see vconf_keylist_add_int()
 639  * @see vconf_keylist_add_str()
 640  * @see vconf_keylist_add_dbl()
 641  * @see vconf_keylist_add_bool()
 642  * @see vconf_keylist_del()
 643  * @see vconf_keylist_add_null()
 644  *
 645  * @par example
 646  * @code
 647 #include <stdio.h>
 648 #include <vconf.h>
 649
 650 int main()
 651 {
 652    keylist_t *kl=NULL;
 653    const char *keyname_list[3]={"db/test/key1", "db/test/key2", "db/test/key3"};
 654
 655    // Transaction Test(all or nothing is written)
 656    kl = vconf_keylist_new();
 657
 658    vconf_keylist_add_int(kl, keyname_list[0], 1);
 659    vconf_keylist_add_str(kl, keyname_list[1], "transaction Test");
 660    vconf_keylist_add_dbl(kl, keyname_list[2], 0.3);
 661    if(vconf_set(kl))
 662       fprintf(stderr, "nothing is written\n");
 663    else
 664       printf("everything is written\n");
 665
 666    vconf_keylist_free(kl);
 667
 668    // You can set items which have different backend.
 669    kl = vconf_keylist_new();
 670
 671    vconf_keylist_add_int(kl, "memory/a/xxx1", 4);
 672    vconf_keylist_add_str(kl, "file/a/xxx2", "test 3");
 673    vconf_keylist_add_dbl(kl, "db/a/xxx3", 0.3);
 674    vconf_set(kl)
 675
 676    vconf_keylist_free(kl);
 677    return 0;
 678 }
 679  * @endcode
 680  */
 681     int vconf_set(keylist_t *keylist);
 682
 683 /**
 684  * @brief Sets the integer value of the given key.
 685  *
 686  * @since_tizen 2.3
 687  *
 688  * @param[in]   in_key  The key
 689  * @param[in]   intval  The integer value to set \n
 690  *                      @c 0 is also allowed as a value.
 691  *
 692  * @return  @c 0 on success,
 693  *          otherwise @c -1 on error
 694  *
 695  * @see vconf_set_bool()
 696  * @see vconf_set_dbl()
 697  * @see vconf_set_str()
 698  */
 699     int vconf_set_int(const char *in_key, const int intval);
 700
 701 /**
 702  * @brief Sets the boolean value of the given key.
 703  *
 704  * @since_tizen 2.3
 705  *
 706  * @param[in]   in_key   The key
 707  * @param[in]   boolval  The Boolean value( @c 1 or @c 0) to set
 708  *                       Integer value @c 1 is 'True', and @c 0 is 'False'.
 709  *
 710  * @return  @c 0 on success,
 711  *          otherwise @c -1 on error
 712  *
 713  * @see vconf_set_int()
 714  * @see vconf_set_dbl()
 715  * @see vconf_set_str()
 716  *
 717  * @par example
 718  * @code
 719 #include <stdio.h>
 720 #include <vconf.h>
 721
 722  const char *key1_name="memory/test/key1";
 723
 724  int main(int argc, char **argv)
 725  {
 726    int key1_value;
 727
 728    if(vconf_set_bool(key1_name, 1))
 729       fprintf(stderr, "vconf_set_bool FAIL\n");
 730    else
 731       printf("vconf_set_bool OK\n");
 732
 733    if(vconf_get_bool(key1_name, &key1_value))
 734       fprintf(stderr, "vconf_get_bool FAIL\n");
 735    else
 736       printf("vconf_get_bool OK(key1 value is %d)\n", key1_value);
 737
 738    return 0;
 739  }
 740  * @endcode
 741  */
 742     int vconf_set_bool(const char *in_key, const int boolval);
 743
 744 /**
 745  * @brief Sets the double value of the given key.
 746  *
 747  * @since_tizen 2.3
 748  *
 749  * @param[in]   in_key  The key
 750  * @param[in]   dblval  The double value to set \n
 751  *                      @c 0.0 is also allowed as a value.
 752  *
 753  * @return  @c 0 on success,
 754  *          otherwise @c -1 on error
 755  *
 756  * @see vconf_set_int()
 757  * @see vconf_set_bool()
 758  * @see vconf_set_str()
 759  */
 760     int vconf_set_dbl(const char *in_key, const double dblval);
 761
 762 /**
 763  * @brief Sets the string value of the given key.
 764  *
 765  * @since_tizen 2.3
 766  *
 767  * @remarks The size limit of value is 4K.
 768  *
 769  * @param[in]   in_key  The key
 770  * @param[in]   strval  The string value to set
 771  *
 772  * @return  @c 0 on success,
 773  *          otherwise -1 on error
 774  *
 775  * @see vconf_set_bool()
 776  * @see vconf_set_dbl()
 777  * @see vconf_set_int()
 778  */
 779     int vconf_set_str(const char *in_key, const char *strval);
 780
 781 /**
 782  * @brief Gets the keys or subdirectory in in_parentDIR.
 783  * @details If the keylist has any key information, vconf only retrieves the keys.
 784  *          This is not recursive.
 785  *
 786  * @since_tizen 2.3
 787  *
 788  * @param[in]    keylist       The keylist created by vconf_keylist_new()
 789  * @param[in]    in_parentDIR  The parent DIRECTORY of needed keys
 790  * @param[in]    option        The options \n
 791  *                             VCONF_GET_KEY|VCONF_GET_DIR|VCONF_GET_ALL
 792  *
 793  * @return  @c 0 on success,
 794  *          otherwise @c -1 on error
 795  *
 796  * @par example
 797  * @code
 798 #include <stdio.h>
 799 #include <vconf.h>
 800
 801 int main()
 802 {
 803    keylist_t *kl=NULL;
 804    keynode_t *temp_node;
 805    const char *vconfkeys1="db/test/key1";
 806    const char *parent_dir="db/test";
 807
 808    kl = vconf_keylist_new();
 809    if(vconf_get(kl, parent_dir, 0))
 810       fprintf(stderr, "vconf_get FAIL(%s)", vconfkeys1);
 811    else
 812       printf("vconf_get OK(%s)", vconfkeys1);
 813
 814    while((temp_node = vconf_keylist_nextnode(kl))) {
 815       switch(vconf_keynode_get_type(temp_node)) {
 816     case VCONF_TYPE_INT:
 817         printf("key = %s, value = %d\n",
 818             vconf_keynode_get_name(temp_node), vconf_keynode_get_int(temp_node));
 819         break;
 820     case VCONF_TYPE_BOOL:
 821         printf("key = %s, value = %d\n",
 822             vconf_keynode_get_name(temp_node), vconf_keynode_get_bool(temp_node));
 823         break;
 824     case VCONF_TYPE_DOUBLE:
 825         printf("key = %s, value = %f\n",
 826             vconf_keynode_get_name(temp_node), vconf_keynode_get_dbl(temp_node));
 827         break;
 828     case VCONF_TYPE_STRING:
 829         printf("key = %s, value = %s\n",
 830             vconf_keynode_get_name(temp_node), vconf_keynode_get_str(temp_node));
 831         break;
 832     default:
 833         printf("Unknown Type\n");
 834       }
 835    }
 836    vconf_keylist_free(kl);
 837 }
 838  * @endcode
 839  */
 840     int vconf_get(keylist_t *keylist, const char *in_parentDIR, get_option_t option);
 841
 842 /**
 843  * @brief Gets the integer value of the given key.
 844  *
 845  * @since_tizen 2.3
 846  *
 847  * @param[in]   in_key  The key
 848  * @param[out]  intval  The output buffer
 849  *
 850  * @return  @c 0 on success,
 851  *          otherwise @c -1 on error
 852  *
 853  * @see vconf_get_bool()
 854  * @see vconf_get_dbl()
 855  * @see vconf_get_str()
 856  *
 857  * @par example
 858  * @code
 859 #include <stdio.h>
 860 #include <vconf.h>
 861
 862 const char *key1_name="db/test/key1";
 863
 864 int main(int argc, char **argv)
 865 {
 866    int key1_value;
 867
 868    if(vconf_set_int(key1_name,1))
 869       fprintf(stderr, "vconf_set_int FAIL\n");
 870    else
 871       printf("vconf_set_int OK\n");
 872
 873    if(vconf_get_int(key1_name, &key1_value))
 874       fprintf(stderr, "vconf_get_int FAIL\n");
 875    else
 876       printf("vconf_get_int OK(key1 value is %d)\n", key1_value);
 877
 878    return 0;
 879 }
 880  * @endcode
 881  */
 882     int vconf_get_int(const char *in_key, int *intval);
 883
 884 /**
 885  * @brief Gets the boolean value (@c 1 or @c 0) of the given key.
 886  *
 887  * @since_tizen 2.3
 888  *
 889  * @param[in]   in_key   The key
 890  * @param[out]  boolval  The output buffer
 891  *
 892  * @return  @c 0 on success,
 893  *          otherwise @c -1 on error
 894  *
 895  * @see vconf_get_int()
 896  * @see vconf_get_dbl()
 897  * @see vconf_get_str()
 898  */
 899     int vconf_get_bool(const char *in_key, int *boolval);
 900
 901 /**
 902  * @brief Gets the double value of the given key.
 903  *
 904  * @since_tizen 2.3
 905  *
 906  * @param[in]  in_key  The key
 907  * @param[out] dblval  The output buffer
 908  *
 909  * @return  @c 0 on success,
 910  *          otherwise @c -1 on error
 911  *
 912  * @see vconf_get_int()
 913  * @see vconf_get_bool()
 914  * @see vconf_get_str()
 915  */
 916     int vconf_get_dbl(const char *in_key, double *dblval);
 917
 918 /**
 919  * @brief Gets the string value of the given key.
 920  * @details You have to free this returned value.
 921  *
 922  * @since_tizen 2.3
 923  *
 924  * @param[in] in_key  The key
 925  *
 926  * @return  The allocated pointer of key value on success,
 927  *          otherwise @c NULL on error
 928  *
 929  * @see vconf_get_int()
 930  * @see vconf_get_dbl()
 931  * @see vconf_get_bool()
 932  *
 933  * @par example
 934  * @code
 935    #include <stdio.h>
 936    #include <vconf.h>
 937
 938    char *get_str=vconf_get_str("db/test/test1");
 939    if(get_str) {
 940       printf("vconf_get_str OK(value = %s)", get_str);
 941       free(get_str);
 942    }else
 943       fprintf(stderr, "vconf_get_str FAIL");
 944  * @endcode
 945  */
 946     char *vconf_get_str(const char *in_key);
 947
 948 /**
 949  * @brief Deletes the given key from the backend system.
 950  *
 951  * @since_tizen 2.3
 952  *
 953  * @param[in] in_key  The key
 954  *
 955  * @return  @c 0 on success,
 956  *          otherwise @c -1 on error
 957  */
 958     int vconf_unset(const char *in_key);
 959
 960 /**
 961  * @brief Synchronizes the given key (only file backend) with the storage device.
 962  *
 963  * @since_tizen 2.3
 964  *
 965  * @param[in] in_key  The key
 966  *
 967  * @return  @c 0 on success,
 968  *          otherwise @c -1 on error
 969  *
 970  * @par example
 971  * @code
 972  if(vconf_set_int("file/test/key1",1))
 973     fprintf(stderr, "vconf_set_int FAIL\n");
 974  else {
 975     printf("vconf_set_int OK\n");
 976     vconf_sync_key("file/test/key1");
 977  }
 978  * @endcode
 979  */
 980     int vconf_sync_key(const char *in_key);
 981
 982 /**
 983  * @brief Deletes all keys and directories below the given directory from the backend system.
 984  *
 985  * @since_tizen 2.3
 986  *
 987  * @param[in] in_dir  The directory name for removal
 988  *
 989  * @return  @c 0 on success,
 990  *          otherwise @c -1 on error
 991  *
 992  * @par example
 993  * @code
 994    vconf_set_int("db/test/key1",1);
 995    vconf_set_int("db/test/test1/key1",1);
 996    vconf_set_int("db/test/test2/key1",1);
 997    vconf_set_int("db/test/key2",1);
 998
 999    if(vconf_unset_recursive("db/test"))
1000       fprintf(stderr, "vconf_unset_recursive FAIL\n");
1001    else
1002       printf("vconf_unset_recursive OK(deleted db/test\n");
1003
1004  * @endcode
1005  */
1006     int vconf_unset_recursive(const char *in_dir);
1007
1008 /**
1009  * @brief Adds a change callback for the given key, which is called when the key is set or unset.
1010  * @details The changed information (#keynode_t) of the key is delivered to #vconf_callback_fn,
1011  *          or if the key is deleted, the @link #keynode_t keynode @endlink has #VCONF_TYPE_NONE as type.
1012  *
1013  * @details Multiple vconf_callback_fn functions may exist for one key.
1014  *
1015  * @details The callback is issued in the context of the glib main loop.
1016  *
1017  * @since_tizen 2.3
1018  *
1019  * @remarks: This callback mechanism DOES NOT GUARANTEE consistency of data change. For example,
1020  *           When you have a callback for a certain key, assume that two or more processes are trying to
1021  *           change the value of the key competitively. In this case, the callback function will always
1022  *           get the 'CURRENT' value, not the value which raised the notification and caused the callback call.
1023  *           So, do not use vconf callback when competitive write for a key is happening. In such case, use
1024  *           socket-based IPC (dbus or something else) instead.
1025  *
1026  * @param[in] in_key     The key
1027  * @param[in] cb         The callback function
1028  * @param[in] user_data  The callback data
1029  *
1030  * @return  @c 0 on success,
1031  *          otherwise @c -1 on error
1032  *
1033  * @see vconf_ignore_key_changed
1034  *
1035  * @par example
1036  * @code
1037  void test_cb(keynode_t *key, void* data)
1038  {
1039     switch(vconf_keynode_get_type(key))
1040     {
1041        case VCONF_TYPE_INT:
1042     printf("key = %s, value = %d(int)\n",
1043         vconf_keynode_get_name(key), vconf_keynode_get_int(key));
1044     break;
1045        case VCONF_TYPE_BOOL:
1046     printf("key = %s, value = %d(bool)\n",
1047         vconf_keynode_get_name(key), vconf_keynode_get_bool(key));
1048     break;
1049        case VCONF_TYPE_DOUBLE:
1050     printf("key = %s, value = %f(double)\n",
1051         vconf_keynode_get_name(key), vconf_keynode_get_dbl(key));
1052     break;
1053        case VCONF_TYPE_STRING:
1054     printf("key = %s, value = %s(string)\n",
1055         vconf_keynode_get_name(key), vconf_keynode_get_str(key));
1056     break;
1057        default:
1058     fprintf(stderr, "Unknown Type(%d)\n", vconf_keynode_get_type(key));
1059     break;
1060     }
1061     return;
1062  }
1063
1064  int main()
1065  {
1066     int i;
1067     GMainLoop *event_loop;
1068
1069     g_type_init();
1070
1071     vconf_notify_key_changed("db/test/test1", test_cb, NULL);
1072
1073     event_loop = g_main_loop_new(NULL, FALSE);
1074     g_main_loop_run(event_loop);
1075
1076     vconf_ignore_key_changed("db/test/test1", test_cb);
1077     return 0;
1078  }
1079  * @endcode
1080  */
1081     int vconf_notify_key_changed(const char *in_key, vconf_callback_fn cb,
1082                      void *user_data);
1083
1084 /**
1085  * @brief Removes a change callback for the given key,
1086  *        which was added by vconf_notify_key_changed().
1087  *
1088  * @since_tizen 2.3
1089  *
1090  * @param[in]   in_key  The key
1091  * @param[in]   cb      The callback function
1092  *
1093  * @return @c 0 on success,
1094  *         otherwise @c -1 on error
1095  *
1096  * @see vconf_notify_key_changed()
1097  */
1098     int vconf_ignore_key_changed(const char *in_key, vconf_callback_fn cb);
1099
1100 /**
1101  * This function sorts the list in alphabetical order (with LANG=C)
1102  * @param[in] keylist Key List
1103  * @return 0 if done, -1 on error
1104  * @pre None
1105  * @post None
1106  * @remarks None
1107  */
1108     int             vconf_keylist_sort(keylist_t * keylist);
1109
1110 /**
1111  * This function retrieves the keys or subdirectory in in_parentDIR.<br>
1112  * @param[in]   keylist keylist created by vconf_keylist_new(), MUST be empty
1113  * @param[in]   in_parentDIR parent DIRECTORY of needed keys
1114  * @param[in]   option VCONF_GET_KEY|VCONF_GET_DIR|VCONF_GET_ALL|VCONF_GET_KEY_REC|VCONF_GET_DIR_REC|VCONF_GET_ALL_REC
1115  * @return 0 on success, -1 on error
1116  * @pre None
1117  * @post None
1118  * @remkar None
1119  * @par example
1120  * @code
1121 #include <stdio.h>
1122 #include <vconf.h>
1123
1124 int main()
1125 {
1126    keylist_t *kl=NULL;
1127    keynode_t *temp_node;
1128    const char *vconfkeys1="db/test/key1";
1129    const char *parent_dir="db/test";
1130
1131    kl = vconf_keylist_new();
1132    if(vconf_scan(kl, parent_dir, VCONF_GET_KEY))
1133       fprintf(stderr, "vconf_get FAIL(%s)", vconfkeys1);
1134    else
1135       printf("vconf_get OK(%s)", vconfkeys1);
1136
1137    while((temp_node = vconf_keylist_nextnode(kl))) {
1138       switch(vconf_keynode_get_type(temp_node)) {
1139         case VCONF_TYPE_INT:
1140                 printf("key = %s, value = %d\n",
1141                         vconf_keynode_get_name(temp_node), vconf_keynode_get_int(temp_node));
1142                 break;
1143         case VCONF_TYPE_BOOL:
1144                 printf("key = %s, value = %d\n",
1145                         vconf_keynode_get_name(temp_node), vconf_keynode_get_bool(temp_node));
1146                 break;
1147         case VCONF_TYPE_DOUBLE:
1148                 printf("key = %s, value = %f\n",
1149                         vconf_keynode_get_name(temp_node), vconf_keynode_get_dbl(temp_node));
1150                 break;
1151         case VCONF_TYPE_STRING:
1152                 printf("key = %s, value = %s\n",
1153                         vconf_keynode_get_name(temp_node), vconf_keynode_get_str(temp_node));
1154                 break;
1155         default:
1156                 printf("Unknown Type\n");
1157       }
1158    }
1159    vconf_keylist_free(kl);
1160 }
1161  * @endcode
1162  */
1163     int             vconf_scan(keylist_t * keylist,
1164                                const char *in_parentDIR,
1165                                get_option_t option);
1166
1167 /**
1168  * This function reads the database to refresh the values of
1169  * the keys in 'keylist'.
1170  * @param[in]   keylist the keylist whose values have to be refreshed
1171  * @return 0 on success, -1 on error
1172  * @see vconf_keylist_lookup, vconf_keylist_nextnode, vconf_keylist_rewind
1173  */
1174     int             vconf_refresh(keylist_t * keylist);
1175
1176 /**
1177  * This function set the smack label of its keys
1178  * @param[in] keylist Key List
1179  * @param[in] label The label to set
1180  * @return 0 if done, -1 on error
1181  * @pre None
1182  * @post None
1183  * @remarks None
1184  */
1185
1186     int             vconf_set_labels(keylist_t * keylist, const char *label);
1187
1188 /**
1189  * This function set the smack label of its keys
1190  * @param[in] keylist Key List
1191  * @param[in] label The label to set
1192  * @return 0 if done, -1 on error
1193  * @pre None
1194  * @post None
1195  * @remarks None
1196  */
1197     int             vconf_set_label(const char *keyname, const char *label);
1198
1199 /**
1200  * Set the default group of key lists created using vconf_keylist_new.
1201  * @param[in] groupname The name of the default group to bind to
1202  * @return 0 in case of success or -1 in case of error of allocation
1203  * @see vconf_keylist_new()
1204  */
1205     int             vconf_set_default_group(const char *groupname);
1206
1207 /**
1208  * This function checks if the given key exists from backend system.
1209  * @param[in]   keyname key
1210  * @return 0 on success: exists, -1 on error or not existing
1211  */
1212     int             vconf_exists(const char *keyname);
1213
1214 /**
1215  * This function returns result of last api call
1216  * @return The result of last api call
1217  * @retval #VCONF_OK                 Successful
1218  * @retval #VCONF_ERROR              General error
1219  * @retval #VCONF_ERROR_FILE_NO_ENT  No such key
1220  * @retval #VCONF_ERROR_FILE_PERM    Permission denied
1221  */
1222     int             vconf_get_ext_errno(void);
1223 /**
1224  * @}
1225  */
1226
1227 #ifdef __cplusplus
1228 }
1229 #endif
1230
1231 #endif              /* __VCONF_BUXTON_H__ */