include/bundle.h

   1 /*
   2  * bundle
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jayoun Lee <airjany@samsung.com>, Sewook Park <sewook7.park@samsung.com>,
   7  * Jaeho Lee <jaeho81.lee@samsung.com>
   8  *
   9  * Licensed under the Apache License, Version 2.0 (the "License");
  10  * you may not use this file except in compliance with the License.
  11  * You may obtain a copy of the License at
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  *
  21  */
  22
  23
  24 #ifndef __BUNDLE_H__
  25 #define __BUNDLE_H__
  26
  27 /**
  28  * @file bundle.h
  29  * @version 0.1
  30  * @brief    This file declares API of bundle library
  31  */
  32
  33 /**
  34  * @addtogroup APPLICATION_FRAMEWORK
  35  * @{
  36  *
  37  * @defgroup bundle
  38  * @version    0.1
  39  *
  40  * @section    Header to use them:
  41  * @code
  42  * #include <bundle.h>
  43  * @endcode
  44  *
  45  * @addtogroup bundle
  46  * @{
  47  */
  48
  49 #include <errno.h>
  50 #include <stddef.h>
  51
  52 #ifdef __cplusplus
  53 extern "C" {
  54 # endif
  55
  56 #define API     __attribute__((visibility("default")))
  57 #define likely(x) __builtin_expect(x,1)
  58 #define unlikely(x) __builtin_expect(x,0)
  59
  60 /**
  61  * bundle is an opaque type pointing a bundle object
  62  */
  63 typedef struct _bundle_t bundle;
  64
  65 /**
  66  * bundle_raw is an encoded data type
  67  * @see bundle_encode()
  68  * @see bundle_decode()
  69  */
  70 typedef unsigned char bundle_raw;
  71
  72
  73 /**
  74  * Each bundle keyval have a type.
  75  */
  76 enum bundle_type_property {
  77         BUNDLE_TYPE_ARRAY = 0x0100,
  78         BUNDLE_TYPE_PRIMITIVE = 0x0200,
  79         BUNDLE_TYPE_MEASURABLE = 0x0400
  80 };
  81
  82 enum bundle_type {
  83         BUNDLE_TYPE_NONE = -1,
  84         BUNDLE_TYPE_ANY = 0,
  85         BUNDLE_TYPE_STR = 1 | BUNDLE_TYPE_MEASURABLE,   /* Default */
  86         BUNDLE_TYPE_STR_ARRAY = BUNDLE_TYPE_STR | BUNDLE_TYPE_ARRAY | BUNDLE_TYPE_MEASURABLE,
  87         BUNDLE_TYPE_BYTE = 2,
  88         BUNDLE_TYPE_BYTE_ARRAY = BUNDLE_TYPE_BYTE | BUNDLE_TYPE_ARRAY
  89 };
  90
  91 /**
  92  * A keyval object in a bundle.
  93  * @see bundle_iterator_t
  94  */
  95 typedef struct keyval_t bundle_keyval_t;
  96
  97
  98 /**
  99  * bundle_iterator is a new iterator function type for bundle_foreach()
 100  * @see bundle_foreach()
 101  */
 102 typedef void (*bundle_iterator_t) (
 103                 const char *key,
 104                 const int type,
 105                 const bundle_keyval_t *kv,
 106                 void *user_data
 107 );
 108
 109
 110 /**
 111  * bundle_iterate_cb_t is an iterator function type for bundle_iterate()
 112  * @see bundle_iterate()
 113  * @remark This type is obsolete. Do not use this type any more.
 114  */
 115 typedef void (*bundle_iterate_cb_t) (const char *key, const char *val, void *data);
 116
 117
 118 /**
 119  * @brief       Create a bundle object.
 120  * @pre                 None
 121  * @post                None
 122  * @see                 bundle_free()
 123  * @return      bundle object
 124  * @retval      NULL    on failure creating an object
 125  * @remark      When NULL is returned, errno is set to one of the following values; \n
 126  *                      ENOMEM : No memory to create an object
 127  *
 128  @code
 129  #include <bundle.h>
 130  bundle *b = bundle_create(); // Create new bundle object
 131  bundle_free(b); // free bundle
 132  @endcode
 133  */
 134 API bundle*             bundle_create(void);
 135
 136 /**
 137  * @brief               Free given bundle object with key/values in it
 138  * @pre                 b must be a valid bundle object.
 139  * @post                None
 140  * @see                 bundle_create()
 141  * @param[in]   b       bundle object to be freed
 142  * @return              Operation result;
 143  * @retval              0 success
 144  * @retval              -1 failure
 145  * @remark              None
 146  @code
 147  #include <bundle.h>
 148  bundle *b = bundle_create(); // Create new bundle object
 149  bundle_free(b); // free bundle
 150  @endcode
 151  */
 152 API int                 bundle_free(bundle *b);
 153 /**
 154  * @brief               Add a string array type key-value pair into bundle.
 155  * @pre                 b must be a valid bundle object.
 156  * @post                None
 157  * @see                 bundle_get_str_array()
 158  * @see                 bundle_set_str_array_element()
 159  * @param[in]   b       bundle object
 160  * @param[in]   key     key
 161  * @param[in]   str_array string type value. If NULL, empty array is created. You can change an item with
 162  * @param[in]   len Length of array.
 163  * @return              Operation result
 164  * @retval              0       success
 165  * @retval              -1      failure
 166  *
 167  * @remark              When -1 is returned, errno is set to one of the following values; \n
 168                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 169                                 EPERM : key is already exist, not permitted to overwrite value \n
 170                                 EINVAL : b or val is not valid (NULL or sth) \n
 171  @code
 172  #include <bundle.h>
 173  char *sa = { "aaa", "bbb", "ccc" };    // A string array of length 3
 174  bundle *b = bundle_create();
 175  bundle_add_str_array(b, "foo", sa, 3); // add a key-val pair
 176  bundle_free(b);
 177  @endcode
 178  */
 179 API int bundle_add_str_array(bundle *b, const char *key, const char **str_array, const int len);
 180 /**
 181  * @brief               Add a string type key-value pair into bundle.
 182  * @pre                 b must be a valid bundle object.
 183  * @post                None
 184  * @see                 bundle_add_str()
 185  * @param[in]   b       bundle object
 186  * @param[in]   key     key
 187  * @param[in]   val     value
 188  * @return              Operation result
 189  * @retval              0       success
 190  * @retval              -1      failure
 191  *
 192  * @remark              When -1 is returned, errno is set to one of the following values; \n
 193                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 194                                 EPERM : key is already exist, not permitted to overwrite value \n
 195                                 EINVAL : b or val is not valid (NULL or sth) \n
 196  @code
 197  #include <bundle.h>
 198  bundle *b = bundle_create(); // Create new bundle object
 199  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 200
 201  bundle_free(b);
 202  @endcode
 203  */
 204 API int                         bundle_add(bundle *b, const char *key, const char *val);
 205
 206 /**
 207  * @brief               Delete val with given key
 208  * @pre                 b must be a valid bundle object.
 209  * @post                None
 210  * @see                 None
 211  * @param[in]   b       bundle object
 212  * @param[in]   key     given key
 213  * @return              Operation result
 214  * @retval              0       Success
 215  * @retval              -1      Failure
 216  *
 217  * @remark              When -1 is returned, errno is set to one of the following values; \n
 218                                 EINVAL : b is invalid (NULL or sth) \n
 219                                 ENOKEY : No key exist \n
 220                                 EKEYREJECTED : key is invalid (NULL or sth) \n
 221  @code
 222  #include <bundle.h>
 223  bundle *b = bundle_create(); // Create new bundle object
 224  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 225  bundle_del(b, "foo_key"); // del "foo_key" from b
 226
 227  bundle_free(b);
 228  @endcode
 229  */
 230 API int                         bundle_del(bundle *b, const char* key);
 231 /**
 232  * @brief               Get string array value from key
 233  * @pre                 b must be a valid bundle object.
 234  * @post                None
 235  * @see                 bundle_add_str_array()
 236  * @see                 bundle_set_str_array_element()
 237  * @param[in]   b       bundle object
 238  * @param[in]   key     key
 239  * @param[out]  len     array length
 240  * @return              Pointer to array of  string
 241  * @retval              NULL    If key is not found, returns NULL.
 242  * @remark              DO NOT free or modify returned string!
 243                                 When NULL is returned, errno is set to one of the following values; \n
 244                                 EINVAL : b is invalid \n
 245                                 ENOKEY : No key exists \n
 246                                 EKEYREJECTED : invalid key (NULL or sth) \n
 247  @code
 248  #include <bundle.h>
 249  bundle *b = bundle_create();
 250  bundle_add_str_array(b, "foo", NULL, 3); // add a key-val pair
 251  bundle_set_str_array_element(b, "foo", 0, "aaa");
 252  bundle_set_str_array_element(b, "foo", 1, "bbb");
 253  bundle_set_str_array_element(b, "foo", 2, "ccc");
 254
 255  char **str_array = NULL;
 256  int len_str_array = 0;
 257
 258  str_array=bundle_get_str_array(b, "foo", &len_str_array);
 259  // str_array = { "aaa", "bbb", "ccc" }, and len_str_array = 3
 260
 261  bundle_free(b);
 262  @endcode
 263  */
 264
 265 API const char** bundle_get_str_array(bundle *b, const char *key,int *len);
 266 /**
 267  * @brief               Get value from key
 268  * @pre                 b must be a valid bundle object.
 269  * @post                None
 270  * @see                 bundle_get_str()
 271  * @param[in]   b       bundle object
 272  * @param[in]   key     key
 273  * @return              Pointer for value string
 274  * @retval              NULL    If key is not found, returns NULL.
 275  * @remark              DO NOT free or modify returned string!
 276                                 When NULL is returned, errno is set to one of the following values; \n
 277                                 EINVAL : b is invalid \n
 278                                 ENOKEY : No key exists \n
 279                                 EKEYREJECTED : invalid key (NULL or sth) \n
 280  @code
 281  #include <bundle.h>
 282  bundle *b = bundle_create(); // Create new bundle object
 283  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 284  char *val = bundle_get_val(b, "foo_key");      // val = "bar_val"
 285
 286  bundle_free(b);        // After freeing b, val becomes a dangling pointer.
 287  val = NULL;
 288  @endcode
 289  */
 290 API const char*         bundle_get_val(bundle *b, const char *key);
 291
 292 /**
 293  * @brief       Get the number of bundle items
 294  * @pre                 b must be a valid bundle object.
 295  * @post                None
 296  * @see                 None
 297  * @param[in]   b       bundle object
 298  * @return              Number of bundle items
 299  * @remark              None
 300  @code
 301  #include <bundle.h>
 302  bundle *b = bundle_create(); // Create new bundle object
 303  bundle_add(b, "key1", "val1"); // add a key-val pair
 304  int count = bundle_get_count(b);       // count=1
 305  bundle_add(b, "key2", "val2"); // add another key-val pair
 306  count = bundle_get_count(b); // count=2
 307
 308  bundle_free(b);
 309  @endcode
 310  */
 311 API int                         bundle_get_count(bundle *b);
 312
 313
 314 /**
 315  * @brief       Get a type of a value with certain key
 316  * @pre         b must be a valid bundle object
 317  * @post        None
 318  * @see         bundle_type_t
 319  * @param[in]   b       A bundle
 320  * @param[in]   key     A key in bundle
 321  * @return      Type of a key in b
 322  * @remark
 323  @code
 324  @endcode
 325  */
 326 API int bundle_get_type(bundle *b, const char *key);
 327
 328
 329 /**
 330  * @brief       Duplicate given bundle object
 331  * @pre                 b must be a valid bundle object.
 332  * @post                None
 333  * @see                 None
 334  * @param[in]   b_from  bundle object to be duplicated
 335  * @return              New bundle object
 336  * @retval              NULL    Failure
 337  * @remark              None
 338  @code
 339  #include <bundle.h>
 340  bundle *b = bundle_create(); // Create new bundle object
 341  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 342  bundle *b_dup = bundle_dup(b); // duplicate b
 343
 344  bundle_free(b);
 345  bundle_free(b_dup);
 346  @endcode
 347  */
 348 API bundle *            bundle_dup(bundle *b_from);
 349
 350 /**
 351  * @brief       iterate callback function with each key/val pairs in bundle. (NOTE: Only BUNDLE_TYPE_STR type values come!)
 352  * @pre                 b must be a valid bundle object.
 353  * @post                None
 354  * @see                 None
 355  * @param[in]   b       bundle object
 356  * @param[in]   callback        iteration callback function
 357  * @param[in]   data    data for callback function
 358  * @remark              This function is obsolete, and does not give values whose types are not BUNDLE_TYPE_STR.
 359  @code
 360  @include <stdio.h>
 361  #include <bundle.h>
 362  void sample_cb(const char *k, const char *v, void *data) {
 363    printf("%s -> %s\n", k, v);
 364  }
 365
 366  int main(void) {
 367          bundle *b = bundle_create(); // Create new bundle object
 368          bundle_add(b, "k1", "v1"); // add a key-val pair
 369          bundle_add(b, "k2", "v2"); // add a key-val pair
 370          bundle_add(b, "k3", "v3"); // add a key-val pair
 371          bundle_iterate(b, sample_cb, NULL);    // iterate sample_cb for each key/val
 372          return 0;
 373  }
 374  @endcode
 375  */
 376 API void                        bundle_iterate(bundle *b, bundle_iterate_cb_t callback, void *cb_data);
 377
 378
 379 /**
 380  * @brief       iterate callback function with each key/val pairs in bundle. (Supports all types of value)
 381  * @pre                 b must be a valid bundle object.
 382  * @post                None
 383  * @see                 bundle_keyval_get_type bundle_keyval_type_is_array bundle_keyval_get_basic_val bundle_keyval_get_array_val
 384  * @param[in]   b       bundle object
 385  * @param[in]   iter    iteration callback function
 386  * @param[in]   user_data       data for callback function
 387  * @remark              This function supports all types.
 388  @code
 389  @include <stdio.h>
 390  #include <bundle.h>
 391  void sample_cb(const char *key, const int type, const bundle_keyval_t *kv, void *user_data) {
 392    void *basic_val = NULL;
 393    size_t basic_size = 0;
 394    void **array_val = NULL;
 395    int array_len = 0;
 396    size_t *array_elem_size = NULL;
 397
 398    printf("Key:%s, Type:%d\n", key, type);
 399    if(bundle_keyval_type_is_array(kv)) {
 400      bundle_keyval_get_array_val(kv, &array_val, &array_len, &array_elem_size);
 401          // Do something...
 402    }
 403    else {
 404      bundle_keyval_get_basic_val(kv, &basic_val, &size);
 405          // Do something...
 406    }
 407  }
 408
 409  int main(void) {
 410          bundle *b = bundle_create(); // Create new bundle object
 411          bundle_add_str(b, "k1", "v1"); // add a key-val pair
 412          bundle_add_byte(b, "k2", "v2", 3); // add a key-val pair
 413          char *s_arr[] = {"abc", "bcd", "cde"};
 414          bundle_add_str_array(b, "k3", s_arr, 3); // add a key-val pair
 415          bundle_iterate(b, sample_cb, NULL);    // iterate sample_cb for each key/val
 416          return 0;
 417  }
 418  @endcode
 419  */
 420 API void                        bundle_foreach(bundle *b, bundle_iterator_t iter, void *user_data);
 421
 422
 423 /**
 424  * @brief       Get type for a bundle_keyval_t object.
 425  * @pre         kv must be a valid bundle_keyval_t object.
 426  * @post        None
 427  * @see         bundle_foreach
 428  * @param[in]   kv      A bundle_keyval_t object
 429  * @return      Type of kv
 430  * @retval      -1      Operation failure.      errno is set.
 431  * @remark
 432  */
 433 API int bundle_keyval_get_type(bundle_keyval_t *kv);
 434
 435
 436 /**
 437  * @brief       Determine if kv is array type or not.
 438  * @pre         kv must be a valid bundle_keyval_t object.
 439  * @post        None
 440  * @see         bundle_foreach
 441  * @param[in]   kv      A bundle_keyval_t object
 442  * @return              Operation result
 443  * @retval              1       kv is an array.
 444  * @retval              0       kv is not an array.
 445  * @remark
 446  */
 447 API int bundle_keyval_type_is_array(bundle_keyval_t *kv);
 448
 449
 450 /**
 451  * @brief       Get value and size of the value from kv of basic type.
 452  * @pre         kv must be a valid bundle_keyval_t object.
 453  * @post        val, size are set.
 454  * @see         bundle_foreach
 455  * @param[in]   kv              A bundle_keyval_t object
 456  * @param[out]  val             Value
 457  * @param[out]  size    Size of val
 458  * @return      Operation result
 459  * @retval      0       Success
 460  * @remark      Do not free val.
 461  */
 462 API int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *size);
 463
 464
 465 /**
 466  * @brief       Get value array, length of array, and size of each array item
 467  * @pre         kv must be a valid bundle_keyval_t object.
 468  * @post        array_val, array_len, array_item_size are set.
 469  * @see         bundle_foreach
 470  * @param[in]   kv              A bundle_keyval_t object
 471  * @param[out]  array_val       Array pointer of values
 472  * @param[out]  array_len       Length of array_val
 473  * @param[out]  array_element_size      Array of size of each array element
 474  * @return      Operation result
 475  * @retval      0       Success
 476  * @retval      0       Failure
 477  * @remark
 478  */
 479 API int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size);
 480
 481
 482 /**
 483  * @brief       Encode bundle to bundle_raw format (uses base64 format)
 484  * @pre                 b must be a valid bundle object.
 485  * @post                None
 486  * @see                 None
 487  * @param[in]   b       bundle object
 488  * @param[out]  r       returned bundle_raw data(byte data)
 489  *                                      r MUST BE FREED by free(r).
 490  * @param[out]  len     size of r (in bytes)
 491  * @return      size of raw data
 492  * @retval              0               Success
 493  * @retval              -1              Failure
 494  * @remark              None
 495  @code
 496  #include <bundle.h>
 497  bundle *b = bundle_create(); // Create new bundle object
 498  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 499  bundle_raw *r;
 500  int len;
 501  bundle_encode(b, &r, &len);    // encode b
 502
 503  bundle_free_encoded_rawdata(r);
 504  bundle_free(b);
 505  @endcode
 506  */
 507 API int                         bundle_encode(bundle *b, bundle_raw **r, int *len);
 508
 509 /**
 510  * @brief       Free encoded rawdata from memory
 511  * @pre         r is a valid rawdata generated by bundle_encode().
 512  * @post        None
 513  * @see         bundle_encode
 514  * @param[in]   r       is a rawdata
 515  * @return              Operation result
 516  * @retval              0       Success
 517  * @retval              -1      Failure
 518  * @reamark     None
 519  */
 520 API int                         bundle_free_encoded_rawdata(bundle_raw **r);
 521
 522 /**
 523  * @brief       deserialize bundle_raw, and get bundle object
 524  * @pre                 b must be a valid bundle object.
 525  * @post                None
 526  * @see                 None
 527  * @param[in]   r       bundle_raw data to be converted to bundle object
 528  * @param[in]   len     size of r
 529  * @return      bundle object
 530  * @retval      NULL    Failure
 531  * @remark              None
 532  @code
 533  #include <bundle.h>
 534  bundle *b = bundle_create(); // Create new bundle object
 535  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 536
 537  bundle_raw *encoded_b;
 538  int len;
 539  bundle_encode(b, &encoded_b, &len);    // encode b
 540
 541  bundle *b_dup;
 542  b_dup = bundle_decode(encoded_b, len); // decoded bundle object
 543
 544  bundle_free(b);
 545  free(encoded_b);
 546  bundle_free(b_dup);
 547  @endcode
 548  */
 549 API bundle *            bundle_decode(const bundle_raw *r, const int len);
 550
 551
 552 /**
 553  * @brief       Export bundle to argv
 554  * @pre         b is a valid bundle object.
 555  * @post        argv is a pointer of newly allocated memory. It must be freed.
 556  *          Each item of argv points the string in the bundle object b. If b is freed, argv will have garbage pointers. DO NOT FREE b BEFORE ACCESSING argv!!
 557  * @see         bundle_import_from_argv
 558  * @param[in]   b       bundle object
 559  * @param[out]  argv    Pointer of string array.
 560  *                      This array has NULL values for first and last item.
 561  *                      First NULL is for argv[0], and last NULL is a terminator for execv().
 562  * @return      Number of item in argv. This value is equal to actual count of argv - 1. (Last NULL terminator is not counted.)
 563  * @retval      -1              Function failure. Check errno to get the reason.
 564  * @remark      None
 565  @code
 566  #include <bundle.h>
 567  bundle *b = bundle_create(); // Create new bundle object
 568  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 569
 570  int argc = 0;
 571  char **argv = NULL;
 572  argc = bundle_export_to_argv(b, &argv);        // export to argv
 573  if(0 > argc) error("export failure");
 574
 575  int i;
 576  for(i=0; i < argc; i++) {
 577    printf("%s\n", argv[i]);             // print argv
 578  }
 579  bundle_free_exported_argv(argc, argv); // argv must be freed after being used.
 580
 581  bundle_free(b);
 582  @endcode
 583  */
 584 API int                         bundle_export_to_argv(bundle *b, char ***argv);
 585
 586 /**
 587  * @brief       Free exported argv
 588  * @pre         argv is a valid string array generated from bundle_export_to_argv().
 589  * @post        None
 590  * @see         bundle_export_to_argv
 591  * @param[in]   argc    number of args, which is the return value of bundle_export_to_argv().
 592  * @param[in]   argv array from bundle_export_to_argv().
 593  * @return      Operation result.
 594  * @retval      0       on success
 595  * @retval      -1      on failure
 596  * @remark      You must not use this API when you use global argv.
 597  @code
 598  bundle *b = bundle_create();
 599  bundle_add_str(b, "foo", "bar");
 600
 601  int argc = 0;
 602  char **argv = NULL;
 603  argc = bundle_export_to_argv(b, &argv);
 604  if(0 > argc) error("export failure");
 605
 606  // Use argv...
 607
 608  bundle_free_export_argv(argc, argv);
 609  argv = NULL;
 610
 611  bundle_free(b);
 612  @endcode
 613  */
 614 API int                         bundle_free_exported_argv(int argc, char ***argv);
 615
 616 /**
 617  * @brief       import a bundle from argv
 618  * @pre         argv is a valid string array, which is created by bundle_export_to_argv().
 619  * @post        Returned bundle b must be freed.
 620  * @see         bundle_export_to_argv
 621  * @param[in]   argc    argument count
 622  * @param[in]   argv    argument vector
 623  * @return      New bundle object
 624  * @retval      NULL    Function failure
 625  * @remark      None
 626  @code
 627  #include <bundle.h>
 628
 629  int main(int argc, char **argv) {
 630    bundle *b = bundle_import_from_argv(argc, argv); // import from argc+argv
 631    char *val = bundle_get_val(b, "foo_key");    // value for "foo_key"
 632    // ......
 633    bundle_free(b);      // After freeing b, val becomes a dangling pointer.
 634    val = NULL;
 635  }
 636  @endcode
 637  */
 638 API bundle *            bundle_import_from_argv(int argc, char **argv);
 639
 640 #if 0
 641 /**
 642  * @brief               Add a string type key-value pair into bundle.
 643  * @pre                 b must be a valid bundle object.
 644  * @post                None
 645  * @see                 bundle_get_str()
 646  * @param[in]   b       bundle object
 647  * @param[in]   key     key
 648  * @param[in]   str string type value
 649  * @return              Operation result
 650  * @retval              0       success
 651  * @retval              -1      failure
 652  *
 653  * @remark              When -1 is returned, errno is set to one of the following values; \n
 654                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 655                                 EPERM : key is already exist, not permitted to overwrite value \n
 656                                 EINVAL : b or val is not valid (NULL or sth) \n
 657  @code
 658  #include <bundle.h>
 659  bundle *b = bundle_create(); // Create new bundle object
 660  bundle_add_str(b, "foo", "bar"); // add a key-val pair
 661
 662  bundle_free(b);
 663  @endcode
 664  */
 665 API int bundle_add_str(bundle *b, const char *key, const char *str);
 666
 667 /**
 668  * @brief               Set a value of string array element
 669  * @pre                 b must be a valid bundle object.
 670  * @post                None
 671  * @see                 bundle_add_str_array()
 672  * @see                 bundle_get_str_array()
 673  * @param[in]   b       bundle object
 674  * @param[in]   key     key
 675  * @param[in]   idx index of array element to be changed
 676  * @param[in]   val string type value. If NULL, empty array is created. You can change an item with
 677  * @return              Operation result
 678  * @retval              0       success
 679  * @retval              -1      failure
 680  *
 681  * @remark              When -1 is returned, errno is set to one of the following values; \n
 682                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 683                                 EPERM : key is already exist, not permitted to overwrite value \n
 684                                 EINVAL : b or val is not valid (NULL or sth) \n
 685  @code
 686  #include <bundle.h>
 687  bundle *b = bundle_create();
 688  bundle_add_str_array(b, "foo", NULL, 3); // add a key-val pair
 689  bundle_set_str_array_element(b, "foo", 0, "aaa");
 690  bundle_set_str_array_element(b, "foo", 1, "bbb");
 691  bundle_set_str_array_element(b, "foo", 2, "ccc");
 692
 693  char **str_array = NULL;
 694  int len_str_array = 0;
 695
 696  str_array=bundle_get_str_array(b, "foo", &len_str_array);
 697  // str_array = { "aaa", "bbb", "ccc" }, and len_str_array = 3
 698
 699  bundle_free(b);
 700  @endcode
 701  */
 702 API int bundle_set_str_array_element(bundle *b, const char *key, const unsigned int idx, const char *val);
 703
 704 /**
 705  * @brief               Add a byte type key-value pair into bundle.
 706  * @pre                 b must be a valid bundle object.
 707  * @post                None
 708  * @see                 bundle_get_byte()
 709  * @param[in]   b       bundle object
 710  * @param[in]   key     key
 711  * @param[in]   byte string type value
 712  * @param[in]   size size of byte
 713  * @return              Operation result
 714  * @retval              0       success
 715  * @retval              -1      failure
 716  *
 717  * @remark              When -1 is returned, errno is set to one of the following values; \n
 718                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 719                                 EPERM : key is already exist, not permitted to overwrite value \n
 720                                 EINVAL : b or val is not valid (NULL or sth) \n
 721  @code
 722  #include <bundle.h>
 723  bundle *b = bundle_create(); // Create new bundle object
 724  bundle_add_byte(b, "foo", "bar\0", 4); // add a key-val pair
 725
 726  bundle_free(b);
 727  @endcode
 728  */
 729
 730 API int bundle_add_byte(bundle *b, const char *key, const void *byte, const size_t size);
 731
 732 /**
 733  * @brief               Add a byte array type key-value pair into bundle.
 734  * @pre                 b must be a valid bundle object.
 735  * @post                None
 736  * @see                 bundle_get_str_array()
 737  * @see                 bundle_set_byte_array_element()
 738  * @param[in]   b       bundle object
 739  * @param[in]   key     key
 740  * @param[in]   byte_array  Not used.
 741  * @param[in]   len Length of array to be created
 742  * @return              Operation result
 743  * @retval              0       success
 744  * @retval              -1      failure
 745  *
 746  * @remark              When -1 is returned, errno is set to one of the following values; \n
 747                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 748                                 EPERM : key is already exist, not permitted to overwrite value \n
 749                                 EINVAL : b or val is not valid (NULL or sth) \n
 750  @code
 751  #include <bundle.h>
 752  bundle *b = bundle_create();
 753  bundle_add_byte_array(b, "foo", NULL, 3); // add a byte-array with length 3
 754
 755  bundle_set_byte_array_element(b, "foo", 0, "aaa\0", 4);        array[0] = "aaa\0"
 756  bundle_set_byte_array_element(b, "foo", 1, "bbb\0", 4);        array[1] = "bbb\0"
 757  bundle_set_byte_array_element(b, "foo", 2, "ccc\0", 4);        array[2] = "ccc\0"
 758
 759  bundle_free(b);
 760  @endcode
 761  */
 762 API int bundle_add_byte_array(bundle *b, const char *key, void **byte_array, const unsigned int len);
 763
 764 /**
 765  * @brief               Set a value of byte array element
 766  * @pre                 b must be a valid bundle object.
 767  * @post                None
 768  * @see                 bundle_add_str_array()
 769  * @see                 bundle_get_str_array()
 770  * @param[in]   b       bundle object
 771  * @param[in]   key     key
 772  * @param[in]   idx index of array element to be changed
 773  * @param[in]   val string type value. If NULL, empty array is created. You can change an item with
 774  * @param[in]   size Size of value in byte
 775  * @return              Operation result
 776  * @retval              0       success
 777  * @retval              -1      failure
 778  *
 779  * @remark              When -1 is returned, errno is set to one of the following values; \n
 780                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 781                                 EPERM : key is already exist, not permitted to overwrite value \n
 782                                 EINVAL : b or val is not valid (NULL or sth) \n
 783  @code
 784  #include <bundle.h>
 785  bundle *b = bundle_create();
 786  bundle_add_byte_array(b, "foo", NULL, 3); // add a key-val pair
 787  bundle_set_byte_array_element(b, "foo", 0, "aaa\0", 4);
 788  bundle_set_byte_array_element(b, "foo", 1, "bbb\0", 4);
 789  bundle_set_byte_array_element(b, "foo", 2, "ccc\0", 4);
 790
 791  unsigned char **byte_array = NULL;
 792  int len_byte_array = 0;
 793
 794  byte_array=bundle_get_str_array(b, "foo", &len_byte_array);
 795  // byte_array = { "aaa\0", "bbb\0", "ccc\0" }, and len_byte_array = 3
 796
 797  bundle_free(b);
 798  @endcode
 799  */
 800 API int bundle_set_byte_array_element(bundle *b, const char *key, const unsigned int idx, const void *val, const size_t size);
 801
 802 /**
 803  * @brief               Get string value from key
 804  * @pre                 b must be a valid bundle object.
 805  * @post                None
 806  * @see                 bundle_add_str()
 807  * @param[in]   b       bundle object
 808  * @param[in]   key     key
 809  * @param[out]  str returned value
 810  * @return              Operation result
 811  * @retval              0 on success
 812  * @retval              -1 on failure
 813  * @remark              Do not free str!
 814                                 When -1 is returned, errno is set to one of the following values; \n
 815                                 EINVAL : b is invalid \n
 816                                 ENOKEY : No key exists \n
 817                                 EKEYREJECTED : invalid key (NULL or sth) \n
 818  @code
 819  #include <bundle.h>
 820  bundle *b = bundle_create(); // Create new bundle object
 821  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 822
 823  char *v = NULL;
 824  bundle_get_str(b, "foo_key", &v);      // v = "bar_val"
 825
 826  bundle_free(b);        // After freeing b, v becomes a dangling pointer.
 827  v = NULL;
 828  @endcode
 829  */
 830 API int bundle_get_str(bundle *b, const char *key, char **str);
 831
 832 /**
 833  * @brief               Get byte value from key
 834  * @pre                 b must be a valid bundle object.
 835  * @post                None
 836  * @see                 bundle_add_byte()
 837  * @param[in]   b       bundle object
 838  * @param[in]   key     key
 839  * @param[out]  byte returned value
 840  * @param[out]  size Size of byte
 841  * @return              Operation result
 842  * @retval              0 on success
 843  * @retval              -1 on failure
 844  * @remark              Do not free str!
 845                                 When -1 is returned, errno is set to one of the following values; \n
 846                                 EINVAL : b is invalid \n
 847                                 ENOKEY : No key exists \n
 848                                 EKEYREJECTED : invalid key (NULL or sth) \n
 849  @code
 850  #include <bundle.h>
 851  bundle *b = bundle_create(); // Create new bundle object
 852  bundle_add_byte(b, "foo", "bar\0", 4); // add a key-val pair
 853
 854  unsigned char *v = NULL;
 855  bundle_get_str(b, "foo", &v);  // v = "bar\0"
 856
 857  bundle_free(b);        // After freeing b, v becomes a dangling pointer.
 858  @endcode
 859  */
 860 API int bundle_get_byte(bundle *b, const char *key, void **byte, size_t *size);
 861
 862 /**
 863  * @brief               Get byte array value from key
 864  * @pre                 b must be a valid bundle object.
 865  * @post                None
 866  * @see                 bundle_add_str_array()
 867  * @see                 bundle_set_str_array_element()
 868  * @param[in]   b       bundle object
 869  * @param[in]   key     key
 870  * @param[out]  byte_array returned value
 871  * @param[out]  len     array length
 872  * @param[out]  array_element_size      an array of sizes of each byte_array element
 873  * @return              Operation result
 874  * @retval              0 on success
 875  * @retval              -1 on failure
 876  * @remark              Do not free str!
 877                                 When -1 is returned, errno is set to one of the following values; \n
 878                                 EINVAL : b is invalid \n
 879                                 ENOKEY : No key exists \n
 880                                 EKEYREJECTED : invalid key (NULL or sth) \n
 881  @code
 882  #include <bundle.h>
 883  bundle *b = bundle_create();
 884  bundle_add_byte_array(b, "foo", NULL, 3);
 885  bundle_set_byte_array_element(b, "foo", 0, "aaa\0", 4);
 886  bundle_set_byte_array_element(b, "foo", 1, "bbb\0", 4);
 887  bundle_set_byte_array_element(b, "foo", 2, "ccc\0", 4);
 888
 889  char **byte_array = NULL;
 890  int len_byte_array = 0;
 891  size_t *size_byte_array = NULL;
 892
 893  byte_array = bundle_get_str_array(b, "foo", &len_byte_array, &size_byte_array);
 894  // byte_array = { "aaa\0", "bbb\0", "ccc\0" }, len_byte_array = 3, and size_byte_array = { 4, 4, 4 }
 895
 896  bundle_free(b);
 897  @endcode
 898  */
 899 API int bundle_get_byte_array(bundle *b, const char *key, void ***byte_array, unsigned int *len, unsigned int **array_element_size);
 900 #endif
 901
 902
 903 #ifdef __cplusplus
 904 }
 905 #endif
 906
 907 /**
 908  * @}
 909  * @}
 910  */
 911
 912 #endif  /* __BUNDLE_H__ */