Merge branch 'refs/heads/t/build'
[osl.git] / 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://people.tuebingen.mpg.de/maan/paraslash/">paraslash</a>, a network audio
151 streaming system, and <a href="http://people.tuebingen.mpg.de/maan/adu/">adu
152 </a>, the advanced disk usage tool.
153
154 */