include/bundle.h

   1 /*
   2  * Copyright (c) 2000 - 2020 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 /**
  39  * @brief Enumeration for error codes of Bundle.
  40  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  41  */
  42 typedef enum {
  43         BUNDLE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  44         BUNDLE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  45         BUNDLE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  46         BUNDLE_ERROR_KEY_NOT_AVAILABLE = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Required key not available */
  47         BUNDLE_ERROR_KEY_EXISTS = TIZEN_ERROR_BUNDLE | 0x01, /**< Key exists */
  48         BUNDLE_ERROR_ARRAY_INDEX_OUT_OF_BOUNDS = TIZEN_ERROR_BUNDLE | 0x02 /**< The index is out of bounds of the array */
  49 } bundle_error_e;
  50
  51
  52 /**
  53  * @brief The bundle handle.
  54  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  55  */
  56 typedef struct _bundle_t bundle;
  57
  58
  59 /**
  60  * @brief The encoded data type.
  61  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  62  * @see bundle_encode()
  63  * @see bundle_decode()
  64  */
  65 typedef unsigned char bundle_raw;
  66
  67
  68 /**
  69  * @brief Enumeration for key-value pair types.
  70  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  71  */
  72 enum bundle_type_property {
  73         BUNDLE_TYPE_ARRAY = 0x0100, /**< Array type */
  74         BUNDLE_TYPE_PRIMITIVE = 0x0200, /**< Primitive type */
  75         BUNDLE_TYPE_MEASURABLE = 0x0400 /**< Measurable type */
  76 };
  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 /**
  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 /**
 102  * @brief Called for every key-value pair.
 103  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 104  * @param[in] key The key of key-value pair
 105  * @param[in] type The type of bundle
 106  * @param[in] kv The handle of key-value pair
 107  * @param[in] user_data The user data
 108  * @see bundle_foreach()
 109  */
 110 typedef void (*bundle_iterator_t) (const char *key, const int type, const bundle_keyval_t *kv, void *user_data);
 111
 112
 113 /**
 114  * @brief Creates a bundle object.
 115  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 116  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 117  * @return The bundle object,
 118  *         @c NULL - Failure
 119  * @exception #BUNDLE_ERROR_NONE Success
 120  * @exception #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 121  * @see bundle_free()
 122  *
 123  * @code
 124  #include <bundle.h>
 125  bundle *b = bundle_create(); // Create a new bundle object
 126  bundle_free(b); // Free the bundle
 127  * @endcode
 128  */
 129 bundle *bundle_create(void);
 130
 131
 132 /**
 133  * @brief Frees the given bundle object with key-value pairs in it.
 134  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 135  * @param[in] b The bundle object to be freed
 136  * @return The operation result
 137  * @retval #BUNDLE_ERROR_NONE Success
 138  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 139  * @pre @a b must be a valid bundle object.
 140  * @see bundle_create()
 141  *
 142  * @code
 143  #include <bundle.h>
 144  bundle *b = bundle_create(); // Create a new bundle object
 145  bundle_free(b); // Free the bundle
 146  * @endcode
 147  */
 148 int bundle_free(bundle *b);
 149
 150
 151 /**
 152  * @brief Adds a strings array type key-value pair into a given bundle.
 153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 154  * @param[in] b The bundle object
 155  * @param[in] key The key
 156  * @param[in] str_array The string type value; if @c NULL, an empty array is created; you can change an item with
 157  * @param[in] len The length of the array
 158  * @return The operation result
 159  * @retval #BUNDLE_ERROR_NONE Success
 160  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 161  * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
 162  * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 163  * @pre @a b must be a valid bundle object.
 164  * @see bundle_get_str_array()
 165  *
 166  * @code
 167  #include <bundle.h>
 168  char *sa = {"aaa", "bbb", "ccc"}; // String array of length 3
 169  bundle *b = bundle_create();
 170  bundle_add_str_array(b, "foo", sa, 3); // Add a key-value pair
 171  bundle_free(b);
 172  * @endcode
 173  */
 174 int bundle_add_str_array(bundle *b, const char *key, const char **str_array, const int len);
 175
 176
 177 /**
 178  * @brief Deletes a key-value object with the given key.
 179  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 180  * @param[in] b The bundle object
 181  * @param[in] key The given key
 182  * @return The operation result
 183  * @retval #BUNDLE_ERROR_NONE Success
 184  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 185  * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
 186  * @pre @a b must be a valid bundle object.
 187  *
 188  * @code
 189  #include <bundle.h>
 190  bundle *b = bundle_create(); // Create a new bundle object
 191  bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair
 192  bundle_del(b, "foo_key"); // Delete "foo_key" from b
 193
 194  bundle_free(b);
 195  * @endcode
 196  */
 197 int bundle_del(bundle *b, const char *key);
 198
 199
 200 /**
 201  * @brief Gets a string array from a given key.
 202  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 203  * @remarks You MUST NOT free or modify the returned string. \n
 204  *          The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 205  * @param[in] b The bundle object
 206  * @param[in] key The key
 207  * @param[out] len The array length
 208  * @return The pointer to the array of strings,
 209  *         @c NULL - Key not found
 210  * @exception #BUNDLE_ERROR_NONE Success
 211  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @exception #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
 213  * @pre @a b must be a valid bundle object.
 214  * @see bundle_add_str_array()
 215  *
 216  * @code
 217  #include <bundle.h>
 218  bundle *b = bundle_create();
 219  char *sa = {"aaa", "bbb", "ccc"}; // String array of length 3
 220  bundle_add_str_array(b, "foo", sa, 3); // Add a key-value pair
 221
 222  char **str_array = NULL;
 223  int len_str_array = 0;
 224
 225  str_array=bundle_get_str_array(b, "foo", &len_str_array);
 226  // str_array = {"aaa", "bbb", "ccc"}, and len_str_array = 3
 227
 228  bundle_free(b);
 229  * @endcode
 230  */
 231 const char **bundle_get_str_array(bundle *b, const char *key, int *len);
 232
 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  *
 241  * @code
 242  #include <bundle.h>
 243  bundle *b = bundle_create(); // Create a new bundle object
 244  bundle_add_str(b, "key1", "val1"); // Add a key-value pair
 245  int count = bundle_get_count(b); // count = 1
 246  bundle_add_str(b, "key2", "val2"); // Add another key-value pair
 247  count = bundle_get_count(b); // count = 2
 248
 249  bundle_free(b);
 250  * @endcode
 251  */
 252 int bundle_get_count(bundle *b);
 253
 254
 255 /**
 256  * @brief Gets the type of the value with a given key.
 257  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 258  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 259  * @param[in] b A bundle
 260  * @param[in] key A key in the bundle
 261  * @return The type of a key in @a b
 262  * @exception #BUNDLE_ERROR_NONE Success
 263  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 264  * @exception #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
 265  * @pre @a b must be a valid bundle object.
 266  * @see bundle_type
 267  */
 268 int bundle_get_type(bundle *b, const char *key);
 269
 270
 271 /**
 272  * @brief Duplicates a given bundle object.
 273  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 274  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 275  *          The returned value should be released using bundle_free().
 276  * @param[in] b_from The bundle object to be duplicated
 277  * @return The new bundle object,
 278  *         @c NULL - Failure
 279  * @exception #BUNDLE_ERROR_NONE Success
 280  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 281  * @pre @a b_from must be a valid bundle object.
 282  *
 283  * @code
 284  #include <bundle.h>
 285  bundle *b = bundle_create(); // Create a new bundle object
 286  bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair
 287  bundle *b_dup = bundle_dup(b); // Duplicate b
 288
 289  bundle_free(b);
 290  bundle_free(b_dup);
 291  * @endcode
 292  */
 293 bundle *bundle_dup(bundle *b_from);
 294
 295
 296 /**
 297  * @brief Iterates a callback function for each key-value pair in a given bundle.
 298  * @details Supports all types of values.
 299  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 300  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section. \n
 301  *          This function supports all types.
 302  * @param[in] b The bundle object
 303  * @param[in] iter The iteration callback function
 304  * @param[in] user_data The data for the callback function
 305  * @exception #BUNDLE_ERROR_NONE Success
 306  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 307  * @pre @a b must be a valid bundle object.
 308  * @see bundle_keyval_get_type()
 309  * @see bundle_keyval_type_is_array()
 310  * @see bundle_keyval_get_basic_val()
 311  * @see bundle_keyval_get_array_val()
 312  *
 313  * @code
 314  #include <stdio.h>
 315  #include <bundle.h>
 316  void
 317  sample_cb(const char *key, const int type, const bundle_keyval_t *kv, void *user_data)
 318  {
 319      void *basic_val = NULL;
 320      size_t basic_size = 0;
 321      void **array_val = NULL;
 322      int array_len = 0;
 323      size_t *array_elem_size = NULL;
 324
 325      printf("Key:%s, Type:%d\n", key, type);
 326      if (bundle_keyval_type_is_array(kv)) {
 327          bundle_keyval_get_array_val(kv, &array_val, &array_len, &array_elem_size);
 328          // Do something
 329      }
 330      else {
 331          bundle_keyval_get_basic_val(kv, &basic_val, &basic_size);
 332          // Do something
 333      }
 334  }
 335
 336  int main(void)
 337  {
 338      bundle *b = bundle_create(); // Create a new bundle object
 339      bundle_add_str(b, "k1", "v1"); // Add a key-value pair
 340      bundle_add_byte(b, "k2", "v2", 3); // Add a key-value pair
 341      char *s_arr[] = {"abc", "bcd", "cde"};
 342      bundle_add_str_array(b, "k3", s_arr, 3); // Add a key-value pair
 343      bundle_foreach(b, sample_cb, NULL); // Iterate sample_cb() for each key/value
 344
 345      return 0;
 346  }
 347  * @endcode
 348  */
 349 void bundle_foreach(bundle *b, bundle_iterator_t iter, void *user_data);
 350
 351
 352 /**
 353  * @brief Gets the type of a key-value pair.
 354  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 355  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 356  * @param[in] kv A bundle_keyval_t object
 357  * @return The type of @a kv,
 358  *         @c -1 - Failure
 359  * @exception #BUNDLE_ERROR_NONE Success
 360  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 361  * @pre @a kv must be a valid bundle_keyval_t object.
 362  * @see bundle_foreach()
 363  */
 364 int bundle_keyval_get_type(bundle_keyval_t *kv);
 365
 366
 367 /**
 368  * @brief Determines whether the type of a key-value pair is an array.
 369  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 370  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 371  * @param[in] kv A bundle_keyval_t object
 372  * @return The operation result
 373  *         @c 1 - @a kv is an array
 374  *         @c 0 - @a kv is not an array
 375  * @exception #BUNDLE_ERROR_NONE Success
 376  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 377  * @pre @a kv must be a valid bundle_keyval_t object.
 378  * @see bundle_foreach()
 379  */
 380 int bundle_keyval_type_is_array(bundle_keyval_t *kv);
 381
 382
 383 /**
 384  * @brief Gets the value and size of the value from a key-value pair of basic type.
 385  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 386  * @remarks You must not free @a val.
 387  * @param[in] kv A bundle_keyval_t object
 388  * @param[out] val The value
 389  * @param[out] size The size of @a val
 390  * @return The operation result
 391  * @retval #BUNDLE_ERROR_NONE Success
 392  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 393  * @pre @a kv must be a valid bundle_keyval_t object.
 394  * @post @a val and @a size are set.
 395  * @see bundle_foreach()
 396  */
 397 int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *size);
 398
 399
 400 /**
 401  * @brief Gets the value array, length of the array, and size of each array item.
 402  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 403  * @param[in] kv A bundle_keyval_t object
 404  * @param[out] array_val The array pointer of values
 405  * @param[out] array_len The length of @a array_val
 406  * @param[out] array_element_size The array of size of each array element
 407  * @return The operation result
 408  * @retval #BUNDLE_ERROR_NONE Success
 409  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 410  * @pre @a kv must be a valid bundle_keyval_t object.
 411  * @post @a array_val, @a array_len, @a array_element_size are set.
 412  * @see bundle_foreach()
 413  */
 414 int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size);
 415
 416
 417 /**
 418  * @brief Encodes a bundle to the bundle_raw format (uses base64 format).
 419  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 420  * @param[in] b The bundle object
 421  * @param[out] r The returned bundle_raw data(byte data)
 422  *               @a r MUST BE FREED by free(r)
 423  * @param[out] len The size of @a r (in bytes)
 424  * @return The size of the raw data
 425  * @retval #BUNDLE_ERROR_NONE Success
 426  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 427  * @pre @a b must be a valid bundle object.
 428  *
 429  * @code
 430  #include <bundle.h>
 431  bundle *b = bundle_create(); // Create a new bundle object
 432  bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair
 433  bundle_raw *r;
 434  int len;
 435  bundle_encode(b, &r, &len); // Encode b
 436
 437  bundle_free(b);
 438  * @endcode
 439  */
 440 int bundle_encode(bundle *b, bundle_raw **r, int *len);
 441
 442
 443 /**
 444  * @brief Deserializes bundle_raw and gets the bundle object.
 445  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 446  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 447  *          The returned value should be released using bundle_free().
 448  * @param[in] r The bundle_raw data to be converted to bundle object
 449  * @param[in] len The size of @a r
 450  * @return The bundle object,
 451  *         @c NULL - Failure
 452  * @exception #BUNDLE_ERROR_NONE Success
 453  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 454  * @pre @a r must be a valid bundle object.
 455  *
 456  * @code
 457  #include <bundle.h>
 458  bundle *b = bundle_create(); // Create a new bundle object
 459  bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair
 460
 461  bundle_raw *encoded_b;
 462  int len;
 463  bundle_encode(b, &encoded_b, &len); // Encode b
 464
 465  bundle *b_dup;
 466  b_dup = bundle_decode(encoded_b, len); // Decoded bundle object
 467
 468  bundle_free(b);
 469  free(encoded_b);
 470  bundle_free(b_dup);
 471  * @endcode
 472  */
 473 bundle *bundle_decode(const bundle_raw *r, const int len);
 474
 475
 476 /**
 477  * @brief Adds a string type key-value pair into a bundle.
 478  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 479  * @param[in] b The bundle object
 480  * @param[in] key The key
 481  * @param[in] str The string type value
 482  * @return The operation result
 483  * @retval #BUNDLE_ERROR_NONE Success
 484  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 485  * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
 486  * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 487  * @pre @a b must be a valid bundle object.
 488  * @see bundle_get_str()
 489  * @code
 490  #include <bundle.h>
 491  bundle *b = bundle_create(); // Create a new bundle object
 492  bundle_add_str(b, "foo", "bar"); // Add a key-value pair
 493
 494  bundle_free(b);
 495  * @endcode
 496  */
 497 int bundle_add_str(bundle *b, const char *key, const char *str);
 498
 499
 500 /**
 501  * @brief Adds a byte sequence type key-value pair into a bundle.
 502  * @details The bundle will contain a copy of the added byte sequence.
 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] bytes The byte sequence
 507  * @param[in] size The byte sequence size in bytes
 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 int bundle_add_byte(bundle *b, const char *key, const void *bytes, 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 int bundle_get_str(bundle *b, const char *key, char **str);
 557
 558
 559 /**
 560  * @brief Gets the byte sequence with the given key.
 561  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 562  * @remarks You must not free @a bytes.
 563  * @param[in] b The bundle object
 564  * @param[in] key The key
 565  * @param[out] bytes The byte sequence
 566  * @param[out] size The byte sequence size in bytes
 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 int bundle_get_byte(bundle *b, const char *key, void **bytes, size_t *size);
 592
 593 /**
 594  * @brief Adds an 'array of byte sequences' type key-value pair into a bundle.
 595  * @since_tizen 5.5
 596  * @remarks To set the value of the byte array element, you should use bundle_set_byte_array_element().
 597  *          This function is only for creating a buffer of the byte array.
 598  *
 599  * @param[in]   b                       The bundle object
 600  * @param[in]   key                     The key
 601  * @param[in]   len                     The length of the array to be created
 602  * @return      @c 0 on success,
 603  *              otherwise a negative error value
 604  * @retval #BUNDLE_ERROR_NONE Successful
 605  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 606  * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
 607  * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 608  *
 609  * @see bundle_get_byte_array()
 610  * @see bundle_set_byte_array_element()
 611  */
 612 int bundle_add_byte_array(bundle *b, const char *key, const unsigned int len);
 613
 614 /**
 615  * @brief Sets an element of an array of byte sequences.
 616  * @details The array will contain its own copy of the added value.
 617  * @since_tizen 5.5
 618  *
 619  * @param[in]   b                       The bundle object
 620  * @param[in]   key                     The key
 621  * @param[in]   idx                     The index of the array element to be changed
 622  * @param[in]   bytes                   The byte sequence
 623  * @param[in]   size                    The byte sequence size in bytes
 624  * @return      @c 0 on success,
 625  *              otherwise a negative error value
 626  * @retval #BUNDLE_ERROR_NONE Successful
 627  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 628  * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
 629  * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 630  * @retval #BUNDLE_ERROR_ARRAY_INDEX_OUT_OF_BOUNDS The index is out of bounds of the array
 631  *
 632  * @see bundle_add_byte_array()
 633  * @see bundle_get_byte_array()
 634  */
 635 int bundle_set_byte_array_element(bundle *b, const char *key, const unsigned int idx, const void *bytes, const size_t size);
 636
 637 /**
 638  * @brief Gets the array of byte sequences with the given key.
 639  * @since_tizen 5.5
 640  * @remarks You should not release @a byte_array, @a len and @a array_element_size.
 641  *          @a byte_array, @a len and @a array_element_size will be released when the bundle containing them is released with bundle_free().
 642  *
 643  * @param[in]   b                       The bundle object
 644  * @param[in]   key                     The key
 645  * @param[out]  byte_array              The array pointer of the byte value
 646  * @param[out]  len                     The array length
 647  * @param[out]  array_element_size      An array of sizes of each @a byte_array element
 648  * @return      @c 0 on success,
 649  *              otherwise a negative error value
 650  * @retval #BUNDLE_ERROR_NONE Successful
 651  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 652  * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
 653  *
 654  * @see bundle_add_byte_array()
 655  * @see bundle_set_byte_array_element()
 656 */
 657 int bundle_get_byte_array(bundle *b, const char *key, void ***byte_array, unsigned int *len, unsigned int **array_element_size);
 658
 659 #ifdef __cplusplus
 660 }
 661 #endif
 662
 663 /**
 664  * @}
 665  */
 666
 667 #endif /* __BUNDLE_H__ */