include/bundle.h

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