include/SLP_bundle_PG.h

   1 /*
   2  * bundle
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jayoun Lee <airjany@samsung.com>, Sewook Park <sewook7.park@samsung.com>,
   7  * Jaeho Lee <jaeho81.lee@samsung.com>
   8  *
   9  * Licensed under the Apache License, Version 2.0 (the "License");
  10  * you may not use this file except in compliance with the License.
  11  * You may obtain a copy of the License at
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  *
  21  */
  22
  23
  24 /**
  25  *
  26  * @ingroup SLP_PG
  27  * @defgroup bundle_PG Bundle
  28  * @brief A simple string-based dictionary ADT
  29  * @{
  30
  31 <h1 class="pg">Introduction</h1>
  32 bundle is a simple dictionary ADT to be used in UI-gadget, AUL, and other libraries in application framework. <br>
  33 bundle can store a number of string key-value pairs, get value by key, duplicate itself, and encode/decode to convert itself into binary data. <br>
  34
  35
  36 <h1 class="pg">Functional architecture diagram</h1>
  37 \image html SLP_bundle_PG_image01.png "Picture 1. Functional architecture"
  38
  39 A bundle object, created by bundle_create(), can add/delete key/value pairs, get a value with a key, and get number of key/value pairs in it. <br>
  40 A bundle object can be duplicated by bundle_dup(). <br>
  41 bundle_encode() can encode a bundle object into byte code(bundle_raw == unsigned char *). This byte code can be decoded into a new bundle object, by bundle_decode(). <br>
  42 All bundle objects must be freed by bundle_free(). <br>
  43
  44 <h1 class="pg">Features</h1>
  45 <ul>
  46         <li>Only string type is allowed for key and value.</li>
  47         <li>Each key and value is duplicated into the bundle object.</li>
  48         <li>Unlimited number of key/value pairs. (Memory limit is still to be considered)</li>
  49         <li>No key overlap : You cannot assign new values with existing key.</li>
  50 </ul>
  51
  52 <h1 class="pg">API list and description</h1>
  53 <ul>
  54         <li>bundle_create() : Create a bundle object.</li>
  55         <li>bundle_free() : Free a bundle object.</li>
  56         <li>bundle_add() : Add a key/value pair into the bundle object.</li>
  57         <li>bundle_del() : Delete a key/value pair by given key from the bundle object.</li>
  58         <li>bundle_get_val() : Get a value by key.</li>
  59         <li>bundle_get_count() : Get number of key/value pairs in the bundle object.</li>
  60         <li>bundle_dup() : Duplicate give bundle object</li>
  61         <li>bundle_iterate() : Run iterator function for each key/value pair in the bundle object.</li>
  62         <li>bundle_encode() : Encode bundle object into a byte code.</li>
  63         <li>bundle_decode() : Decode byt code into a bundle object.</li>
  64         <li></li>
  65 </ul>
  66
  67 <h1 class="pg">Sample code</h1>
  68 bundle library is very easy to use, and the sample code below would enough to understand how to use bundle. <br>
  69 Detailed API instructions are in API reference in doxygen document.
  70 <h2 class="pg">Note</h2>
  71 <ul>
  72         <li>Only string type(char *) keys/values are allowed.</li>
  73         <li>A bundle object must be freed certainly by bundle_free(). </li>
  74         <li>Values retrived by bundle_get_val() cannot be modified.<br> If you want to modify value string, duplicate it.</li>
  75 </ul>
  76 <h2 class="pg">Code</h2>
  77 @code
  78 #include <stdio.h>
  79 #include <bundle.h>
  80
  81 // This is a sample iterator callback function
  82 void print_bundle_item(const char *key, const char *val, void *data);
  83
  84 // Sample code
  85 int
  86 main(int argc, char **argv)
  87 {
  88         char *str;
  89         int count;
  90
  91         bundle *b, *b_dup;
  92
  93         // Create a new bundle object
  94         b = bundle_new();
  95
  96         // Add a string with key "a"
  97         bundle_add(b, "a", "123abc");
  98
  99         // Add another string with key "b"
 100         bundle_add("b", "456def");
 101
 102         // str = "123abc"
 103         // You cannot modify string!
 104         str = bundle_get_val(b, "a");
 105
 106         // Run iterator function with each items
 107         bundle_iterate(b, print_bundle_item, NULL);
 108
 109         // count = 2
 110         count = bundle_get_count(b);
 111
 112         // Delete an item with key "a"
 113         bundle_del(b, "a");
 114
 115         // count = 1
 116         count = bundle_get_count(b);
 117
 118         // If "a" key is requested, NULL is returned
 119         // str = NULL, errno = ENOKEY
 120         str = bundle_get_val(b, "a");
 121
 122         // Duplicate bundle object
 123         b_dup = bundle_dup(b);
 124
 125         // Free bundle objects
 126         bundle_free(b);
 127         bundle_free(b_dup);
 128
 129         return 0;
 130 }
 131
 132 void
 133 print_bundle_item(const char *key, const char *val, void *data)
 134 {
 135         printf("%s -> %s\n", key, val);
 136 }
 137 @endcode
 138
 139  * @}
 140  */