QUICK_START

   1 /** \mainpage OSL Quick start
   2
   3 This document describes the steps which have to be performed in order
   4 to create and use an osl table. The code sniplets in this section
   5 are taken from the file \ref osltar.c in the source distribution.
   6
   7 The complete API reference is contained in the file \ref osl.h.
   8
   9 - Define an enum that assigns descriptive names to the columns
  10 of your table. Example:
  11
  12 \verbatim
  13
  14 enum osltar_columns {
  15         OTC_NAME,
  16         OTC_DATA,
  17         NUM_OT_COLUMNS
  18 };
  19
  20 \endverbatim
  21
  22 The last element is is useful because the number of columns
  23 of your table must be specified later, see below.
  24
  25 - Define an array of struct osl_column_description, one
  26 array member per column:
  27
  28 \verbatim
  29
  30 struct osl_column_description tar_table_cols[] = {
  31         [OTC_NAME] = {
  32                 .storage_type = OSL_MAPPED_STORAGE,
  33                 .storage_flags = OSL_RBTREE | OSL_UNIQUE,
  34                 .name = "filename",
  35                 .compare_function = string_compare,
  36         },
  37         [OTC_DATA] = {
  38                 .storage_type = OSL_MAPPED_STORAGE,
  39                 .name = "data",
  40         },
  41 };
  42
  43 \endverbatim
  44
  45 Three different storage types are available which may be
  46 selected on a per-column basis: \ref OSL_DISK_STORAGE, \ref
  47 OSL_MAPPED_STORAGE, and \ref OSL_NO_STORAGE.
  48
  49 For columns of type OSL_MAPPED_STORAGE and OSL_NO_STORAGE an optional
  50 rbtree is maintained by the osl library which allows to quickly lookup
  51 rows by cell content. Whether or not an rbtree should be used must be
  52 specified in the storage_flags field which should contain the bitwise
  53 or of suitable \ref osl_storage_flags.
  54
  55 If a column has an associated rbtree, i.e. if the OSL_RBTREE flag
  56 is set in the storage flags for the column, the compare_function
  57 field must be initialized to point to a function of type \ref
  58 osl_compare_func. In this example, \ref string_compare() is used,
  59 which is just a wrapper for strcmp() that interprets osl objects as
  60 C-strings and calls strcmp() on the object data.
  61
  62 - Define a struct \ref osl_table_description and initialize
  63 it with the number of columns of your table and the column
  64 descriptions:
  65
  66 \verbatim
  67
  68 struct osl_table_description tar_table_desc = {
  69         .name = "tar_table",
  70         .num_columns = NUM_OT_COLUMNS,
  71         .column_descriptions = tar_table_cols,
  72         .dir = "/tmp/osltest"
  73 };
  74
  75 \endverbatim
  76
  77 - Create the table by calling \ref osl_create_table():
  78
  79 \verbatim
  80
  81 ret = osl_create_table(&tar_table_desc);
  82
  83 \endverbatim
  84
  85 - Open the newly created table by calling osl_open_table:
  86
  87 \verbatim
  88
  89 struct osl_table *table;
  90 ret = osl_open_table(&tar_table_desc, &table);
  91
  92 \endverbatim
  93
  94 - To add a new row to the table, you must define an array of struct
  95 osl_object of length NUM_OT_COLUMNS which holds the contents of the
  96 new row. Note that an osl object is just a blob: It consists of a
  97 data pointer and a size value. Once the array has been initialized,
  98 pass it to \ref osl_add_row() together with the table handle obtained
  99 from osl_open_table():
 100
 101 \verbatim
 102
 103 struct osl_object objs[NUM_OT_COLUMNS];
 104 /* ...init the array... */
 105 ret = osl_add_row(table, objs);
 106
 107 \endverbatim
 108
 109 - Close the table with \ref osl_close_table().
 110
 111 \verbatim
 112
 113 osl_close_table(table, OSL_MARK_CLEAN);
 114
 115 \endverbatim
 116
 117 The storage type of both columns of the table in this example
 118 is OSL_MAPPED_STORAGE, so you can later open the table again
 119 and retrieve its contents:
 120
 121 \verbatim
 122
 123 ret = osl_get_row(table, OTC_NAME, &obj, &row);
 124 if (ret < 0) {
 125         fprintf(stderr, "osl_get_row(%s): %s\n", name,
 126                 osl_strerror(-ret));
 127         return ret;
 128 }
 129 ret = osl_get_object(table, row, OTC_DATA, &obj);
 130
 131 \endverbatim
 132
 133 The call to \ref osl_get_row() uses the rbtree of the OTC_NAME
 134 column to find the row whose object in the OTC_NAME column
 135 matches the given object obj. If a row was found, it is
 136 passed to \ref osl_get_object() which returns the object of
 137 the OTC_DATA column of this row.
 138
 139
 140 This concludes the quick start document. Of course, libosl contains
 141 many more public functions than those used above. For details on the
 142 C-API, look at the file \ref osl.h which contains the declarations of
 143 all public functions and the complete documentation of the public part
 144 of the library.
 145
 146 The "examples" subdirectory of the source distribution
 147 contains the full code of the above example and another
 148 small program which illustrates the use of columns of
 149 type OSL_NO_STORAGE. Larger applications using libosl are <a
 150 href="http://paraslash.systemlinux.org">paraslash</a>, a network audio
 151 streaming system, and <a href="http://systemlinux.org/~maan/adu">adu
 152 </a>, the advanced disk usage tool.
 153
 154 */