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
  33 <p> 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. </p><br/>
  34
  35 <p> ADT(Abstract data type) An Abstract Data type is defined as a mathematical model of the data objects that make up a data type as well
  36 as the functions that operate on these objects.</p>
  37
  38 <h1 class="pg">Features</h1>
  39 <ul>
  40         <li> Bundle provides string based Dictionary ADT to
  41                 map/store key-value pairs. Eg. Clock </li>
  42         <li> Bundle  provides Application Data Exchange (ADE):
  43                 <ul>
  44                         <li> Transfer application argument between caller and callee by creating a bundle and storing key-value pairs in it. </li>
  45                         <li> This bundle object can be passed between applications by encoding and decoding the bundle objects. </li>
  46                 </ul> </li>
  47
  48 </ul>
  49
  50 <h1 class="pg">Properties</h1>
  51 <ul>
  52         <li>Only string type is allowed for key and value.</li>
  53         <li>Each key and value is duplicated into the bundle object.</li>
  54         <li>Unlimited number of key/value pairs. (Memory limit is still to be considered)</li>
  55         <li>No key overlap : You cannot assign new values with existing key.</li>
  56 </ul>
  57
  58 <h1 class="pg">Bundle Logical View diagram</h1>
  59 \image html SLP_bundle_PG_images_logical_view.png "Picture 1. Logical view"
  60
  61
  62 <h1 class="pg">Functional architecture diagram</h1>
  63 \image html SLP_bundle_PG_image01.png "Picture 2. Functional architecture"
  64
  65 <p> Bundle requests are received by the Bundle interface. It passes the requests to bundle manager. Bundle Manager checks the type of the request and handles it accordingly. If string key-value needs to be handled in the request it interacts with String manager to provide the required functionality. If the request is based on array of string key-value pair then, Bundle manager interacts with Array manager to provide the required functionality.</p>
  66
  67 <h1 class="pg"> Bundle encode decode life cycle </h1>
  68 \image html SLP_bundle_PG_images_encode_decode.png "Picture 2. Encode decode life cycle"
  69
  70 <h1 class="pg"> Bundle export import life cycle </h1>
  71 \image html SLP_bundle_PG_images_export_import.png "Picture 2. Export import life cycle"
  72
  73 <h1 class="pg">API list and description</h1>
  74 <ul>
  75         <li>bundle_create() : Create a bundle object.</li>
  76         <li>bundle_free() : Free a bundle object.</li>
  77         <li>bundle_add() : Add a key/value pair into the bundle object.</li>
  78         <li>bundle_del() : Delete a key/value pair by given key from the bundle object.</li>
  79         <li>bundle_get_val() : Get a value by key.</li>
  80         <li>bundle_get_count() : Get number of key/value pairs in the bundle object.</li>
  81         <li>bundle_dup() : Duplicate give bundle object</li>
  82         <li>bundle_iterate() : Run iterator function for each key/value pair in the bundle object.</li>
  83         <li>bundle_encode() : Encode bundle object into a byte code.</li>
  84         <li>bundle_decode() : Decode byt code into a bundle object.</li>
  85         <li></li>
  86 </ul>
  87
  88 <h1 class="pg">Programming Guide</h1>
  89 <p> bundle library is very easy to use, and the sample code below would enough to understand how to use bundle. </p><br>
  90 <p>Detailed API instructions are in API reference in doxygen document.</p>
  91 <h2 class="pg">Note</h2>
  92 <ul>
  93         <li>Only string type(char *) keys/values are allowed.</li>
  94         <li>A bundle object must be freed certainly by bundle_free(). </li>
  95         <li>Values retrived by bundle_get_val() cannot be modified.<br> If you want to modify value string, duplicate it.</li>
  96 </ul>
  97 <h2 class="pg"> Header file </h2>
  98 <p> header file name: <strong> bundle.h </strong></p>
  99 <h2 class="pg">Code</h2>
 100 @code
 101 #include <stdio.h>
 102 #include <bundle.h>
 103
 104 // This is a sample iterator callback function
 105 void print_bundle_item(const char *key, const char *val, void *data);
 106
 107 // Sample code
 108 int
 109 main(int argc, char **argv)
 110 {
 111         char *str;
 112         int count;
 113
 114         bundle *b, *b_dup;
 115
 116         // Create a new bundle object
 117         b = bundle_new();
 118
 119         // Add a string with key "a"
 120         bundle_add(b, "a", "123abc");
 121
 122         // Add another string with key "b"
 123         bundle_add("b", "456def");
 124
 125         // str = "123abc"
 126         // You cannot modify string!
 127         str = bundle_get_val(b, "a");
 128
 129         // Run iterator function with each items
 130         bundle_iterate(b, print_bundle_item, NULL);
 131
 132         // count = 2
 133         count = bundle_get_count(b);
 134
 135         // Delete an item with key "a"
 136         bundle_del(b, "a");
 137
 138         // count = 1
 139         count = bundle_get_count(b);
 140
 141         // If "a" key is requested, NULL is returned
 142         // str = NULL, errno = ENOKEY
 143         str = bundle_get_val(b, "a");
 144
 145         // Duplicate bundle object
 146         b_dup = bundle_dup(b);
 147
 148         // Free bundle objects
 149         bundle_free(b);
 150         bundle_free(b_dup);
 151
 152         return 0;
 153 }
 154
 155 void
 156 print_bundle_item(const char *key, const char *val, void *data)
 157 {
 158         printf("%s -> %s\n", key, val);
 159 }
 160 @endcode
 161
 162  * @}
 163  */