Tizen Native API
Functions | Typedefs
Bundle
Application Framework

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 a value with a given key.
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 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 *byte, const size_t size)
 Adds a byte 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 **byte, size_t *size)
 Gets the byte value 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.1
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.1
See also:
bundle_foreach()
typedef struct keyval_t bundle_keyval_t

The key-value pair handle.

Since :
2.3.1
See also:
bundle_iterator_t
typedef unsigned char bundle_raw

The encoded data type.

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

Enumeration Type Documentation

enum bundle_error_e

Enumeration for error code of Bundle.

Since :
2.3.1
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

enum bundle_type

Enumeration for bundle types.

Since :
2.3.1
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.1
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 *  byte,
const size_t  size 
)

Adds a byte type key-value pair into a bundle.

Since :
2.3.1
Parameters:
[in]bThe bundle object
[in]keyThe key
[in]byteThe string type value
[in]sizeThe size of byte
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 new bundle object
 bundle_add_byte(b, "foo", "bar\0", 4); // add a key-val pair

 int number = 12345;
 bundle_add_byte(b, "number", &number, sizeof(int));

 bundle_free(b);
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.1
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 new bundle object
 bundle_add_str(b, "foo", "bar"); // add a key-val 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.1
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" };    // A string array of length 3
 bundle *b = bundle_create();
 bundle_add_str_array(b, "foo", sa, 3); // add a key-val pair
 bundle_free(b);
bundle* bundle_create ( void  )

Creates a bundle object.

Since :
2.3.1
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
Return values:
@cNULL - Failure
Exceptions:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_OUT_OF_MEMORYOut of memory
See also:
bundle_free()
 #include <bundle.h>
 bundle *b = bundle_create(); // Create new bundle object
 bundle_free(b); // free bundle
bundle* bundle_decode ( const bundle_raw *  r,
const int  len 
)

Deserializes bundle_raw and gets the bundle object.

Since :
2.3.1
Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
Parameters:
[in]rThe bundle_raw data to be converted to bundle object
[in]lenThe size of r
Returns:
The bundle object
Return values:
@cNULL - Failure
Exceptions:
BUNDLE_ERROR_NONESuccess
BUNDLE_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
b must be a valid bundle object. 
 #include <bundle.h>
 bundle *b = bundle_create(); // Create new bundle object
 bundle_add_str(b, "foo_key", "bar_val"); // add a key-val 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.1
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 new bundle object
 bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 bundle_del(b, "foo_key"); // del "foo_key" from b

 bundle_free(b);
int bundle_encode ( bundle *  b,
bundle_raw **  r,
int *  len 
)

Encodes a bundle to the bundle_raw format (uses base64 format).

Since :
2.3.1
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 new bundle object
 bundle_add_str(b, "foo_key", "bar_val"); // add a key-val 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.1
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 new bundle object
     bundle_add_str(b, "k1", "v1"); // add a key-val pair
     bundle_add_byte(b, "k2", "v2", 3); // add a key-val pair
     char *s_arr[] = {"abc", "bcd", "cde"};
     bundle_add_str_array(b, "k3", s_arr, 3); // add a key-val pair
     bundle_foreach(b, sample_cb, NULL);    // iterate sample_cb() for each key/val
     return 0;
 }
int bundle_free ( bundle *  b)

Frees the given bundle object with key-value pairs in it.

Since :
2.3.1
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 new bundle object
 bundle_free(b); // free bundle
int bundle_get_byte ( bundle *  b,
const char *  key,
void **  byte,
size_t *  size 
)

Gets the byte value with the given key.

Since :
2.3.1
Remarks:
You must not free byte!
Parameters:
[in]bThe bundle object
[in]keyThe key
[out]byteThe returned value
[out]sizeThe size of the byte
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 new bundle object
 bundle_add_byte(b, "foo", "bar\0", 4); // add string to bundle
 int number = 12345;
 bundle_add_byte(b, "number", (const void**)&number, sizeof(int)); // add integer to 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 becomes a dangling pointer.
int bundle_get_count ( bundle *  b)

Gets the number of bundle items.

Since :
2.3.1
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 new bundle object
 bundle_add_str(b, "key1", "val1"); //add a key-val pair
 int count = bundle_get_count(b);   // count=1
 bundle_add_str(b, "key2", "val2"); // add another key-val 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.1
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 new bundle object
 bundle_add_str(b, "foo_key", "bar_val"); // add a key-val 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.1
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
Return values:
@cNULL - 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" };    // A string array of length 3
 bundle_add_str_array(b, "foo", sa, 3); // add a key-val 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 a value with a given key.

Since :
2.3.1
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_t 
 











      

        

          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.1 


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_item_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.1 


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











      

        

          int bundle_keyval_get_type 
          (
          bundle_keyval_t * 
          kv)
          
        

      







Gets the type of a key-value pair. 


Since :
2.3.1 


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 


Return values:

  

    
@c-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() 











      

        

          int bundle_keyval_type_is_array 
          (
          bundle_keyval_t * 
          kv)
          
        

      







Determines whether the type of a key-value pair is array. 


Since :
2.3.1 


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 


Return values:

  

    
@c1 - kv is an array 

    
@c0 - 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()