include/SLP_bundle_PG.h

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