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