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