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       Determine if kv is measurable type or not.
 452  * @pre         kv must be a valid bundle_keyval_t object.
 453  * @post        None
 454  * @see         bundle_foreach
 455  * @param[in]   kv      A bundle_keyval_t object
 456  * @return              Operation result
 457  * @retval              1       kv is an measurable.
 458  * @retval              0       kv is not an measurable.
 459  * @remark
 460  */
 461 API int bundle_keyval_type_is_measurable(bundle_keyval_t *kv);
 462
 463
 464 /**
 465  * @brief       Get value and size of the value from kv of basic type.
 466  * @pre         kv must be a valid bundle_keyval_t object.
 467  * @post        val, size are set.
 468  * @see         bundle_foreach
 469  * @param[in]   kv              A bundle_keyval_t object
 470  * @param[out]  val             Value
 471  * @param[out]  size    Size of val
 472  * @return      Operation result
 473  * @retval      0       Success
 474  * @remark      Do not free val.
 475  */
 476 API int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *size);
 477
 478
 479 /**
 480  * @brief       Get value array, length of array, and size of each array item
 481  * @pre         kv must be a valid bundle_keyval_t object.
 482  * @post        array_val, array_len, array_item_size are set.
 483  * @see         bundle_foreach
 484  * @param[in]   kv              A bundle_keyval_t object
 485  * @param[out]  array_val       Array pointer of values
 486  * @param[out]  array_len       Length of array_val
 487  * @param[out]  array_element_size      Array of size of each array element
 488  * @return      Operation result
 489  * @retval      0       Success
 490  * @retval      0       Failure
 491  * @remark
 492  */
 493 API int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size);
 494
 495
 496 /**
 497  * @brief       Encode bundle to bundle_raw format (uses base64 format)
 498  * @pre                 b must be a valid bundle object.
 499  * @post                None
 500  * @see                 None
 501  * @param[in]   b       bundle object
 502  * @param[out]  r       returned bundle_raw data(byte data)
 503  *                                      r MUST BE FREED by free(r).
 504  * @param[out]  len     size of r (in bytes)
 505  * @return      size of raw data
 506  * @retval              0               Success
 507  * @retval              -1              Failure
 508  * @remark              None
 509  @code
 510  #include <bundle.h>
 511  bundle *b = bundle_create(); // Create new bundle object
 512  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 513  bundle_raw *r;
 514  int len;
 515  bundle_encode(b, &r, &len);    // encode b
 516
 517  bundle_free_encoded_rawdata(r);
 518  bundle_free(b);
 519  @endcode
 520  */
 521 API int                         bundle_encode(bundle *b, bundle_raw **r, int *len);
 522
 523 /**
 524  * @brief       Free encoded rawdata from memory
 525  * @pre         r is a valid rawdata generated by bundle_encode().
 526  * @post        None
 527  * @see         bundle_encode
 528  * @param[in]   r       is a rawdata
 529  * @return              Operation result
 530  * @retval              0       Success
 531  * @retval              -1      Failure
 532  * @reamark     None
 533  */
 534 API int                         bundle_free_encoded_rawdata(bundle_raw **r);
 535
 536 /**
 537  * @brief       deserialize bundle_raw, and get bundle object
 538  * @pre                 b must be a valid bundle object.
 539  * @post                None
 540  * @see                 None
 541  * @param[in]   r       bundle_raw data to be converted to bundle object
 542  * @param[in]   len     size of r
 543  * @return      bundle object
 544  * @retval      NULL    Failure
 545  * @remark              None
 546  @code
 547  #include <bundle.h>
 548  bundle *b = bundle_create(); // Create new bundle object
 549  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 550
 551  bundle_raw *encoded_b;
 552  int len;
 553  bundle_encode(b, &encoded_b, &len);    // encode b
 554
 555  bundle *b_dup;
 556  b_dup = bundle_decode(encoded_b, len); // decoded bundle object
 557
 558  bundle_free(b);
 559  free(encoded_b);
 560  bundle_free(b_dup);
 561  @endcode
 562  */
 563 API bundle *            bundle_decode(const bundle_raw *r, const int len);
 564
 565
 566 /**
 567  * @brief       Export bundle to argv
 568  * @pre         b is a valid bundle object.
 569  * @post        argv is a pointer of newly allocated memory. It must be freed.
 570  *          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!!
 571  * @see         bundle_import_from_argv
 572  * @param[in]   b       bundle object
 573  * @param[out]  argv    Pointer of string array.
 574  *                      This array has NULL values for first and last item.
 575  *                      First NULL is for argv[0], and last NULL is a terminator for execv().
 576  * @return      Number of item in argv. This value is equal to actual count of argv - 1. (Last NULL terminator is not counted.)
 577  * @retval      -1              Function failure. Check errno to get the reason.
 578  * @remark      None
 579  @code
 580  #include <bundle.h>
 581  bundle *b = bundle_create(); // Create new bundle object
 582  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 583
 584  int argc = 0;
 585  char **argv = NULL;
 586  argc = bundle_export_to_argv(b, &argv);        // export to argv
 587  if(0 > argc) error("export failure");
 588
 589  int i;
 590  for(i=0; i < argc; i++) {
 591    printf("%s\n", argv[i]);             // print argv
 592  }
 593  bundle_free_exported_argv(argc, argv); // argv must be freed after being used.
 594
 595  bundle_free(b);
 596  @endcode
 597  */
 598 API int                         bundle_export_to_argv(bundle *b, char ***argv);
 599
 600 /**
 601  * @brief       Free exported argv
 602  * @pre         argv is a valid string array generated from bundle_export_to_argv().
 603  * @post        None
 604  * @see         bundle_export_to_argv
 605  * @param[in]   argc    number of args, which is the return value of bundle_export_to_argv().
 606  * @param[in]   argv array from bundle_export_to_argv().
 607  * @return      Operation result.
 608  * @retval      0       on success
 609  * @retval      -1      on failure
 610  * @remark      You must not use this API when you use global argv.
 611  @code
 612  bundle *b = bundle_create();
 613  bundle_add_str(b, "foo", "bar");
 614
 615  int argc = 0;
 616  char **argv = NULL;
 617  argc = bundle_export_to_argv(b, &argv);
 618  if(0 > argc) error("export failure");
 619
 620  // Use argv...
 621
 622  bundle_free_export_argv(argc, argv);
 623  argv = NULL;
 624
 625  bundle_free(b);
 626  @endcode
 627  */
 628 API int                         bundle_free_exported_argv(int argc, char ***argv);
 629
 630 /**
 631  * @brief       import a bundle from argv
 632  * @pre         argv is a valid string array, which is created by bundle_export_to_argv().
 633  * @post        Returned bundle b must be freed.
 634  * @see         bundle_export_to_argv
 635  * @param[in]   argc    argument count
 636  * @param[in]   argv    argument vector
 637  * @return      New bundle object
 638  * @retval      NULL    Function failure
 639  * @remark      None
 640  @code
 641  #include <bundle.h>
 642
 643  int main(int argc, char **argv) {
 644    bundle *b = bundle_import_from_argv(argc, argv); // import from argc+argv
 645    char *val = bundle_get_val(b, "foo_key");    // value for "foo_key"
 646    // ......
 647    bundle_free(b);      // After freeing b, val becomes a dangling pointer.
 648    val = NULL;
 649  }
 650  @endcode
 651  */
 652 API bundle *            bundle_import_from_argv(int argc, char **argv);
 653
 654 /**
 655  * @brief               Add a string type key-value pair into bundle.
 656  * @pre                 b must be a valid bundle object.
 657  * @post                None
 658  * @see                 bundle_get_str()
 659  * @param[in]   b       bundle object
 660  * @param[in]   key     key
 661  * @param[in]   str string type value
 662  * @return              Operation result
 663  * @retval              0       success
 664  * @retval              -1      failure
 665  *
 666  * @remark              When -1 is returned, errno is set to one of the following values; \n
 667                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 668                                 EPERM : key is already exist, not permitted to overwrite value \n
 669                                 EINVAL : b or val is not valid (NULL or sth) \n
 670  @code
 671  #include <bundle.h>
 672  bundle *b = bundle_create(); // Create new bundle object
 673  bundle_add_str(b, "foo", "bar"); // add a key-val pair
 674
 675  bundle_free(b);
 676  @endcode
 677  */
 678 API int bundle_add_str(bundle *b, const char *key, const char *str);
 679
 680 /**
 681  * @brief               Set a value of string array element
 682  * @pre                 b must be a valid bundle object.
 683  * @post                None
 684  * @see                 bundle_add_str_array()
 685  * @see                 bundle_get_str_array()
 686  * @param[in]   b       bundle object
 687  * @param[in]   key     key
 688  * @param[in]   idx index of array element to be changed
 689  * @param[in]   val string type value. If NULL, empty array is created. You can change an item with
 690  * @return              Operation result
 691  * @retval              0       success
 692  * @retval              -1      failure
 693  *
 694  * @remark              When -1 is returned, errno is set to one of the following values; \n
 695                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 696                                 EPERM : key is already exist, not permitted to overwrite value \n
 697                                 EINVAL : b or val is not valid (NULL or sth) \n
 698  @code
 699  #include <bundle.h>
 700  bundle *b = bundle_create();
 701  bundle_add_str_array(b, "foo", NULL, 3); // add a key-val pair
 702  bundle_set_str_array_element(b, "foo", 0, "aaa");
 703  bundle_set_str_array_element(b, "foo", 1, "bbb");
 704  bundle_set_str_array_element(b, "foo", 2, "ccc");
 705
 706  char **str_array = NULL;
 707  int len_str_array = 0;
 708
 709  str_array=bundle_get_str_array(b, "foo", &len_str_array);
 710  // str_array = { "aaa", "bbb", "ccc" }, and len_str_array = 3
 711
 712  bundle_free(b);
 713  @endcode
 714  */
 715 API int bundle_set_str_array_element(bundle *b, const char *key, const unsigned int idx, const char *val);
 716
 717 /**
 718  * @brief               Add a byte type key-value pair into bundle.
 719  * @pre                 b must be a valid bundle object.
 720  * @post                None
 721  * @see                 bundle_get_byte()
 722  * @param[in]   b       bundle object
 723  * @param[in]   key     key
 724  * @param[in]   byte string type value
 725  * @param[in]   size size of byte
 726  * @return              Operation result
 727  * @retval              0       success
 728  * @retval              -1      failure
 729  *
 730  * @remark              When -1 is returned, errno is set to one of the following values; \n
 731                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 732                                 EPERM : key is already exist, not permitted to overwrite value \n
 733                                 EINVAL : b or val is not valid (NULL or sth) \n
 734  @code
 735  #include <bundle.h>
 736  bundle *b = bundle_create(); // Create new bundle object
 737  bundle_add_byte(b, "foo", "bar\0", 4); // add a key-val pair
 738
 739  bundle_free(b);
 740  @endcode
 741  */
 742
 743 API int bundle_add_byte(bundle *b, const char *key, const void *byte, const size_t size);
 744
 745 /**
 746  * @brief               Add a byte array type key-value pair into bundle.
 747  * @pre                 b must be a valid bundle object.
 748  * @post                None
 749  * @see                 bundle_get_str_array()
 750  * @see                 bundle_set_byte_array_element()
 751  * @param[in]   b       bundle object
 752  * @param[in]   key     key
 753  * @param[in]   byte_array  Not used.
 754  * @param[in]   len Length of array to be created
 755  * @return              Operation result
 756  * @retval              0       success
 757  * @retval              -1      failure
 758  *
 759  * @remark              When -1 is returned, errno is set to one of the following values; \n
 760                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 761                                 EPERM : key is already exist, not permitted to overwrite value \n
 762                                 EINVAL : b or val is not valid (NULL or sth) \n
 763  @code
 764  #include <bundle.h>
 765  bundle *b = bundle_create();
 766  bundle_add_byte_array(b, "foo", NULL, 3); // add a byte-array with length 3
 767
 768  bundle_set_byte_array_element(b, "foo", 0, "aaa\0", 4);        array[0] = "aaa\0"
 769  bundle_set_byte_array_element(b, "foo", 1, "bbb\0", 4);        array[1] = "bbb\0"
 770  bundle_set_byte_array_element(b, "foo", 2, "ccc\0", 4);        array[2] = "ccc\0"
 771
 772  bundle_free(b);
 773  @endcode
 774  */
 775 API int bundle_add_byte_array(bundle *b, const char *key, void **byte_array, const unsigned int len);
 776
 777 /**
 778  * @brief               Set a value of byte array element
 779  * @pre                 b must be a valid bundle object.
 780  * @post                None
 781  * @see                 bundle_add_str_array()
 782  * @see                 bundle_get_str_array()
 783  * @param[in]   b       bundle object
 784  * @param[in]   key     key
 785  * @param[in]   idx index of array element to be changed
 786  * @param[in]   val string type value. If NULL, empty array is created. You can change an item with
 787  * @param[in]   size Size of value in byte
 788  * @return              Operation result
 789  * @retval              0       success
 790  * @retval              -1      failure
 791  *
 792  * @remark              When -1 is returned, errno is set to one of the following values; \n
 793                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 794                                 EPERM : key is already exist, not permitted to overwrite value \n
 795                                 EINVAL : b or val is not valid (NULL or sth) \n
 796  @code
 797  #include <bundle.h>
 798  bundle *b = bundle_create();
 799  bundle_add_byte_array(b, "foo", NULL, 3); // add a key-val pair
 800  bundle_set_byte_array_element(b, "foo", 0, "aaa\0", 4);
 801  bundle_set_byte_array_element(b, "foo", 1, "bbb\0", 4);
 802  bundle_set_byte_array_element(b, "foo", 2, "ccc\0", 4);
 803
 804  unsigned char **byte_array = NULL;
 805  int len_byte_array = 0;
 806
 807  byte_array=bundle_get_str_array(b, "foo", &len_byte_array);
 808  // byte_array = { "aaa\0", "bbb\0", "ccc\0" }, and len_byte_array = 3
 809
 810  bundle_free(b);
 811  @endcode
 812  */
 813 API int bundle_set_byte_array_element(bundle *b, const char *key, const unsigned int idx, const void *val, const size_t size);
 814
 815 /**
 816  * @brief               Get string value from key
 817  * @pre                 b must be a valid bundle object.
 818  * @post                None
 819  * @see                 bundle_add_str()
 820  * @param[in]   b       bundle object
 821  * @param[in]   key     key
 822  * @param[out]  str returned value
 823  * @return              Operation result
 824  * @retval              0 on success
 825  * @retval              -1 on failure
 826  * @remark              Do not free str!
 827                                 When -1 is returned, errno is set to one of the following values; \n
 828                                 EINVAL : b is invalid \n
 829                                 ENOKEY : No key exists \n
 830                                 EKEYREJECTED : invalid key (NULL or sth) \n
 831  @code
 832  #include <bundle.h>
 833  bundle *b = bundle_create(); // Create new bundle object
 834  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 835
 836  char *v = NULL;
 837  bundle_get_str(b, "foo_key", &v);      // v = "bar_val"
 838
 839  bundle_free(b);        // After freeing b, v becomes a dangling pointer.
 840  v = NULL;
 841  @endcode
 842  */
 843 API int bundle_get_str(bundle *b, const char *key, char **str);
 844
 845 /**
 846  * @brief               Get byte value from key
 847  * @pre                 b must be a valid bundle object.
 848  * @post                None
 849  * @see                 bundle_add_byte()
 850  * @param[in]   b       bundle object
 851  * @param[in]   key     key
 852  * @param[out]  byte returned value
 853  * @param[out]  size Size of byte
 854  * @return              Operation result
 855  * @retval              0 on success
 856  * @retval              -1 on failure
 857  * @remark              Do not free str!
 858                                 When -1 is returned, errno is set to one of the following values; \n
 859                                 EINVAL : b is invalid \n
 860                                 ENOKEY : No key exists \n
 861                                 EKEYREJECTED : invalid key (NULL or sth) \n
 862  @code
 863  #include <bundle.h>
 864  bundle *b = bundle_create(); // Create new bundle object
 865  bundle_add_byte(b, "foo", "bar\0", 4); // add a key-val pair
 866
 867  unsigned char *v = NULL;
 868  bundle_get_str(b, "foo", &v);  // v = "bar\0"
 869
 870  bundle_free(b);        // After freeing b, v becomes a dangling pointer.
 871  @endcode
 872  */
 873 API int bundle_get_byte(bundle *b, const char *key, void **byte, size_t *size);
 874
 875 /**
 876  * @brief               Get byte array value from key
 877  * @pre                 b must be a valid bundle object.
 878  * @post                None
 879  * @see                 bundle_add_str_array()
 880  * @see                 bundle_set_str_array_element()
 881  * @param[in]   b       bundle object
 882  * @param[in]   key     key
 883  * @param[out]  byte_array returned value
 884  * @param[out]  len     array length
 885  * @param[out]  array_element_size      an array of sizes of each byte_array element
 886  * @return              Operation result
 887  * @retval              0 on success
 888  * @retval              -1 on failure
 889  * @remark              Do not free str!
 890                                 When -1 is returned, errno is set to one of the following values; \n
 891                                 EINVAL : b is invalid \n
 892                                 ENOKEY : No key exists \n
 893                                 EKEYREJECTED : invalid key (NULL or sth) \n
 894  @code
 895  #include <bundle.h>
 896  bundle *b = bundle_create();
 897  bundle_add_byte_array(b, "foo", NULL, 3);
 898  bundle_set_byte_array_element(b, "foo", 0, "aaa\0", 4);
 899  bundle_set_byte_array_element(b, "foo", 1, "bbb\0", 4);
 900  bundle_set_byte_array_element(b, "foo", 2, "ccc\0", 4);
 901
 902  char **byte_array = NULL;
 903  int len_byte_array = 0;
 904  size_t *size_byte_array = NULL;
 905
 906  byte_array = bundle_get_str_array(b, "foo", &len_byte_array, &size_byte_array);
 907  // byte_array = { "aaa\0", "bbb\0", "ccc\0" }, len_byte_array = 3, and size_byte_array = { 4, 4, 4 }
 908
 909  bundle_free(b);
 910  @endcode
 911  */
 912 API int bundle_get_byte_array(bundle *b, const char *key, void ***byte_array, unsigned int *len, unsigned int **array_element_size);
 913
 914
 915 #ifdef __cplusplus
 916 }
 917 #endif
 918
 919 /**
 920  * @}
 921  * @}
 922  */
 923
 924 #endif  /* __BUNDLE_H__ */