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