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