Tizen(Headless) 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

bundlebundle_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.
bundlebundle_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).
bundlebundle_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]keyThe key of key-value pair
[in]typeThe type of bundle
[in]kvThe handle of key-value pair
[in]user_dataThe user data
See also:
bundle_foreach()
typedef struct keyval_t bundle_keyval_t

The key-value pair handle.

Since :
2.3
See also:
bundle_iterator_t
typedef unsigned char bundle_raw

The encoded data type.

Since :
2.3
See also:
bundle_encode()
bundle_decode()

Enumeration Type Documentation

Enumeration for error codes of Bundle.

Since :
2.3
Enumerator:
BUNDLE_ERROR_NONE 

Successful

BUNDLE_ERROR_OUT_OF_MEMORY 

Out of memory

BUNDLE_ERROR_INVALID_PARAMETER 

Invalid parameter

BUNDLE_ERROR_KEY_NOT_AVAILABLE 

Required key not available

BUNDLE_ERROR_KEY_EXISTS 

Key exists

BUNDLE_ERROR_ARRAY_INDEX_OUT_OF_BOUNDS 

The index is out of bounds of the array

Enumeration for bundle types.

Since :
2.3
Enumerator:
BUNDLE_TYPE_NONE 

None

BUNDLE_TYPE_ANY 

Any type

BUNDLE_TYPE_STR 

String type (Default)

BUNDLE_TYPE_STR_ARRAY 

String array type

BUNDLE_TYPE_BYTE 

Byte type

BUNDLE_TYPE_BYTE_ARRAY 

Byte array type

Enumeration for key-value pair types.

Since :
2.3
Enumerator:
BUNDLE_TYPE_ARRAY 

Array type

BUNDLE_TYPE_PRIMITIVE 

Primitive type

BUNDLE_TYPE_MEASURABLE 

Measurable type


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]bThe bundle object
[in]keyThe key
[in]bytesThe byte sequence
[in]sizeThe byte sequence size in bytes
Returns:
The operation result
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_EXISTSKey already exists
BUNDLE_ERROR_OUT_OF_MEMORYOut 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]bThe bundle object
[in]keyThe key
[in]lenThe length of the array to be created
Returns:
0 on success, otherwise a negative error value
Return values:
BUNDLE_ERROR_NONESuccessful
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_EXISTSKey already exists
BUNDLE_ERROR_OUT_OF_MEMORYOut of memory
See also:
bundle_get_byte_array()
bundle_set_byte_array_element()
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]bThe bundle object
[in]keyThe key
[in]strThe string type value
Returns:
The operation result
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_EXISTSKey already exists
BUNDLE_ERROR_OUT_OF_MEMORYOut 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]bThe bundle object
[in]keyThe key
[in]str_arrayThe string type value; if NULL, an empty array is created; you can change an item with
[in]lenThe length of the array
Returns:
The operation result
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_EXISTSKey already exists
BUNDLE_ERROR_OUT_OF_MEMORYOut 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_NONESuccess
BUNDLE_ERROR_OUT_OF_MEMORYOut 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]rThe bundle_raw data to be converted to bundle object
[in]lenThe size of r
Returns:
The bundle object, NULL - Failure
Exceptions:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid 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]bThe bundle object
[in]keyThe given key
Returns:
The operation result
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_NOT_AVAILABLEKey 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_fromThe bundle object to be duplicated
Returns:
The new bundle object, NULL - Failure
Exceptions:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid 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]bThe bundle object
[out]rThe returned bundle_raw data(byte data) r MUST BE FREED by free(r)
[out]lenThe size of r (in bytes)
Returns:
The size of the raw data
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid 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]bThe bundle object
[in]iterThe iteration callback function
[in]user_dataThe data for the callback function
Exceptions:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid 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]bThe bundle object to be freed
Returns:
The operation result
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid 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]bThe bundle object
[in]keyThe key
[out]bytesThe byte sequence
[out]sizeThe byte sequence size in bytes
Returns:
The operation result
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_NOT_AVAILABLEKey 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]bThe bundle object
[in]keyThe key
[out]byte_arrayThe array pointer of the byte value
[out]lenThe array length
[out]array_element_sizeAn array of sizes of each byte_array element
Returns:
0 on success, otherwise a negative error value
Return values:
BUNDLE_ERROR_NONESuccessful
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_NOT_AVAILABLEKey not available
See also:
bundle_add_byte_array()
bundle_set_byte_array_element()
int bundle_get_count ( bundle b)

Gets the number of bundle items.

Since :
2.3
Parameters:
[in]bThe 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]bThe bundle object
[in]keyThe key
[out]strThe returned value
Returns:
The operation result
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_NOT_AVAILABLEKey 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]bThe bundle object
[in]keyThe key
[out]lenThe array length
Returns:
The pointer to the array of strings, NULL - Key not found
Exceptions:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_NOT_AVAILABLEKey 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]bA bundle
[in]keyA key in the bundle
Returns:
The type of a key in b
Exceptions:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_NOT_AVAILABLEKey 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]kvA bundle_keyval_t object
[out]array_valThe array pointer of values
[out]array_lenThe length of array_val
[out]array_element_sizeThe array of size of each array element
Returns:
The operation result
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid 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]kvA bundle_keyval_t object
[out]valThe value
[out]sizeThe size of val
Returns:
The operation result
Return values:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
kv must be a valid bundle_keyval_t object.
Postcondition:
val and size are set.
See also:
bundle_foreach()

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]kvA bundle_keyval_t object
Returns:
The type of kv, -1 - Failure
Exceptions:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
kv must be a valid bundle_keyval_t object.
See also:
bundle_foreach()

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]kvA bundle_keyval_t object
Returns:
The operation result 1 - kv is an array 0 - kv is not an array
Exceptions:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid 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]bThe bundle object
[in]keyThe key
[in]idxThe index of the array element to be changed
[in]bytesThe byte sequence
[in]sizeThe byte sequence size in bytes
Returns:
0 on success, otherwise a negative error value
Return values:
BUNDLE_ERROR_NONESuccessful
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
BUNDLE_ERROR_KEY_NOT_AVAILABLEKey not available
BUNDLE_ERROR_OUT_OF_MEMORYOut of memory
BUNDLE_ERROR_ARRAY_INDEX_OUT_OF_BOUNDSThe index is out of bounds of the array
See also:
bundle_add_byte_array()
bundle_get_byte_array()