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

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

enum bundle_error_e

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

enum bundle_type

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

enum bundle_type_property

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]	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

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]	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

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] 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 array 0 - 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

See also:: bundle_add_byte_array(); bundle_get_byte_array()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation