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