/*
- * Copyright (c) 2000 - 2016 Samsung Electronics Co., Ltd. All rights reserved.
+ * Copyright (c) 2000 - 2020 Samsung Electronics Co., Ltd. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
extern "C" {
# endif
-#define API __attribute__((visibility("default")))
-#define likely(x) __builtin_expect(x, 1)
-#define unlikely(x) __builtin_expect(x, 0)
-
/**
* @brief Enumeration for error codes of Bundle.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
BUNDLE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
BUNDLE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
BUNDLE_ERROR_KEY_NOT_AVAILABLE = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Required key not available */
- BUNDLE_ERROR_KEY_EXISTS = TIZEN_ERROR_BUNDLE | 0x01 /**< Key exists */
+ BUNDLE_ERROR_KEY_EXISTS = TIZEN_ERROR_BUNDLE | 0x01, /**< Key exists */
+ BUNDLE_ERROR_ARRAY_INDEX_OUT_OF_BOUNDS = TIZEN_ERROR_BUNDLE | 0x02 /**< The index is out of bounds of the array */
} bundle_error_e;
/**
* @brief Called for every key-value pair.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @param[in] key The key of key-value pair
+ * @param[in] type The type of bundle
+ * @param[in] kv The handle of key-value pair
+ * @param[in] user_data The user data
* @see bundle_foreach()
*/
-typedef void (*bundle_iterator_t) (const char *key, const int type, const bundle_keyval_t *kv, void *user_data );
+typedef void (*bundle_iterator_t) (const char *key, const int type, const bundle_keyval_t *kv, void *user_data);
/**
* @brief Creates a bundle object.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
* @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
- * @return The bundle object
- * @retval @c NULL - Failure
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ * @return The bundle object,
+ * @c NULL - Failure
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
* @see bundle_free()
*
* @code
bundle_free(b); // Free the bundle
* @endcode
*/
-API bundle *bundle_create(void);
+bundle *bundle_create(void);
/**
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
* @param[in] b The bundle object to be freed
* @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
* @pre @a b must be a valid bundle object.
* @see bundle_create()
*
bundle_free(b); // Free the bundle
* @endcode
*/
-API int bundle_free(bundle *b);
+int bundle_free(bundle *b);
/**
* @param[in] str_array The string type value; if @c NULL, an empty array is created; you can change an item with
* @param[in] len The length of the array
* @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
- * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
+ * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
* @pre @a b must be a valid bundle object.
* @see bundle_get_str_array()
*
bundle_free(b);
* @endcode
*/
-API int bundle_add_str_array(bundle *b, const char *key, const char **str_array, const int len);
+int bundle_add_str_array(bundle *b, const char *key, const char **str_array, const int len);
/**
* @param[in] b The bundle object
* @param[in] key The given key
* @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
* @pre @a b must be a valid bundle object.
*
* @code
bundle_free(b);
* @endcode
*/
-API int bundle_del(bundle *b, const char *key);
+int bundle_del(bundle *b, const char *key);
/**
* @param[in] b The bundle object
* @param[in] key The key
* @param[out] len The array length
- * @return The pointer to the array of strings
- * @retval @c NULL - Key not found
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @exception BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @return The pointer to the array of strings,
+ * @c NULL - Key not found
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @exception #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
* @pre @a b must be a valid bundle object.
* @see bundle_add_str_array()
*
bundle_free(b);
* @endcode
*/
-API const char **bundle_get_str_array(bundle *b, const char *key, int *len);
+const char **bundle_get_str_array(bundle *b, const char *key, int *len);
/**
bundle_free(b);
* @endcode
*/
-API int bundle_get_count(bundle *b);
+int bundle_get_count(bundle *b);
/**
* @param[in] b A bundle
* @param[in] key A key in the bundle
* @return The type of a key in @a b
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @exception BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @exception #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
* @pre @a b must be a valid bundle object.
- * @see bundle_type_t
+ * @see bundle_type
*/
-API int bundle_get_type(bundle *b, const char *key);
+int bundle_get_type(bundle *b, const char *key);
/**
* @brief Duplicates a given bundle object.
* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
* @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
+ * The returned value should be released using bundle_free().
* @param[in] b_from The bundle object to be duplicated
- * @return The new bundle object
- * @retval @c NULL - Failure
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @pre @a b must be a valid bundle object.
+ * @return The new bundle object,
+ * @c NULL - Failure
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @pre @a b_from must be a valid bundle object.
*
* @code
#include <bundle.h>
bundle_free(b_dup);
* @endcode
*/
-API bundle *bundle_dup(bundle *b_from);
+bundle *bundle_dup(bundle *b_from);
/**
* @param[in] b The bundle object
* @param[in] iter The iteration callback function
* @param[in] user_data The data for the callback function
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
* @pre @a b must be a valid bundle object.
* @see bundle_keyval_get_type()
* @see bundle_keyval_type_is_array()
}
* @endcode
*/
-API void bundle_foreach(bundle *b, bundle_iterator_t iter, void *user_data);
+void bundle_foreach(bundle *b, bundle_iterator_t iter, void *user_data);
/**
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
* @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
* @param[in] kv A bundle_keyval_t object
- * @return The type of @a kv
- * @retval @c -1 - Failure
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @return The type of @a kv,
+ * @c -1 - Failure
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
* @pre @a kv must be a valid bundle_keyval_t object.
* @see bundle_foreach()
*/
-API int bundle_keyval_get_type(bundle_keyval_t *kv);
+int bundle_keyval_get_type(bundle_keyval_t *kv);
/**
* @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
* @param[in] kv A bundle_keyval_t object
* @return The operation result
- * @retval @c 1 - @a kv is an array
- * @retval @c 0 - @a kv is not an array
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @c 1 - @a kv is an array
+ * @c 0 - @a kv is not an array
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
* @pre @a kv must be a valid bundle_keyval_t object.
* @see bundle_foreach()
*/
-API int bundle_keyval_type_is_array(bundle_keyval_t *kv);
+int bundle_keyval_type_is_array(bundle_keyval_t *kv);
/**
* @param[out] val The value
* @param[out] size The size of @a val
* @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
* @pre @a kv must be a valid bundle_keyval_t object.
* @post @a val and @a size are set.
* @see bundle_foreach()
*/
-API int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *size);
+int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *size);
/**
* @param[out] array_len The length of @a array_val
* @param[out] array_element_size The array of size of each array element
* @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
* @pre @a kv must be a valid bundle_keyval_t object.
- * @post @a array_val, @a array_len, @a array_item_size are set.
+ * @post @a array_val, @a array_len, @a array_element_size are set.
* @see bundle_foreach()
*/
-API int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size);
+int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size);
/**
* @a r MUST BE FREED by free(r)
* @param[out] len The size of @a r (in bytes)
* @return The size of the raw data
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
* @pre @a b must be a valid bundle object.
*
* @code
bundle_free(b);
* @endcode
*/
-API int bundle_encode(bundle *b, bundle_raw **r, int *len);
+int bundle_encode(bundle *b, bundle_raw **r, int *len);
/**
* @brief Deserializes bundle_raw and gets the bundle object.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
* @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
+ * The returned value should be released using bundle_free().
* @param[in] r The bundle_raw data to be converted to bundle object
* @param[in] len The size of @a r
- * @return The bundle object
- * @retval @c NULL - Failure
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @pre @a b must be a valid bundle object.
+ * @return The bundle object,
+ * @c NULL - Failure
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @pre @a r must be a valid bundle object.
*
* @code
#include <bundle.h>
bundle_free(b_dup);
* @endcode
*/
-API bundle *bundle_decode(const bundle_raw *r, const int len);
+bundle *bundle_decode(const bundle_raw *r, const int len);
/**
* @param[in] key The key
* @param[in] str The string type value
* @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
- * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
+ * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
* @pre @a b must be a valid bundle object.
* @see bundle_get_str()
* @code
bundle_free(b);
* @endcode
*/
-API int bundle_add_str(bundle *b, const char *key, const char *str);
+int bundle_add_str(bundle *b, const char *key, const char *str);
/**
- * @brief Adds a byte type key-value pair into a bundle.
+ * @brief Adds a byte sequence type key-value pair into a bundle.
+ * @details The bundle will contain a copy of the added byte sequence.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
* @param[in] b The bundle object
* @param[in] key The key
- * @param[in] byte The string type value
- * @param[in] size The size of @a byte
+ * @param[in] bytes The byte sequence
+ * @param[in] size The byte sequence size in bytes
* @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
- * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
+ * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
* @pre @a b must be a valid bundle object.
* @see bundle_get_byte()
*
bundle_free(b);
* @endcode
*/
-API int bundle_add_byte(bundle *b, const char *key, const void *byte, const size_t size);
+int bundle_add_byte(bundle *b, const char *key, const void *bytes, const size_t size);
/**
* @param[in] key The key
* @param[out] str The returned value
* @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
* @pre @a b must be a valid bundle object.
* @see bundle_add_str()
*
v = NULL;
* @endcode
*/
-API int bundle_get_str(bundle *b, const char *key, char **str);
+int bundle_get_str(bundle *b, const char *key, char **str);
/**
- * @brief Gets the byte value with the given key.
+ * @brief Gets the byte sequence with the given key.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
- * @remarks You must not free @a byte.
+ * @remarks You must not free @a bytes.
* @param[in] b The bundle object
* @param[in] key The key
- * @param[out] byte The returned value
- * @param[out] size The size of the byte
+ * @param[out] bytes The byte sequence
+ * @param[out] size The byte sequence size in bytes
* @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
* @pre @a b must be a valid bundle object.
* @see bundle_add_byte()
*
bundle_free(b); // After freeing b, v and n become a dangling pointer
* @endcode
*/
-API int bundle_get_byte(bundle *b, const char *key, void **byte, size_t *size);
+int bundle_get_byte(bundle *b, const char *key, void **bytes, size_t *size);
+
+/**
+ * @brief Adds an 'array of byte sequences' type key-value pair into a bundle.
+ * @since_tizen 5.5
+ * @remarks To set the value of the byte array element, you should use bundle_set_byte_array_element().
+ * This function is only for creating a buffer of the byte array.
+ *
+ * @param[in] b The bundle object
+ * @param[in] key The key
+ * @param[in] len The length of the array to be created
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ * @retval #BUNDLE_ERROR_NONE Successful
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
+ * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ *
+ * @see bundle_get_byte_array()
+ * @see bundle_set_byte_array_element()
+ */
+int bundle_add_byte_array(bundle *b, const char *key, const unsigned int len);
+
+/**
+ * @brief Sets an element of an array of byte sequences.
+ * @details The array will contain its own copy of the added value.
+ * @since_tizen 5.5
+ *
+ * @param[in] b The bundle object
+ * @param[in] key The key
+ * @param[in] idx The index of the array element to be changed
+ * @param[in] bytes The byte sequence
+ * @param[in] size The byte sequence size in bytes
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ * @retval #BUNDLE_ERROR_NONE Successful
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #BUNDLE_ERROR_ARRAY_INDEX_OUT_OF_BOUNDS The index is out of bounds of the array
+ *
+ * @see bundle_add_byte_array()
+ * @see bundle_get_byte_array()
+ */
+int bundle_set_byte_array_element(bundle *b, const char *key, const unsigned int idx, const void *bytes, const size_t size);
+
+/**
+ * @brief Gets the array of byte sequences with the given key.
+ * @since_tizen 5.5
+ * @remarks You should not release @a byte_array, @a len and @a array_element_size.
+ * @a byte_array, @a len and @a array_element_size will be released when the bundle containing them is released with bundle_free().
+ *
+ * @param[in] b The bundle object
+ * @param[in] key The key
+ * @param[out] byte_array The array pointer of the byte value
+ * @param[out] len The array length
+ * @param[out] array_element_size An array of sizes of each @a byte_array element
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ * @retval #BUNDLE_ERROR_NONE Successful
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ *
+ * @see bundle_add_byte_array()
+ * @see bundle_set_byte_array_element()
+*/
+int bundle_get_byte_array(bundle *b, const char *key, void ***byte_array, unsigned int *len, unsigned int **array_element_size);
#ifdef __cplusplus
}
projects / platform / core / base / bundle.git / blobdiff