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