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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  53  */
  54 typedef enum
  55 {
  56         BUNDLE_ERROR_NONE = TIZEN_ERROR_NONE,                                   /**< Successful */
  57         BUNDLE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,                 /**< Out of memory */
  58         BUNDLE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,         /**< Invalid parameter */
  59         BUNDLE_ERROR_KEY_NOT_AVAILABLE = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Required key not available */
  60         BUNDLE_ERROR_KEY_EXISTS = TIZEN_ERROR_BUNDLE | 0x01     /**< Key exists */
  61 } bundle_error_e;
  62
  63 /**
  64  * @brief The bundle handle.
  65  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  66  */
  67 typedef struct _bundle_t bundle;
  68
  69 /**
  70  * @brief The encoded data type.
  71  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  72  * @see bundle_encode()
  73  * @see bundle_decode()
  74  */
  75 typedef unsigned char bundle_raw;
  76
  77
  78 /**
  79  * @brief Enumeration for key-value pair types.
  80  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  81  */
  82 enum bundle_type_property {
  83         BUNDLE_TYPE_ARRAY = 0x0100,     /**< Array type */
  84         BUNDLE_TYPE_PRIMITIVE = 0x0200, /**< Primitive type */
  85         BUNDLE_TYPE_MEASURABLE = 0x0400 /**< Measurable type */
  86 };
  87
  88 /**
  89  * @brief Enumeration for bundle types.
  90  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  91  */
  92 enum bundle_type {
  93         BUNDLE_TYPE_NONE = -1,  /**< None */
  94         BUNDLE_TYPE_ANY = 0,    /**< Any type */
  95         BUNDLE_TYPE_STR = 1 | BUNDLE_TYPE_MEASURABLE,   /**< String type (Default) */
  96         BUNDLE_TYPE_STR_ARRAY = BUNDLE_TYPE_STR | BUNDLE_TYPE_ARRAY | BUNDLE_TYPE_MEASURABLE,   /**< String array type */
  97         BUNDLE_TYPE_BYTE = 2,   /**< Byte type */
  98         BUNDLE_TYPE_BYTE_ARRAY = BUNDLE_TYPE_BYTE | BUNDLE_TYPE_ARRAY   /**< Byte array type */
  99 };
 100
 101 /**
 102  * @brief The key-value pair handle.
 103  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 104  * @see bundle_iterator_t
 105  */
 106 typedef struct keyval_t bundle_keyval_t;
 107
 108
 109 /**
 110  * @brief Called for every key-value pair.
 111  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 112  * @see bundle_foreach()
 113  */
 114 typedef void (*bundle_iterator_t) (
 115                 const char *key,
 116                 const int type,
 117                 const bundle_keyval_t *kv,
 118                 void *user_data
 119 );
 120
 121 /**
 122  * @brief Creates a bundle object.
 123  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 124  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 125  * @return      The bundle object
 126  * @retval      @c NULL - Failure
 127  * @exception BUNDLE_ERROR_NONE Success
 128  * @exception BUNDLE_ERROR_OUT_OF_MEMORY        Out of memory
 129  * @see                 bundle_free()
 130  *
 131  @code
 132  #include <bundle.h>
 133  bundle *b = bundle_create(); // Create new bundle object
 134  bundle_free(b); // free bundle
 135  @endcode
 136  */
 137 API bundle*             bundle_create(void);
 138
 139 /**
 140  * @brief Frees the given bundle object with key-value pairs in it.
 141  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 142  * @param[in]   b       The bundle object to be freed
 143  * @return              The operation result;
 144  * @retval BUNDLE_ERROR_NONE    Success
 145  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 146  * @pre                 @a b must be a valid bundle object.
 147  * @see                 bundle_create()
 148  @code
 149  #include <bundle.h>
 150  bundle *b = bundle_create(); // Create new bundle object
 151  bundle_free(b); // free bundle
 152  @endcode
 153  */
 154 API int                 bundle_free(bundle *b);
 155
 156 /**
 157  * @brief Adds a strings array type key-value pair into a given bundle.
 158  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 159  * @param[in]   b       The bundle object
 160  * @param[in]   key     The key
 161  * @param[in]   str_array The string type value; if @c NULL, an empty array is created; you can change an item with
 162  * @param[in]   len The length of the array
 163  * @return              The operation result
 164  * @retval BUNDLE_ERROR_NONE    Success
 165  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 166  * @retval BUNDLE_ERROR_KEY_EXISTS      Key already exists
 167  * @retval BUNDLE_ERROR_OUT_OF_MEMORY   Out of memory
 168  * @pre                 @a b must be a valid bundle object.
 169  * @see                 bundle_get_str_array()
 170  *
 171  @code
 172  #include <bundle.h>
 173  char *sa = { "aaa", "bbb", "ccc" };    // A string array of length 3
 174  bundle *b = bundle_create();
 175  bundle_add_str_array(b, "foo", sa, 3); // add a key-val pair
 176  bundle_free(b);
 177  @endcode
 178  */
 179 API int bundle_add_str_array(bundle *b, const char *key, const char **str_array, const int len);
 180
 181 /**
 182  * @brief Deletes a key-value object with the given key.
 183  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 184  * @param[in]   b       The bundle object
 185  * @param[in]   key     The given key
 186  * @return              The operation result
 187  * @retval BUNDLE_ERROR_NONE    Success
 188  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 189  * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE       Key not available
 190  * @pre                 @a b must be a valid bundle object.
 191  @code
 192  #include <bundle.h>
 193  bundle *b = bundle_create(); // Create new bundle object
 194  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 195  bundle_del(b, "foo_key"); // del "foo_key" from b
 196
 197  bundle_free(b);
 198  @endcode
 199  */
 200 API int                         bundle_del(bundle *b, const char* key);
 201
 202 /**
 203  * @brief Gets a string array from a given key.
 204  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 205  * @remarks             You MUST NOT free or modify the returned string!
 206  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 207  * @param[in]   b       The bundle object
 208  * @param[in]   key     The key
 209  * @param[out]  len     The array length
 210  * @return              The pointer to the array of strings
 211  * @retval              @c NULL - Key not found
 212  * @exception BUNDLE_ERROR_NONE Success
 213  * @exception BUNDLE_ERROR_INVALID_PARAMETER    Invalid parameter
 214  * @exception BUNDLE_ERROR_KEY_NOT_AVAILABLE    Key not available
 215  * @pre                 @a b must be a valid bundle object.
 216  * @see                 bundle_add_str_array()
 217  @code
 218  #include <bundle.h>
 219  bundle *b = bundle_create();
 220  char *sa = { "aaa", "bbb", "ccc" };    // A string array of length 3
 221  bundle_add_str_array(b, "foo", sa, 3); // add a key-val pair
 222
 223  char **str_array = NULL;
 224  int len_str_array = 0;
 225
 226  str_array=bundle_get_str_array(b, "foo", &len_str_array);
 227  // str_array = { "aaa", "bbb", "ccc" }, and len_str_array = 3
 228
 229  bundle_free(b);
 230  @endcode
 231  */
 232 API const char** bundle_get_str_array(bundle *b, const char *key,int *len);
 233
 234 /**
 235  * @brief Gets the number of bundle items.
 236  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 237  * @param[in]   b       The bundle object
 238  * @return              The number of bundle items
 239  * @pre                 @a b must be a valid bundle object.
 240  @code
 241  #include <bundle.h>
 242  bundle *b = bundle_create(); // Create new bundle object
 243  bundle_add_str(b, "key1", "val1"); //add a key-val pair
 244  int count = bundle_get_count(b);       // count=1
 245  bundle_add_str(b, "key2", "val2"); // add another key-val pair
 246  count = bundle_get_count(b); // count=2
 247
 248  bundle_free(b);
 249  @endcode
 250  */
 251 API int                         bundle_get_count(bundle *b);
 252
 253 /**
 254  * @brief Gets the type of a value with a given key.
 255  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 256  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 257  * @param[in]   b       A bundle
 258  * @param[in]   key     A key in the bundle
 259  * @return      The type of a key in @a b
 260  * @exception BUNDLE_ERROR_NONE Success
 261  * @exception BUNDLE_ERROR_INVALID_PARAMETER    Invalid parameter
 262  * @exception BUNDLE_ERROR_KEY_NOT_AVAILABLE    Key not available
 263  * @pre         @a b must be a valid bundle object.
 264  * @see         bundle_type_t
 265  @code
 266  @endcode
 267  */
 268 API int bundle_get_type(bundle *b, const char *key);
 269
 270 /**
 271  * @brief Duplicates a given bundle object.
 272  * @since_tizen 2.4
 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_from  the bundle object to be duplicated
 275  * @return              The new bundle object
 276  * @retval              @c NULL - Failure
 277  * @exception BUNDLE_ERROR_NONE Success
 278  * @exception BUNDLE_ERROR_INVALID_PARAMETER    Invalid parameter
 279  * @pre                 @a b must be a valid bundle object.
 280  @code
 281  #include <bundle.h>
 282  bundle *b = bundle_create(); // Create new bundle object
 283  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 284  bundle *b_dup = bundle_dup(b); // duplicate b
 285
 286  bundle_free(b);
 287  bundle_free(b_dup);
 288  @endcode
 289  */
 290 API bundle *            bundle_dup(bundle *b_from);
 291
 292 /**
 293  * @brief Iterates a callback function for each key-value pair in a given bundle.
 294  * @details Supports all types of values.
 295  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 296  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 297  * @remarks             This function supports all types.
 298  * @param[in]   b       The bundle object
 299  * @param[in]   iter    The iteration callback function
 300  * @param[in]   user_data       The data for the callback function
 301  * @exception BUNDLE_ERROR_NONE Success
 302  * @exception BUNDLE_ERROR_INVALID_PARAMETER    Invalid parameter
 303  * @pre                 @a b must be a valid bundle object.
 304  * @see                 bundle_keyval_get_type()
 305  * @see                 bundle_keyval_type_is_array()
 306  * @see                 bundle_keyval_get_basic_val()
 307  * @see                 bundle_keyval_get_array_val()
 308  @code
 309  #include <stdio.h>
 310  #include <bundle.h>
 311  void sample_cb(const char *key, const int type, const bundle_keyval_t *kv, void *user_data) {
 312    void *basic_val = NULL;
 313    size_t basic_size = 0;
 314    void **array_val = NULL;
 315    int array_len = 0;
 316    size_t *array_elem_size = NULL;
 317
 318    printf("Key:%s, Type:%d\n", key, type);
 319    if(bundle_keyval_type_is_array(kv)) {
 320      bundle_keyval_get_array_val(kv, &array_val, &array_len, &array_elem_size);
 321          // Do something...
 322    }
 323    else {
 324      bundle_keyval_get_basic_val(kv, &basic_val, &basic_size);
 325          // Do something...
 326    }
 327  }
 328
 329  int main(void) {
 330          bundle *b = bundle_create(); // Create new bundle object
 331          bundle_add_str(b, "k1", "v1"); // add a key-val pair
 332          bundle_add_byte(b, "k2", "v2", 3); // add a key-val pair
 333          char *s_arr[] = {"abc", "bcd", "cde"};
 334          bundle_add_str_array(b, "k3", s_arr, 3); // add a key-val pair
 335          bundle_foreach(b, sample_cb, NULL);    // iterate sample_cb() for each key/val
 336          return 0;
 337  }
 338  @endcode
 339  */
 340 API void                        bundle_foreach(bundle *b, bundle_iterator_t iter, void *user_data);
 341
 342 /**
 343  * @brief Gets the type of a key-value pair.
 344  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 345  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 346  * @param[in]   kv      A bundle_keyval_t object
 347  * @return      The type of @a kv
 348  * @retval      @c -1 - Failure
 349  * @exception BUNDLE_ERROR_NONE Success
 350  * @exception BUNDLE_ERROR_INVALID_PARAMETER    Invalid parameter
 351  * @pre         @a kv must be a valid bundle_keyval_t object.
 352  * @see         bundle_foreach()
 353  */
 354 API int bundle_keyval_get_type(bundle_keyval_t *kv);
 355
 356 /**
 357  * @brief Determines whether the  type of a key-value pair is array.
 358  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 359  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 360  * @param[in]   kv      A bundle_keyval_t object
 361  * @return              The operation result
 362  * @retval              @c 1 - @a kv is an array
 363  * @retval              @c 0 - @a kv is not an array
 364  * @exception BUNDLE_ERROR_NONE Success
 365  * @exception BUNDLE_ERROR_INVALID_PARAMETER    Invalid parameter
 366  * @pre         @a kv must be a valid bundle_keyval_t object.
 367  * @see         bundle_foreach()
 368  */
 369 API int bundle_keyval_type_is_array(bundle_keyval_t *kv);
 370
 371 /**
 372  * @brief Gets the value and size of the value from a key-value pair of basic type.
 373  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 374  * @remarks     You must not free @a val.
 375  * @param[in]   kv              A bundle_keyval_t object
 376  * @param[out]  val             The value
 377  * @param[out]  size    The size of @a val
 378  * @return      The operation result
 379  * @retval BUNDLE_ERROR_NONE    Success
 380  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 381  * @pre         @a kv must be a valid bundle_keyval_t object.
 382  * @post        @a val and @a size are set.
 383  * @see         bundle_foreach()
 384  */
 385 API int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *size);
 386
 387 /**
 388  * @brief Gets the value array, length of the array, and size of each array item.
 389  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 390  * @param[in]   kv              A bundle_keyval_t object
 391  * @param[out]  array_val       The array pointer of values
 392  * @param[out]  array_len       The length of @a array_val
 393  * @param[out]  array_element_size      The array of size of each array element
 394  * @return      The operation result
 395  * @retval BUNDLE_ERROR_NONE    Success
 396  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 397  * @pre         @a kv must be a valid bundle_keyval_t object.
 398  * @post        @a array_val, @a array_len, @a array_item_size are set.
 399  * @see         bundle_foreach()
 400  */
 401 API int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size);
 402
 403 /**
 404  * @brief Encodes a bundle to the bundle_raw format (uses base64 format).
 405  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 406  * @param[in]   b       The bundle object
 407  * @param[out]  r       The returned bundle_raw data(byte data)
 408  *                                      @a r MUST BE FREED by free(r)
 409  * @param[out]  len     The size of @a r (in bytes)
 410  * @return      The size of the raw data
 411  * @retval BUNDLE_ERROR_NONE    Success
 412  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 413  * @pre                 @a b must be a valid bundle object.
 414  @code
 415  #include <bundle.h>
 416  bundle *b = bundle_create(); // Create new bundle object
 417  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 418  bundle_raw *r;
 419  int len;
 420  bundle_encode(b, &r, &len);    // encode b
 421
 422  bundle_free(b);
 423  @endcode
 424  */
 425 API int                         bundle_encode(bundle *b, bundle_raw **r, int *len);
 426
 427 /**
 428  * @brief Deserializes bundle_raw and gets the bundle object.
 429  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 430  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 431  * @param[in]   r       The bundle_raw data to be converted to bundle object
 432  * @param[in]   len     The size of @a r
 433  * @return      The bundle object
 434  * @retval      @c NULL - Failure
 435  * @exception BUNDLE_ERROR_NONE Success
 436  * @exception BUNDLE_ERROR_INVALID_PARAMETER    Invalid parameter
 437  * @pre                 @a b must be a valid bundle object.
 438  @code
 439  #include <bundle.h>
 440  bundle *b = bundle_create(); // Create new bundle object
 441  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 442
 443  bundle_raw *encoded_b;
 444  int len;
 445  bundle_encode(b, &encoded_b, &len);    // encode b
 446
 447  bundle *b_dup;
 448  b_dup = bundle_decode(encoded_b, len); // decoded bundle object
 449
 450  bundle_free(b);
 451  free(encoded_b);
 452  bundle_free(b_dup);
 453  @endcode
 454  */
 455 API bundle *            bundle_decode(const bundle_raw *r, const int len);
 456
 457 /**
 458  * @brief Adds a string type key-value pair into a bundle.
 459  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 460  * @param[in]   b       The bundle object
 461  * @param[in]   key     The key
 462  * @param[in]   str The string type value
 463  * @return              The operation result
 464  * @retval BUNDLE_ERROR_NONE    Success
 465  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 466  * @retval BUNDLE_ERROR_KEY_EXISTS      Key already exists
 467  * @retval BUNDLE_ERROR_OUT_OF_MEMORY   Out of memory
 468  * @pre                 @a b must be a valid bundle object.
 469  * @see                 bundle_get_str()
 470  @code
 471  #include <bundle.h>
 472  bundle *b = bundle_create(); // Create new bundle object
 473  bundle_add_str(b, "foo", "bar"); // add a key-val pair
 474
 475  bundle_free(b);
 476  @endcode
 477  */
 478 API int bundle_add_str(bundle *b, const char *key, const char *str);
 479
 480 /**
 481  * @brief Adds a byte type key-value pair into a bundle.
 482  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 483  * @param[in]   b       The bundle object
 484  * @param[in]   key     The key
 485  * @param[in]   byte The string type value
 486  * @param[in]   size The size of @a byte
 487  * @return              The operation result
 488  * @retval BUNDLE_ERROR_NONE    Success
 489  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 490  * @retval BUNDLE_ERROR_KEY_EXISTS      Key already exists
 491  * @retval BUNDLE_ERROR_OUT_OF_MEMORY   Out of memory
 492  * @pre                 @a b must be a valid bundle object.
 493  * @see                 bundle_get_byte()
 494  @code
 495  #include <bundle.h>
 496  bundle *b = bundle_create(); // Create new bundle object
 497  bundle_add_byte(b, "foo", "bar\0", 4); // add a key-val pair
 498
 499  int number = 12345;
 500  bundle_add_byte(b, "number", &number, sizeof(int));
 501
 502  bundle_free(b);
 503  @endcode
 504  */
 505 API int bundle_add_byte(bundle *b, const char *key, const void *byte, const size_t size);
 506
 507 /**
 508  * @brief Gets the string value with the given key.
 509  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 510  * @remarks             You must not free str!
 511  * @param[in]   b       The bundle object
 512  * @param[in]   key     The key
 513  * @param[out]  str The returned value
 514  * @return              The operation result
 515  * @retval BUNDLE_ERROR_NONE    Success
 516  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 517  * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE       Key not available
 518  * @pre                 @a b must be a valid bundle object.
 519  * @see                 bundle_add_str()
 520  @code
 521  #include <bundle.h>
 522  bundle *b = bundle_create(); // Create new bundle object
 523  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 524
 525  char *v = NULL;
 526  bundle_get_str(b, "foo_key", &v);      // v = "bar_val"
 527
 528  bundle_free(b);        // After freeing b, v becomes a dangling pointer.
 529  v = NULL;
 530  @endcode
 531  */
 532 API int bundle_get_str(bundle *b, const char *key, char **str);
 533
 534 /**
 535  * @brief Gets the byte value with the given key.
 536  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 537  * @remarks             You must not free @a byte!
 538  * @param[in]   b       The bundle object
 539  * @param[in]   key     The key
 540  * @param[out]  byte The returned value
 541  * @param[out]  size The size of the byte
 542  * @return              The operation result
 543  * @retval BUNDLE_ERROR_NONE    Success
 544  * @retval BUNDLE_ERROR_INVALID_PARAMETER       Invalid parameter
 545  * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE       Key not available
 546  * @pre                 @a b must be a valid bundle object.
 547  * @see                 bundle_add_byte()
 548  @code
 549  #include <bundle.h>
 550  bundle *b = bundle_create(); // Create new bundle object
 551  bundle_add_byte(b, "foo", "bar\0", 4); // add string to bundle
 552  int number = 12345;
 553  bundle_add_byte(b, "number", (const void**)&number, sizeof(int)); // add integer to bundle
 554
 555  unsigned char *v = NULL;
 556  size_t v_size;
 557  bundle_get_byte(b, "foo", (void**)&v, &v_size);    // v = "bar\0"
 558  int *n = NULL;
 559  size_t n_size;
 560  bundle_get_byte(b, "number", (void**)&n, &n_size); // number = 12345
 561
 562  bundle_free(b);        // After freeing b, v and n becomes a dangling pointer.
 563  @endcode
 564  */
 565 API int bundle_get_byte(bundle *b, const char *key, void **byte, size_t *size);
 566
 567 #ifdef __cplusplus
 568 }
 569 #endif
 570
 571 /**
 572  * @}
 573  * @}
 574  */
 575
 576 #endif  /* __BUNDLE_H__ */