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