--- /dev/null
+/** \mainpage OSL Quick start
+
+This document describes the steps which have to be performed in order
+to create and use an osl table. The code sniplets in this section
+are taken from the file \ref osltar.c in the source distribution.
+
+The complete API reference is contained in the file \ref osl.h.
+
+- Define an enum that assigns descriptive names to the columns
+of your table. Example:
+
+\verbatim
+
+enum osltar_columns {
+ OTC_NAME,
+ OTC_DATA,
+ NUM_OT_COLUMNS
+};
+
+\endverbatim
+
+The last element is is useful because the number of columns
+of your table must be specified later, see below.
+
+- Define an array of struct osl_column_description, one
+array member per column:
+
+\verbatim
+
+struct osl_column_description tar_table_cols[] = {
+ [OTC_NAME] = {
+ .storage_type = OSL_MAPPED_STORAGE,
+ .storage_flags = OSL_RBTREE | OSL_UNIQUE,
+ .name = "filename",
+ .compare_function = string_compare,
+ },
+ [OTC_DATA] = {
+ .storage_type = OSL_MAPPED_STORAGE,
+ .name = "data",
+ },
+};
+
+\endverbatim
+
+Three different storage types are available which may be
+selected on a per-column basis: \ref OSL_DISK_STORAGE, \ref
+OSL_MAPPED_STORAGE, and \ref OSL_NO_STORAGE.
+
+For columns of type OSL_MAPPED_STORAGE and OSL_NO_STORAGE an optional
+rbtree is maintained by the osl library which allows to quickly lookup
+rows by cell content. Whether or not an rbtree should be used must be
+specified in the storage_flags field which should contain the bitwise
+or of suitable \ref osl_storage_flags.
+
+If a column has an associated rbtree, i.e. if the OSL_RBTREE flag
+is set in the storage flags for the column, the compare_function
+field must be initialized to point to a function of type \ref
+osl_compare_func. In this example, \ref string_compare() is used,
+which is just a wrapper for strcmp() that interprets osl objects as
+C-strings and calls strcmp() on the object data.
+
+- Define a struct \ref osl_table_description and initialize
+it with the number of columns of your table and the column
+descriptions:
+
+\verbatim
+
+struct osl_table_description tar_table_desc = {
+ .name = "tar_table",
+ .num_columns = NUM_OT_COLUMNS,
+ .column_descriptions = tar_table_cols,
+ .dir = "/tmp/osltest"
+};
+
+\endverbatim
+
+- Create the table by calling \ref osl_create_table():
+
+\verbatim
+
+ret = osl_create_table(&tar_table_desc);
+
+\endverbatim
+
+- Open the newly created table by calling osl_open_table:
+
+\verbatim
+
+struct osl_table *table;
+ret = osl_open_table(&tar_table_desc, &table);
+
+\endverbatim
+
+- To add a new row to the table, you must define an array of struct
+osl_object of length NUM_OT_COLUMNS which holds the contents of the
+new row. Note that an osl object is just a blob: It consists of a
+data pointer and a size value. Once the array has been initialized,
+pass it to \ref osl_add_row() together with the table handle obtained
+from osl_open_table():
+
+\verbatim
+
+struct osl_object objs[NUM_OT_COLUMNS];
+/* ...init the array... */
+ret = osl_add_row(table, objs);
+
+\endverbatim
+
+- Close the table with \ref osl_close_table().
+
+\verbatim
+
+osl_close_table(table, OSL_MARK_CLEAN);
+
+\endverbatim
+
+The storage type of both columns of the table in this example
+is OSL_MAPPED_STORAGE, so you can later open the table again
+and retrieve its contents:
+
+\verbatim
+
+ret = osl_get_row(table, OTC_NAME, &obj, &row);
+if (ret < 0) {
+ fprintf(stderr, "osl_get_row(%s): %s\n", name,
+ osl_strerror(-ret));
+ return ret;
+}
+ret = osl_get_object(table, row, OTC_DATA, &obj);
+
+\endverbatim
+
+The call to \ref osl_get_row() uses the rbtree of the OTC_NAME
+column to find the row whose object in the OTC_NAME column
+matches the given object obj. If a row was found, it is
+passed to \ref osl_get_object() which returns the object of
+the OTC_DATA column of this row.
+
+
+This concludes the quick start document. Of course, libosl contains
+many more public functions than those used above. For details on the
+C-API, look at the file \ref osl.h which contains the declarations of
+all public functions and the complete documentation of the public part
+of the library.
+
+The "examples" subdirectory of the source distribution
+contains the full code of the above example and another
+small program which illustrates the use of columns of
+type OSL_NO_STORAGE. Larger applications using libosl are <a
+href="http://paraslash.systemlinux.org">paraslash</a>, a network audio
+streaming system, and <a href="http://systemlinux.org/~maan/adu">adu
+</a>, the advanced disk usage tool.
+
+*/
projects / osl.git / blobdiff