Initial Import
[profile/ivi/bundle.git] / 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__ */