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  * @brief       Encode bundle to bundle_raw format
 567  * @pre                 b must be a valid bundle object.
 568  * @post                None
 569  * @see                 None
 570  * @param[in]   b       bundle object
 571  * @param[out]  r       returned bundle_raw data(byte data)
 572  *                                      r MUST BE FREED by free(r).
 573  * @param[out]  len     size of r (in bytes)
 574  * @return      size of raw data
 575  * @retval              0               Success
 576  * @retval              -1              Failure
 577  * @remark              None
 578  @code
 579  #include <bundle.h>
 580  bundle *b = bundle_create(); // Create new bundle object
 581  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 582  bundle_raw *r;
 583  int len;
 584  bundle_encode_raw(b, &r, &len);        // encode b
 585
 586  bundle_free_encoded_rawdata(r);
 587  bundle_free(b);
 588  @endcode
 589  */
 590 API int                         bundle_encode_raw(bundle *b, bundle_raw **r, int *len);
 591
 592 /**
 593  * @brief       deserialize bundle_raw, and get bundle object
 594  * @pre                 b must be a valid bundle object.
 595  * @post                None
 596  * @see                 None
 597  * @param[in]   r       bundle_raw data to be converted to bundle object
 598  * @param[in]   len     size of r
 599  * @return      bundle object
 600  * @retval      NULL    Failure
 601  * @remark              None
 602  @code
 603  #include <bundle.h>
 604  bundle *b = bundle_create(); // Create new bundle object
 605  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 606
 607  bundle_raw *encoded_b;
 608  int len;
 609  bundle_encode(b, &encoded_b, &len);    // encode b
 610
 611  bundle *b_dup;
 612  b_dup = bundle_decode_raw(encoded_b, len);     // decoded bundle object
 613
 614  bundle_free(b);
 615  free(encoded_b);
 616  bundle_free(b_dup);
 617  @endcode
 618  */
 619 API bundle *            bundle_decode_raw(const bundle_raw *r, const int len);
 620
 621 /**
 622  * @brief       Export bundle to argv
 623  * @pre         b is a valid bundle object.
 624  * @post        argv is a pointer of newly allocated memory. It must be freed.
 625  *          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!!
 626  * @see         bundle_import_from_argv
 627  * @param[in]   b       bundle object
 628  * @param[out]  argv    Pointer of string array.
 629  *                      This array has NULL values for first and last item.
 630  *                      First NULL is for argv[0], and last NULL is a terminator for execv().
 631  * @return      Number of item in argv. This value is equal to actual count of argv - 1. (Last NULL terminator is not counted.)
 632  * @retval      -1              Function failure. Check errno to get the reason.
 633  * @remark      None
 634  @code
 635  #include <bundle.h>
 636  bundle *b = bundle_create(); // Create new bundle object
 637  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
 638
 639  int argc = 0;
 640  char **argv = NULL;
 641  argc = bundle_export_to_argv(b, &argv);        // export to argv
 642  if(0 > argc) error("export failure");
 643
 644  int i;
 645  for(i=0; i < argc; i++) {
 646    printf("%s\n", argv[i]);             // print argv
 647  }
 648  bundle_free_exported_argv(argc, argv); // argv must be freed after being used.
 649
 650  bundle_free(b);
 651  @endcode
 652  */
 653 API int                         bundle_export_to_argv(bundle *b, char ***argv);
 654
 655 /**
 656  * @brief       Free exported argv
 657  * @pre         argv is a valid string array generated from bundle_export_to_argv().
 658  * @post        None
 659  * @see         bundle_export_to_argv
 660  * @param[in]   argc    number of args, which is the return value of bundle_export_to_argv().
 661  * @param[in]   argv array from bundle_export_to_argv().
 662  * @return      Operation result.
 663  * @retval      0       on success
 664  * @retval      -1      on failure
 665  * @remark      You must not use this API when you use global argv.
 666  @code
 667  bundle *b = bundle_create();
 668  bundle_add_str(b, "foo", "bar");
 669
 670  int argc = 0;
 671  char **argv = NULL;
 672  argc = bundle_export_to_argv(b, &argv);
 673  if(0 > argc) error("export failure");
 674
 675  // Use argv...
 676
 677  bundle_free_export_argv(argc, argv);
 678  argv = NULL;
 679
 680  bundle_free(b);
 681  @endcode
 682  */
 683 API int                         bundle_free_exported_argv(int argc, char ***argv);
 684
 685 /**
 686  * @brief       import a bundle from argv
 687  * @pre         argv is a valid string array, which is created by bundle_export_to_argv().
 688  * @post        Returned bundle b must be freed.
 689  * @see         bundle_export_to_argv
 690  * @param[in]   argc    argument count
 691  * @param[in]   argv    argument vector
 692  * @return      New bundle object
 693  * @retval      NULL    Function failure
 694  * @remark      None
 695  @code
 696  #include <bundle.h>
 697
 698  int main(int argc, char **argv) {
 699    bundle *b = bundle_import_from_argv(argc, argv); // import from argc+argv
 700    char *val = bundle_get_val(b, "foo_key");    // value for "foo_key"
 701    // ......
 702    bundle_free(b);      // After freeing b, val becomes a dangling pointer.
 703    val = NULL;
 704  }
 705  @endcode
 706  */
 707 API bundle *            bundle_import_from_argv(int argc, char **argv);
 708
 709 /**
 710  * @brief               Add a string type key-value pair into bundle.
 711  * @pre                 b must be a valid bundle object.
 712  * @post                None
 713  * @see                 bundle_get_str()
 714  * @param[in]   b       bundle object
 715  * @param[in]   key     key
 716  * @param[in]   str string type value
 717  * @return              Operation result
 718  * @retval              0       success
 719  * @retval              -1      failure
 720  *
 721  * @remark              When -1 is returned, errno is set to one of the following values; \n
 722                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 723                                 EPERM : key is already exist, not permitted to overwrite value \n
 724                                 EINVAL : b or val is not valid (NULL or sth) \n
 725  @code
 726  #include <bundle.h>
 727  bundle *b = bundle_create(); // Create new bundle object
 728  bundle_add_str(b, "foo", "bar"); // add a key-val pair
 729
 730  bundle_free(b);
 731  @endcode
 732  */
 733 API int bundle_add_str(bundle *b, const char *key, const char *str);
 734
 735 /**
 736  * @brief               Set a value of string array element
 737  * @pre                 b must be a valid bundle object.
 738  * @post                None
 739  * @see                 bundle_add_str_array()
 740  * @see                 bundle_get_str_array()
 741  * @param[in]   b       bundle object
 742  * @param[in]   key     key
 743  * @param[in]   idx index of array element to be changed
 744  * @param[in]   val string type value. If NULL, empty array is created. You can change an item with
 745  * @return              Operation result
 746  * @retval              0       success
 747  * @retval              -1      failure
 748  *
 749  * @remark              When -1 is returned, errno is set to one of the following values; \n
 750                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 751                                 EPERM : key is already exist, not permitted to overwrite value \n
 752                                 EINVAL : b or val is not valid (NULL or sth) \n
 753  @code
 754  #include <bundle.h>
 755  bundle *b = bundle_create();
 756  bundle_add_str_array(b, "foo", NULL, 3); // add a key-val pair
 757  bundle_set_str_array_element(b, "foo", 0, "aaa");
 758  bundle_set_str_array_element(b, "foo", 1, "bbb");
 759  bundle_set_str_array_element(b, "foo", 2, "ccc");
 760
 761  char **str_array = NULL;
 762  int len_str_array = 0;
 763
 764  str_array=bundle_get_str_array(b, "foo", &len_str_array);
 765  // str_array = { "aaa", "bbb", "ccc" }, and len_str_array = 3
 766
 767  bundle_free(b);
 768  @endcode
 769  */
 770 API int bundle_set_str_array_element(bundle *b, const char *key, const unsigned int idx, const char *val);
 771
 772 /**
 773  * @brief               Add a byte type key-value pair into bundle.
 774  * @pre                 b must be a valid bundle object.
 775  * @post                None
 776  * @see                 bundle_get_byte()
 777  * @param[in]   b       bundle object
 778  * @param[in]   key     key
 779  * @param[in]   byte string type value
 780  * @param[in]   size size of byte
 781  * @return              Operation result
 782  * @retval              0       success
 783  * @retval              -1      failure
 784  *
 785  * @remark              When -1 is returned, errno is set to one of the following values; \n
 786                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 787                                 EPERM : key is already exist, not permitted to overwrite value \n
 788                                 EINVAL : b or val is not valid (NULL or sth) \n
 789  @code
 790  #include <bundle.h>
 791  bundle *b = bundle_create(); // Create new bundle object
 792  bundle_add_byte(b, "foo", "bar\0", 4); // add a key-val pair
 793
 794  bundle_free(b);
 795  @endcode
 796  */
 797
 798 API int bundle_add_byte(bundle *b, const char *key, const void *byte, const size_t size);
 799
 800 /**
 801  * @brief               Add a byte array type key-value pair into bundle.
 802  * @pre                 b must be a valid bundle object.
 803  * @post                None
 804  * @see                 bundle_get_str_array()
 805  * @see                 bundle_set_byte_array_element()
 806  * @param[in]   b       bundle object
 807  * @param[in]   key     key
 808  * @param[in]   byte_array  Not used.
 809  * @param[in]   len Length of array to be created
 810  * @return              Operation result
 811  * @retval              0       success
 812  * @retval              -1      failure
 813  *
 814  * @remark              When -1 is returned, errno is set to one of the following values; \n
 815                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 816                                 EPERM : key is already exist, not permitted to overwrite value \n
 817                                 EINVAL : b or val is not valid (NULL or sth) \n
 818  @code
 819  #include <bundle.h>
 820  bundle *b = bundle_create();
 821  bundle_add_byte_array(b, "foo", NULL, 3); // add a byte-array with length 3
 822
 823  bundle_set_byte_array_element(b, "foo", 0, "aaa\0", 4);        array[0] = "aaa\0"
 824  bundle_set_byte_array_element(b, "foo", 1, "bbb\0", 4);        array[1] = "bbb\0"
 825  bundle_set_byte_array_element(b, "foo", 2, "ccc\0", 4);        array[2] = "ccc\0"
 826
 827  bundle_free(b);
 828  @endcode
 829  */
 830 API int bundle_add_byte_array(bundle *b, const char *key, void **byte_array, const unsigned int len);
 831
 832 /**
 833  * @brief               Set a value of byte array element
 834  * @pre                 b must be a valid bundle object.
 835  * @post                None
 836  * @see                 bundle_add_str_array()
 837  * @see                 bundle_get_str_array()
 838  * @param[in]   b       bundle object
 839  * @param[in]   key     key
 840  * @param[in]   idx index of array element to be changed
 841  * @param[in]   val string type value. If NULL, empty array is created. You can change an item with
 842  * @param[in]   size Size of value in byte
 843  * @return              Operation result
 844  * @retval              0       success
 845  * @retval              -1      failure
 846  *
 847  * @remark              When -1 is returned, errno is set to one of the following values; \n
 848                                 EKEYREJECTED : key is rejected (NULL or sth) \n
 849                                 EPERM : key is already exist, not permitted to overwrite value \n
 850                                 EINVAL : b or val is not valid (NULL or sth) \n
 851  @code
 852  #include <bundle.h>
 853  bundle *b = bundle_create();
 854  bundle_add_byte_array(b, "foo", NULL, 3); // add a key-val pair
 855  bundle_set_byte_array_element(b, "foo", 0, "aaa\0", 4);
 856  bundle_set_byte_array_element(b, "foo", 1, "bbb\0", 4);
 857  bundle_set_byte_array_element(b, "foo", 2, "ccc\0", 4);
 858
 859  unsigned char **byte_array = NULL;
 860  int len_byte_array = 0;
 861
 862  byte_array=bundle_get_str_array(b, "foo", &len_byte_array);
 863  // byte_array = { "aaa\0", "bbb\0", "ccc\0" }, and len_byte_array = 3
 864
 865  bundle_free(b);
 866  @endcode
 867  */
 868 API int bundle_set_byte_array_element(bundle *b, const char *key, const unsigned int idx, const void *val, const size_t size);
 869
 870 /**
 871  * @brief               Get string value from key
 872  * @pre                 b must be a valid bundle object.
 873  * @post                None
 874  * @see                 bundle_add_str()
 875  * @param[in]   b       bundle object
 876  * @param[in]   key     key
 877  * @param[out]  str returned value
 878  * @return              Operation result
 879  * @retval              0 on success
 880  * @retval              -1 on failure
 881  * @remark              Do not free str!
 882                                 When -1 is returned, errno is set to one of the following values; \n
 883                                 EINVAL : b is invalid \n
 884                                 ENOKEY : No key exists \n
 885                                 EKEYREJECTED : invalid key (NULL or sth) \n
 886  @code
 887  #include <bundle.h>
 888  bundle *b = bundle_create(); // Create new bundle object
 889  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 890
 891  char *v = NULL;
 892  bundle_get_str(b, "foo_key", &v);      // v = "bar_val"
 893
 894  bundle_free(b);        // After freeing b, v becomes a dangling pointer.
 895  v = NULL;
 896  @endcode
 897  */
 898 API int bundle_get_str(bundle *b, const char *key, char **str);
 899
 900 /**
 901  * @brief               Get byte value from key
 902  * @pre                 b must be a valid bundle object.
 903  * @post                None
 904  * @see                 bundle_add_byte()
 905  * @param[in]   b       bundle object
 906  * @param[in]   key     key
 907  * @param[out]  byte returned value
 908  * @param[out]  size Size of byte
 909  * @return              Operation result
 910  * @retval              0 on success
 911  * @retval              -1 on failure
 912  * @remark              Do not free str!
 913                                 When -1 is returned, errno is set to one of the following values; \n
 914                                 EINVAL : b is invalid \n
 915                                 ENOKEY : No key exists \n
 916                                 EKEYREJECTED : invalid key (NULL or sth) \n
 917  @code
 918  #include <bundle.h>
 919  bundle *b = bundle_create(); // Create new bundle object
 920  bundle_add_byte(b, "foo", "bar\0", 4); // add a key-val pair
 921
 922  unsigned char *v = NULL;
 923  bundle_get_str(b, "foo", &v);  // v = "bar\0"
 924
 925  bundle_free(b);        // After freeing b, v becomes a dangling pointer.
 926  @endcode
 927  */
 928 API int bundle_get_byte(bundle *b, const char *key, void **byte, size_t *size);
 929
 930 /**
 931  * @brief               Get byte array value from key
 932  * @pre                 b must be a valid bundle object.
 933  * @post                None
 934  * @see                 bundle_add_str_array()
 935  * @see                 bundle_set_str_array_element()
 936  * @param[in]   b       bundle object
 937  * @param[in]   key     key
 938  * @param[out]  byte_array returned value
 939  * @param[out]  len     array length
 940  * @param[out]  array_element_size      an array of sizes of each byte_array element
 941  * @return              Operation result
 942  * @retval              0 on success
 943  * @retval              -1 on failure
 944  * @remark              Do not free str!
 945                                 When -1 is returned, errno is set to one of the following values; \n
 946                                 EINVAL : b is invalid \n
 947                                 ENOKEY : No key exists \n
 948                                 EKEYREJECTED : invalid key (NULL or sth) \n
 949  @code
 950  #include <bundle.h>
 951  bundle *b = bundle_create();
 952  bundle_add_byte_array(b, "foo", NULL, 3);
 953  bundle_set_byte_array_element(b, "foo", 0, "aaa\0", 4);
 954  bundle_set_byte_array_element(b, "foo", 1, "bbb\0", 4);
 955  bundle_set_byte_array_element(b, "foo", 2, "ccc\0", 4);
 956
 957  char **byte_array = NULL;
 958  int len_byte_array = 0;
 959  size_t *size_byte_array = NULL;
 960
 961  byte_array = bundle_get_str_array(b, "foo", &len_byte_array, &size_byte_array);
 962  // byte_array = { "aaa\0", "bbb\0", "ccc\0" }, len_byte_array = 3, and size_byte_array = { 4, 4, 4 }
 963
 964  bundle_free(b);
 965  @endcode
 966  */
 967 API int bundle_get_byte_array(bundle *b, const char *key, void ***byte_array, unsigned int *len, unsigned int **array_element_size);
 968
 969
 970 #ifdef __cplusplus
 971 }
 972 #endif
 973
 974 /**
 975  * @}
 976  * @}
 977  */
 978
 979 #endif  /* __BUNDLE_H__ */