Tizen Native API
6.5
|
A simple string-based dictionary ADT.
Required Header
#include <bundle.h>
Overview
Bundle is a string based Dictionary ADT. A dictionary is an ordered or unordered list of key element pairs, where keys are used to locate elements in the list.
Functions | |
bundle * | bundle_create (void) |
Creates a bundle object. | |
int | bundle_free (bundle *b) |
Frees the given bundle object with key-value pairs in it. | |
int | bundle_add_str_array (bundle *b, const char *key, const char **str_array, const int len) |
Adds a strings array type key-value pair into a given bundle. | |
int | bundle_del (bundle *b, const char *key) |
Deletes a key-value object with the given key. | |
const char ** | bundle_get_str_array (bundle *b, const char *key, int *len) |
Gets a string array from a given key. | |
int | bundle_get_count (bundle *b) |
Gets the number of bundle items. | |
int | bundle_get_type (bundle *b, const char *key) |
Gets the type of the value with a given key. | |
bundle * | bundle_dup (bundle *b_from) |
Duplicates a given bundle object. | |
void | bundle_foreach (bundle *b, bundle_iterator_t iter, void *user_data) |
Iterates a callback function for each key-value pair in a given bundle. | |
int | bundle_keyval_get_type (bundle_keyval_t *kv) |
Gets the type of a key-value pair. | |
int | bundle_keyval_type_is_array (bundle_keyval_t *kv) |
Determines whether the type of a key-value pair is an array. | |
int | bundle_keyval_get_basic_val (bundle_keyval_t *kv, void **val, size_t *size) |
Gets the value and size of the value from a key-value pair of basic type. | |
int | bundle_keyval_get_array_val (bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size) |
Gets the value array, length of the array, and size of each array item. | |
int | bundle_encode (bundle *b, bundle_raw **r, int *len) |
Encodes a bundle to the bundle_raw format (uses base64 format). | |
bundle * | bundle_decode (const bundle_raw *r, const int len) |
Deserializes bundle_raw and gets the bundle object. | |
int | bundle_add_str (bundle *b, const char *key, const char *str) |
Adds a string type key-value pair into a bundle. | |
int | bundle_add_byte (bundle *b, const char *key, const void *bytes, const size_t size) |
Adds a byte sequence type key-value pair into a bundle. | |
int | bundle_get_str (bundle *b, const char *key, char **str) |
Gets the string value with the given key. | |
int | bundle_get_byte (bundle *b, const char *key, void **bytes, size_t *size) |
Gets the byte sequence with the given key. | |
int | bundle_add_byte_array (bundle *b, const char *key, const unsigned int len) |
Adds an 'array of byte sequences' type key-value pair into a bundle. | |
int | bundle_set_byte_array_element (bundle *b, const char *key, const unsigned int idx, const void *bytes, const size_t size) |
Sets an element of an array of byte sequences. | |
int | bundle_get_byte_array (bundle *b, const char *key, void ***byte_array, unsigned int *len, unsigned int **array_element_size) |
Gets the array of byte sequences with the given key. | |
Typedefs | |
typedef struct _bundle_t | bundle |
The bundle handle. | |
typedef unsigned char | bundle_raw |
The encoded data type. | |
typedef struct keyval_t | bundle_keyval_t |
The key-value pair handle. | |
typedef void(* | bundle_iterator_t )(const char *key, const int type, const bundle_keyval_t *kv, void *user_data) |
Called for every key-value pair. |
Typedef Documentation
typedef struct _bundle_t bundle |
The bundle handle.
- Since :
- 2.3
typedef void(* bundle_iterator_t)(const char *key, const int type, const bundle_keyval_t *kv, void *user_data) |
Called for every key-value pair.
- Since :
- 2.3
- Parameters:
-
[in] key The key of key-value pair [in] type The type of bundle [in] kv The handle of key-value pair [in] user_data The user data
- See also:
- bundle_foreach()
typedef struct keyval_t bundle_keyval_t |
typedef unsigned char bundle_raw |
Enumeration Type Documentation
enum bundle_error_e |
Enumeration for error codes of Bundle.
- Since :
- 2.3
- Enumerator:
enum bundle_type |
enum bundle_type_property |
Function Documentation
int bundle_add_byte | ( | bundle * | b, |
const char * | key, | ||
const void * | bytes, | ||
const size_t | size | ||
) |
Adds a byte sequence type key-value pair into a bundle.
The bundle will contain a copy of the added byte sequence.
- Since :
- 2.3
- Parameters:
-
[in] b The bundle object [in] key The key [in] bytes The byte sequence [in] size The byte sequence size in bytes
- Returns:
- The operation result
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_EXISTS Key already exists BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
- Precondition:
- b must be a valid bundle object.
- See also:
- bundle_get_byte()
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_add_byte(b, "foo", "bar\0", 4); // Add a key-value pair int number = 12345; bundle_add_byte(b, "number", &number, sizeof(int)); bundle_free(b);
int bundle_add_byte_array | ( | bundle * | b, |
const char * | key, | ||
const unsigned int | len | ||
) |
Adds an 'array of byte sequences' type key-value pair into a bundle.
- Since :
- 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.
- Parameters:
-
[in] b The bundle object [in] key The key [in] len The length of the array to be created
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
BUNDLE_ERROR_NONE Successful BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_EXISTS Key already exists BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
int bundle_add_str | ( | bundle * | b, |
const char * | key, | ||
const char * | str | ||
) |
Adds a string type key-value pair into a bundle.
- Since :
- 2.3
- Parameters:
-
[in] b The bundle object [in] key The key [in] str The string type value
- Returns:
- The operation result
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_EXISTS Key already exists BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
- Precondition:
- b must be a valid bundle object.
- See also:
- bundle_get_str()
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_add_str(b, "foo", "bar"); // Add a key-value pair bundle_free(b);
int bundle_add_str_array | ( | bundle * | b, |
const char * | key, | ||
const char ** | str_array, | ||
const int | len | ||
) |
Adds a strings array type key-value pair into a given bundle.
- Since :
- 2.3
- Parameters:
-
[in] b The bundle object [in] key The key [in] str_array The string type value; if NULL
, an empty array is created; you can change an item with[in] len The length of the array
- Returns:
- The operation result
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_EXISTS Key already exists BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
- Precondition:
- b must be a valid bundle object.
- See also:
- bundle_get_str_array()
#include <bundle.h> char *sa = {"aaa", "bbb", "ccc"}; // String array of length 3 bundle *b = bundle_create(); bundle_add_str_array(b, "foo", sa, 3); // Add a key-value pair bundle_free(b);
bundle* bundle_create | ( | void | ) |
Creates a bundle object.
- Since :
- 2.3
- Remarks:
- The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
- Returns:
- The bundle object,
NULL
- Failure
- Exceptions:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
- See also:
- bundle_free()
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_free(b); // Free the bundle
bundle* bundle_decode | ( | const bundle_raw * | r, |
const int | len | ||
) |
Deserializes bundle_raw and gets the bundle object.
- Since :
- 2.3
- 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().
- Parameters:
-
[in] r The bundle_raw data to be converted to bundle object [in] len The size of r
- Returns:
- The bundle object,
NULL
- Failure
- Exceptions:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- r must be a valid bundle object.
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair bundle_raw *encoded_b; int len; bundle_encode(b, &encoded_b, &len); // Encode b bundle *b_dup; b_dup = bundle_decode(encoded_b, len); // Decoded bundle object bundle_free(b); free(encoded_b); bundle_free(b_dup);
int bundle_del | ( | bundle * | b, |
const char * | key | ||
) |
Deletes a key-value object with the given key.
- Since :
- 2.3
- Parameters:
-
[in] b The bundle object [in] key The given key
- Returns:
- The operation result
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
- Precondition:
- b must be a valid bundle object.
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair bundle_del(b, "foo_key"); // Delete "foo_key" from b bundle_free(b);
bundle* bundle_dup | ( | bundle * | b_from | ) |
Duplicates a given bundle object.
- Since :
- 2.4
- 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().
- Parameters:
-
[in] b_from The bundle object to be duplicated
- Returns:
- The new bundle object,
NULL
- Failure
- Exceptions:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- b_from must be a valid bundle object.
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair bundle *b_dup = bundle_dup(b); // Duplicate b bundle_free(b); bundle_free(b_dup);
int bundle_encode | ( | bundle * | b, |
bundle_raw ** | r, | ||
int * | len | ||
) |
Encodes a bundle to the bundle_raw format (uses base64 format).
- Since :
- 2.3
- Parameters:
-
[in] b The bundle object [out] r The returned bundle_raw data(byte data) r MUST BE FREED by free(r) [out] len The size of r (in bytes)
- Returns:
- The size of the raw data
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- b must be a valid bundle object.
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair bundle_raw *r; int len; bundle_encode(b, &r, &len); // Encode b bundle_free(b);
void bundle_foreach | ( | bundle * | b, |
bundle_iterator_t | iter, | ||
void * | user_data | ||
) |
Iterates a callback function for each key-value pair in a given bundle.
Supports all types of values.
- Since :
- 2.3
- Remarks:
- The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
This function supports all types.
- Parameters:
-
[in] b The bundle object [in] iter The iteration callback function [in] user_data The data for the callback function
- Exceptions:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- b must be a valid bundle object.
- See also:
- bundle_keyval_get_type()
- bundle_keyval_type_is_array()
- bundle_keyval_get_basic_val()
- bundle_keyval_get_array_val()
#include <stdio.h> #include <bundle.h> void sample_cb(const char *key, const int type, const bundle_keyval_t *kv, void *user_data) { void *basic_val = NULL; size_t basic_size = 0; void **array_val = NULL; int array_len = 0; size_t *array_elem_size = NULL; printf("Key:%s, Type:%d\n", key, type); if (bundle_keyval_type_is_array(kv)) { bundle_keyval_get_array_val(kv, &array_val, &array_len, &array_elem_size); // Do something } else { bundle_keyval_get_basic_val(kv, &basic_val, &basic_size); // Do something } } int main(void) { bundle *b = bundle_create(); // Create a new bundle object bundle_add_str(b, "k1", "v1"); // Add a key-value pair bundle_add_byte(b, "k2", "v2", 3); // Add a key-value pair char *s_arr[] = {"abc", "bcd", "cde"}; bundle_add_str_array(b, "k3", s_arr, 3); // Add a key-value pair bundle_foreach(b, sample_cb, NULL); // Iterate sample_cb() for each key/value return 0; }
int bundle_free | ( | bundle * | b | ) |
Frees the given bundle object with key-value pairs in it.
- Since :
- 2.3
- Parameters:
-
[in] b The bundle object to be freed
- Returns:
- The operation result
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- b must be a valid bundle object.
- See also:
- bundle_create()
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_free(b); // Free the bundle
int bundle_get_byte | ( | bundle * | b, |
const char * | key, | ||
void ** | bytes, | ||
size_t * | size | ||
) |
Gets the byte sequence with the given key.
- Since :
- 2.3
- Remarks:
- You must not free bytes.
- Parameters:
-
[in] b The bundle object [in] key The key [out] bytes The byte sequence [out] size The byte sequence size in bytes
- Returns:
- The operation result
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
- Precondition:
- b must be a valid bundle object.
- See also:
- bundle_add_byte()
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_add_byte(b, "foo", "bar\0", 4); // Add a string to the bundle int number = 12345; bundle_add_byte(b, "number", (const void**)&number, sizeof(int)); // Add an integer to the bundle unsigned char *v = NULL; size_t v_size; bundle_get_byte(b, "foo", (void**)&v, &v_size); // v = "bar\0" int *n = NULL; size_t n_size; bundle_get_byte(b, "number", (void**)&n, &n_size); // number = 12345 bundle_free(b); // After freeing b, v and n become a dangling pointer
int bundle_get_byte_array | ( | bundle * | b, |
const char * | key, | ||
void *** | byte_array, | ||
unsigned int * | len, | ||
unsigned int ** | array_element_size | ||
) |
Gets the array of byte sequences with the given key.
- Since :
- 5.5
- Remarks:
- You should not release byte_array, len and array_element_size. byte_array, len and array_element_size will be released when the bundle containing them is released with bundle_free().
- Parameters:
-
[in] b The bundle object [in] key The key [out] byte_array The array pointer of the byte value [out] len The array length [out] array_element_size An array of sizes of each byte_array element
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
BUNDLE_ERROR_NONE Successful BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
int bundle_get_count | ( | bundle * | b | ) |
Gets the number of bundle items.
- Since :
- 2.3
- Parameters:
-
[in] b The bundle object
- Returns:
- The number of bundle items
- Precondition:
- b must be a valid bundle object.
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_add_str(b, "key1", "val1"); // Add a key-value pair int count = bundle_get_count(b); // count = 1 bundle_add_str(b, "key2", "val2"); // Add another key-value pair count = bundle_get_count(b); // count = 2 bundle_free(b);
int bundle_get_str | ( | bundle * | b, |
const char * | key, | ||
char ** | str | ||
) |
Gets the string value with the given key.
- Since :
- 2.3
- Remarks:
- You must not free str.
- Parameters:
-
[in] b The bundle object [in] key The key [out] str The returned value
- Returns:
- The operation result
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
- Precondition:
- b must be a valid bundle object.
- See also:
- bundle_add_str()
#include <bundle.h> bundle *b = bundle_create(); // Create a new bundle object bundle_add_str(b, "foo_key", "bar_val"); // Add a key-value pair char *v = NULL; bundle_get_str(b, "foo_key", &v); // v = "bar_val" bundle_free(b); // After freeing b, v becomes a dangling pointer v = NULL;
const char** bundle_get_str_array | ( | bundle * | b, |
const char * | key, | ||
int * | len | ||
) |
Gets a string array from a given key.
- Since :
- 2.3
- Remarks:
- You MUST NOT free or modify the returned string.
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
- Parameters:
-
[in] b The bundle object [in] key The key [out] len The array length
- Returns:
- The pointer to the array of strings,
NULL
- Key not found
- Exceptions:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
- Precondition:
- b must be a valid bundle object.
- See also:
- bundle_add_str_array()
#include <bundle.h> bundle *b = bundle_create(); char *sa = {"aaa", "bbb", "ccc"}; // String array of length 3 bundle_add_str_array(b, "foo", sa, 3); // Add a key-value pair char **str_array = NULL; int len_str_array = 0; str_array=bundle_get_str_array(b, "foo", &len_str_array); // str_array = {"aaa", "bbb", "ccc"}, and len_str_array = 3 bundle_free(b);
int bundle_get_type | ( | bundle * | b, |
const char * | key | ||
) |
Gets the type of the value with a given key.
- Since :
- 2.3
- Remarks:
- The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
- Parameters:
-
[in] b A bundle [in] key A key in the bundle
- Returns:
- The type of a key in b
- Exceptions:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
- Precondition:
- b must be a valid bundle object.
- See also:
- bundle_type
int bundle_keyval_get_array_val | ( | bundle_keyval_t * | kv, |
void *** | array_val, | ||
unsigned int * | array_len, | ||
size_t ** | array_element_size | ||
) |
Gets the value array, length of the array, and size of each array item.
- Since :
- 2.3
- Parameters:
-
[in] kv A bundle_keyval_t object [out] array_val The array pointer of values [out] array_len The length of array_val [out] array_element_size The array of size of each array element
- Returns:
- The operation result
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- kv must be a valid bundle_keyval_t object.
- Postcondition:
- array_val, array_len, array_element_size are set.
- See also:
- bundle_foreach()
int bundle_keyval_get_basic_val | ( | bundle_keyval_t * | kv, |
void ** | val, | ||
size_t * | size | ||
) |
Gets the value and size of the value from a key-value pair of basic type.
- Since :
- 2.3
- Remarks:
- You must not free val.
- Parameters:
-
[in] kv A bundle_keyval_t object [out] val The value [out] size The size of val
- Returns:
- The operation result
- Return values:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- kv must be a valid bundle_keyval_t object.
- Postcondition:
- val and size are set.
- See also:
- bundle_foreach()
int bundle_keyval_get_type | ( | bundle_keyval_t * | kv | ) |
Gets the type of a key-value pair.
- Since :
- 2.3
- Remarks:
- The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
- Parameters:
-
[in] kv A bundle_keyval_t object
- Returns:
- The type of kv,
-1
- Failure
- Exceptions:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- kv must be a valid bundle_keyval_t object.
- See also:
- bundle_foreach()
int bundle_keyval_type_is_array | ( | bundle_keyval_t * | kv | ) |
Determines whether the type of a key-value pair is an array.
- Since :
- 2.3
- Remarks:
- The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
- Parameters:
-
[in] kv A bundle_keyval_t object
- Returns:
- The operation result
1
- kv is an array0
- kv is not an array
- Exceptions:
-
BUNDLE_ERROR_NONE Success BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- kv must be a valid bundle_keyval_t object.
- See also:
- bundle_foreach()
int bundle_set_byte_array_element | ( | bundle * | b, |
const char * | key, | ||
const unsigned int | idx, | ||
const void * | bytes, | ||
const size_t | size | ||
) |
Sets an element of an array of byte sequences.
The array will contain its own copy of the added value.
- Since :
- 5.5
- Parameters:
-
[in] b The bundle object [in] key The key [in] idx The index of the array element to be changed [in] bytes The byte sequence [in] size The byte sequence size in bytes
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
BUNDLE_ERROR_NONE Successful BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available BUNDLE_ERROR_OUT_OF_MEMORY Out of memory BUNDLE_ERROR_ARRAY_INDEX_OUT_OF_BOUNDS The index is out of bounds of the array