2 * Copyright (c) 2000 - 2016 Samsung Electronics Co., Ltd. All rights reserved.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @brief This file declares API of the bundle library.
26 * @addtogroup CORE_LIB_BUNDLE_MODULE
32 #include <tizen_error.h>
38 #define API __attribute__((visibility("default")))
39 #define likely(x) __builtin_expect(x, 1)
40 #define unlikely(x) __builtin_expect(x, 0)
43 * @brief Enumeration for error codes of Bundle.
44 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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 */
56 * @brief The bundle handle.
57 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
59 typedef struct _bundle_t bundle;
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()
68 typedef unsigned char bundle_raw;
72 * @brief Enumeration for key-value pair types.
73 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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 */
83 * @brief Enumeration for bundle types.
84 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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 */
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
101 typedef struct keyval_t bundle_keyval_t;
105 * @brief Called for every key-value pair.
106 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
107 * @see bundle_foreach()
109 typedef void (*bundle_iterator_t) (const char *key, const int type, const bundle_keyval_t *kv, void *user_data );
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
124 bundle *b = bundle_create(); // Create a new bundle object
125 bundle_free(b); // Free the bundle
128 API bundle *bundle_create(void);
132 * @brief Frees the given bundle object with key-value pairs in it.
133 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
134 * @param[in] b The bundle object to be freed
135 * @return The operation result
136 * @retval BUNDLE_ERROR_NONE Success
137 * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
138 * @pre @a b must be a valid bundle object.
139 * @see bundle_create()
143 bundle *b = bundle_create(); // Create a new bundle object
144 bundle_free(b); // Free the bundle
147 API int bundle_free(bundle *b);
151 * @brief Adds a strings array type key-value pair into a given bundle.
152 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
153 * @param[in] b The bundle object
154 * @param[in] key The key
155 * @param[in] str_array The string type value; if @c NULL, an empty array is created; you can change an item with
156 * @param[in] len The length of the array
157 * @return The operation result
158 * @retval BUNDLE_ERROR_NONE Success
159 * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
160 * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
161 * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
162 * @pre @a b must be a valid bundle object.
163 * @see bundle_get_str_array()
167 char *sa = {"aaa", "bbb", "ccc"}; // String array of length 3
168 bundle *b = bundle_create();
169 bundle_add_str_array(b, "foo", sa, 3); // Add a key-value pair
173 API int bundle_add_str_array(bundle *b, const char *key, const char **str_array, const int len);
177 * @brief Deletes a key-value object with the given key.
178 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
179 * @param[in] b The bundle object
180 * @param[in] key The given key
181 * @return The operation result
182 * @retval BUNDLE_ERROR_NONE Success
183 * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
184 * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
185 * @pre @a b must be a valid bundle object.
189 bundle *b = bundle_create(); // Create a new bundle object
190 bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair
191 bundle_del(b, "foo_key"); // Delete "foo_key" from b
196 API int bundle_del(bundle *b, const char *key);
200 * @brief Gets a string array from a given key.
201 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
202 * @remarks You MUST NOT free or modify the returned string. \n
203 * The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
204 * @param[in] b The bundle object
205 * @param[in] key The key
206 * @param[out] len The array length
207 * @return The pointer to the array of strings
208 * @retval @c NULL - Key not found
209 * @exception BUNDLE_ERROR_NONE Success
210 * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
211 * @exception BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
212 * @pre @a b must be a valid bundle object.
213 * @see bundle_add_str_array()
217 bundle *b = bundle_create();
218 char *sa = {"aaa", "bbb", "ccc"}; // String array of length 3
219 bundle_add_str_array(b, "foo", sa, 3); // Add a key-value pair
221 char **str_array = NULL;
222 int len_str_array = 0;
224 str_array=bundle_get_str_array(b, "foo", &len_str_array);
225 // str_array = {"aaa", "bbb", "ccc"}, and len_str_array = 3
230 API const char **bundle_get_str_array(bundle *b, const char *key, int *len);
234 * @brief Gets the number of bundle items.
235 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
236 * @param[in] b The bundle object
237 * @return The number of bundle items
238 * @pre @a b must be a valid bundle object.
242 bundle *b = bundle_create(); // Create a new bundle object
243 bundle_add_str(b, "key1", "val1"); // Add a key-value pair
244 int count = bundle_get_count(b); // count = 1
245 bundle_add_str(b, "key2", "val2"); // Add another key-value pair
246 count = bundle_get_count(b); // count = 2
251 API int bundle_get_count(bundle *b);
255 * @brief Gets the type of the value with a given key.
256 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
257 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
258 * @param[in] b A bundle
259 * @param[in] key A key in the bundle
260 * @return The type of a key in @a b
261 * @exception BUNDLE_ERROR_NONE Success
262 * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
263 * @exception BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
264 * @pre @a b must be a valid bundle object.
267 API int bundle_get_type(bundle *b, const char *key);
271 * @brief Duplicates a given bundle object.
272 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
273 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
274 * @param[in] b_from The bundle object to be duplicated
275 * @return The new bundle object
276 * @retval @c NULL - Failure
277 * @exception BUNDLE_ERROR_NONE Success
278 * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
279 * @pre @a b must be a valid bundle object.
283 bundle *b = bundle_create(); // Create a new bundle object
284 bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair
285 bundle *b_dup = bundle_dup(b); // Duplicate b
291 API bundle *bundle_dup(bundle *b_from);
295 * @brief Iterates a callback function for each key-value pair in a given bundle.
296 * @details Supports all types of values.
297 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
298 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section. \n
299 * This function supports all types.
300 * @param[in] b The bundle object
301 * @param[in] iter The iteration callback function
302 * @param[in] user_data The data for the callback function
303 * @exception BUNDLE_ERROR_NONE Success
304 * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
305 * @pre @a b must be a valid bundle object.
306 * @see bundle_keyval_get_type()
307 * @see bundle_keyval_type_is_array()
308 * @see bundle_keyval_get_basic_val()
309 * @see bundle_keyval_get_array_val()
315 sample_cb(const char *key, const int type, const bundle_keyval_t *kv, void *user_data)
317 void *basic_val = NULL;
318 size_t basic_size = 0;
319 void **array_val = NULL;
321 size_t *array_elem_size = NULL;
323 printf("Key:%s, Type:%d\n", key, type);
324 if (bundle_keyval_type_is_array(kv)) {
325 bundle_keyval_get_array_val(kv, &array_val, &array_len, &array_elem_size);
329 bundle_keyval_get_basic_val(kv, &basic_val, &basic_size);
336 bundle *b = bundle_create(); // Create a new bundle object
337 bundle_add_str(b, "k1", "v1"); // Add a key-value pair
338 bundle_add_byte(b, "k2", "v2", 3); // Add a key-value pair
339 char *s_arr[] = {"abc", "bcd", "cde"};
340 bundle_add_str_array(b, "k3", s_arr, 3); // Add a key-value pair
341 bundle_foreach(b, sample_cb, NULL); // Iterate sample_cb() for each key/value
347 API void bundle_foreach(bundle *b, bundle_iterator_t iter, void *user_data);
351 * @brief Gets the type of a key-value pair.
352 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
353 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
354 * @param[in] kv A bundle_keyval_t object
355 * @return The type of @a kv
356 * @retval @c -1 - Failure
357 * @exception BUNDLE_ERROR_NONE Success
358 * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
359 * @pre @a kv must be a valid bundle_keyval_t object.
360 * @see bundle_foreach()
362 API int bundle_keyval_get_type(bundle_keyval_t *kv);
366 * @brief Determines whether the type of a key-value pair is an array.
367 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
368 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
369 * @param[in] kv A bundle_keyval_t object
370 * @return The operation result
371 * @retval @c 1 - @a kv is an array
372 * @retval @c 0 - @a kv is not an array
373 * @exception BUNDLE_ERROR_NONE Success
374 * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
375 * @pre @a kv must be a valid bundle_keyval_t object.
376 * @see bundle_foreach()
378 API int bundle_keyval_type_is_array(bundle_keyval_t *kv);
382 * @brief Gets the value and size of the value from a key-value pair of basic type.
383 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
384 * @remarks You must not free @a val.
385 * @param[in] kv A bundle_keyval_t object
386 * @param[out] val The value
387 * @param[out] size The size of @a val
388 * @return The operation result
389 * @retval BUNDLE_ERROR_NONE Success
390 * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
391 * @pre @a kv must be a valid bundle_keyval_t object.
392 * @post @a val and @a size are set.
393 * @see bundle_foreach()
395 API int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *size);
399 * @brief Gets the value array, length of the array, and size of each array item.
400 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
401 * @param[in] kv A bundle_keyval_t object
402 * @param[out] array_val The array pointer of values
403 * @param[out] array_len The length of @a array_val
404 * @param[out] array_element_size The array of size of each array element
405 * @return The operation result
406 * @retval BUNDLE_ERROR_NONE Success
407 * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
408 * @pre @a kv must be a valid bundle_keyval_t object.
409 * @post @a array_val, @a array_len, @a array_item_size are set.
410 * @see bundle_foreach()
412 API int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size);
416 * @brief Encodes a bundle to the bundle_raw format (uses base64 format).
417 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
418 * @param[in] b The bundle object
419 * @param[out] r The returned bundle_raw data(byte data)
420 * @a r MUST BE FREED by free(r)
421 * @param[out] len The size of @a r (in bytes)
422 * @return The size of the raw data
423 * @retval BUNDLE_ERROR_NONE Success
424 * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
425 * @pre @a b must be a valid bundle object.
429 bundle *b = bundle_create(); // Create a new bundle object
430 bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair
433 bundle_encode(b, &r, &len); // Encode b
438 API int bundle_encode(bundle *b, bundle_raw **r, int *len);
442 * @brief Deserializes bundle_raw and gets the bundle object.
443 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
444 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
445 * @param[in] r The bundle_raw data to be converted to bundle object
446 * @param[in] len The size of @a r
447 * @return The bundle object
448 * @retval @c NULL - Failure
449 * @exception BUNDLE_ERROR_NONE Success
450 * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
451 * @pre @a b must be a valid bundle object.
455 bundle *b = bundle_create(); // Create a new bundle object
456 bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair
458 bundle_raw *encoded_b;
460 bundle_encode(b, &encoded_b, &len); // Encode b
463 b_dup = bundle_decode(encoded_b, len); // Decoded bundle object
470 API bundle *bundle_decode(const bundle_raw *r, const int len);
474 * @brief Adds a string type key-value pair into a bundle.
475 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
476 * @param[in] b The bundle object
477 * @param[in] key The key
478 * @param[in] str The string type value
479 * @return The operation result
480 * @retval BUNDLE_ERROR_NONE Success
481 * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
482 * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
483 * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
484 * @pre @a b must be a valid bundle object.
485 * @see bundle_get_str()
488 bundle *b = bundle_create(); // Create a new bundle object
489 bundle_add_str(b, "foo", "bar"); // Add a key-value pair
494 API int bundle_add_str(bundle *b, const char *key, const char *str);
498 * @brief Adds a byte type key-value pair into a bundle.
499 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
500 * @param[in] b The bundle object
501 * @param[in] key The key
502 * @param[in] byte The string type value
503 * @param[in] size The size of @a byte
504 * @return The operation result
505 * @retval BUNDLE_ERROR_NONE Success
506 * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
507 * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
508 * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
509 * @pre @a b must be a valid bundle object.
510 * @see bundle_get_byte()
514 bundle *b = bundle_create(); // Create a new bundle object
515 bundle_add_byte(b, "foo", "bar\0", 4); // Add a key-value pair
518 bundle_add_byte(b, "number", &number, sizeof(int));
523 API int bundle_add_byte(bundle *b, const char *key, const void *byte, const size_t size);
527 * @brief Gets the string value with the given key.
528 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
529 * @remarks You must not free str.
530 * @param[in] b The bundle object
531 * @param[in] key The key
532 * @param[out] str The returned value
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_str()
542 bundle *b = bundle_create(); // Create a new bundle object
543 bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair
546 bundle_get_str(b, "foo_key", &v); // v = "bar_val"
548 bundle_free(b); // After freeing b, v becomes a dangling pointer
552 API int bundle_get_str(bundle *b, const char *key, char **str);
556 * @brief Gets the byte value with the given key.
557 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
558 * @remarks You must not free @a byte.
559 * @param[in] b The bundle object
560 * @param[in] key The key
561 * @param[out] byte The returned value
562 * @param[out] size The size of the byte
563 * @return The operation result
564 * @retval BUNDLE_ERROR_NONE Success
565 * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
566 * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
567 * @pre @a b must be a valid bundle object.
568 * @see bundle_add_byte()
572 bundle *b = bundle_create(); // Create a new bundle object
573 bundle_add_byte(b, "foo", "bar\0", 4); // Add a string to the bundle
575 bundle_add_byte(b, "number", (const void**)&number, sizeof(int)); // Add an integer to the bundle
577 unsigned char *v = NULL;
579 bundle_get_byte(b, "foo", (void**)&v, &v_size); // v = "bar\0"
582 bundle_get_byte(b, "number", (void**)&n, &n_size); // number = 12345
584 bundle_free(b); // After freeing b, v and n become a dangling pointer
587 API int bundle_get_byte(bundle *b, const char *key, void **byte, size_t *size);
597 #endif /* __BUNDLE_H__ */