Added first attempt to CDS library documentation with very short

description in README.

lib/README

@@ -51,3 +51,14 @@ you should set LD_LIBRARY_PATH=/usr/local/lib/ser. In the case of
 nonstandard installation, you can use something like 
 LD_LIBRARY_PATH=/my/ser/directory/lib/ser.
 
+Documentation
+-------------
+Documentation for all libraries is (or will be) in 
+docbook-XML format and it is stored in doc directory (for example cds/doc 
+contains documentation for Common Data Structures library).
+
+Documentation can be translated into HTML using a XSLT processor
+which is able to work with "include" directives.
+For example
+   xmlto html cds/doc/cds.xml
+will create HTML documentation for CDS library in current directory.

lib/cds/doc/cds.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
+'file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd'>
+
+<!--<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
+'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'>-->
+
+<book lang="en">
+<bookinfo>
+	<title>Common Data Structures</title>
+	<author><firstname>Václav</firstname><surname>Kubart</surname></author>
+	<abstract><para>Description of CDS (Common Data Structures) library.
+	</para></abstract>
+</bookinfo>
+
+<preface><title>Preface</title>
+<para>This library contains many useful functions and data structures. It is
+possible to use it with Sip Express Router (SER) or without it. In the first case it
+is able to use some internal SER's data types like strings.
+</para>
+
+<section><title>Conventions</title>
+<para>There is list of conventions used in this library:
+<itemizedlist>
+	<listitem><para>data types (structures, enums, ...) have their names with suffix 
+	<quote>_t</quote> (<structname>dstring_t</structname>, 
+	<structname>str_t</structname>, ...)</para></listitem>
+	<listitem><para>many functions have prefix according to data structure on
+	which are operating (like <function>dstr_append</function> which operates on
+	<structname>dstring_t</structname> data structure)</para></listitem>
+	<listitem><para>most functions return 0 as successful result and nonzero
+	value as error</para></listitem>
+</itemizedlist>
+</para>
+</section>
+
+</preface>
+
+<!--<part><title>Functions and data types</title>-->
+<include xmlns="http://www.w3.org/2001/XInclude" href="sstr.xml"/>
+<include xmlns="http://www.w3.org/2001/XInclude" href="dstring.xml"/>
+<include xmlns="http://www.w3.org/2001/XInclude" href="serialization.xml"/>
+<!--</part>-->
+</book>

lib/cds/doc/dstr_append.xml

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="dstr_append">
+
+<refmeta><refentrytitle>dstr_append</refentrytitle>
+<manvolnum>3</manvolnum></refmeta>
+
+<refnamediv>
+<refname>dstr_append</refname>
+<refname id="dstr_append_str">dstr_append_str</refname>
+<refname id="dstr_append_zt">dstr_append_zt</refname>
+<refpurpose>append string to <structname>dstring_t</structname>
+structure</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv><funcsynopsis>
+
+<funcsynopsisinfo>
+#include &lt;cds/dstring.h&gt;
+</funcsynopsisinfo>
+
+<funcprototype>
+  <funcdef>int <function>dstr_append</function></funcdef>
+  <paramdef>dstring_t *<parameter>dstr</parameter></paramdef>
+  <paramdef>const char *<parameter>s</parameter></paramdef>
+  <paramdef>int <parameter>len</parameter></paramdef>
+</funcprototype>
+
+<funcprototype>
+  <funcdef>int <function>dstr_append_str</function></funcdef>
+  <paramdef>dstring_t *<parameter>dstr</parameter></paramdef>
+  <paramdef>const str_t *<parameter>s</parameter></paramdef>
+</funcprototype>
+
+<funcprototype>
+  <funcdef>int <function>dstr_append_zt</function></funcdef>
+  <paramdef>dstring_t *<parameter>dstr</parameter></paramdef>
+  <paramdef>const char *<parameter>s</parameter></paramdef>
+</funcprototype>
+
+</funcsynopsis></refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para>All these functions are used for appending strings to dynamic string. They
+differ only in the string and its length specification.
+<variablelist>
+<varlistentry>
+	<term><function>dstr_append</function></term>
+	<listitem><para>appends data from buffer <parameter>s</parameter> of
+	length <parameter>len</parameter></para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><function>dstr_append_str</function></term>
+	<listitem><para>appends content of string <parameter>s</parameter>
+	(see <xref linkend="str_t"/>)</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><function>dstr_append_zt</function></term>
+	<listitem><para>appends content of zero terminated string <parameter>s</parameter></para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+</refsect1>
+
+<refsect1><title>Return value</title>
+<para>All these functions return 0 if successful, nonzero otherwise.</para>
+</refsect1>
+
+<refsect1><title>See Also</title>
+<para><xref linkend="dstring_t"/></para>
+</refsect1>
+
+</refentry> 
+

lib/cds/doc/dstr_get_data.xml

@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="dstr_get_data">
+
+<refmeta><refentrytitle>dstr_get_data</refentrytitle>
+<manvolnum>3</manvolnum></refmeta>
+
+<refnamediv>
+<refname>dstr_get_data</refname>
+<refname id="dstr_get_data_length">dstr_get_data_length</refname>
+<refname id="dstr_get_data_str">dstr_get_data_str</refname>
+<refpurpose>exporting data from <structname>dstring_t</structname>
+structure</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv><funcsynopsis>
+
+<funcsynopsisinfo>
+#include &lt;cds/dstring.h&gt;
+</funcsynopsisinfo>
+
+<funcprototype>
+  <funcdef>int <function>dstr_get_data_length</function></funcdef>
+  <paramdef>dstring_t *<parameter>dstr</parameter></paramdef>
+</funcprototype>
+
+<funcprototype>
+  <funcdef>int <function>dstr_get_data</function></funcdef>
+  <paramdef>dstring_t *<parameter>dstr</parameter></paramdef>
+  <paramdef>char *<parameter>dst</parameter></paramdef>
+</funcprototype>
+
+<funcprototype>
+  <funcdef>int <function>dstr_get_data_str</function></funcdef>
+  <paramdef>dstring_t *<parameter>dstr</parameter></paramdef>
+  <paramdef>str_t *<parameter>dst</parameter></paramdef>
+</funcprototype>
+
+</funcsynopsis></refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><function>dstr_get_data_length</function> function is used to determine
+the size of data present in dynamic string. It returns negative value on error.</para>
+
+<para><function>dstr_get_data</function> copies data from internal buffers into
+given character array allocated by caller. The data size can be 
+determined by <function>dstr_get_data_length</function> call.
+</para>
+
+<para><function>dstr_get_data_str</function> copies data from internal buffers into
+internally allocated string. This string is returned in the <varname>dst</varname>
+parameter.
+</para>
+
+</refsect1>
+
+<refsect1><title>Return value</title>
+<para>Functions <function>dstr_get_data</function> and
+<function>dstr_get_data_str</function> return 0 if successful, nonzero otherwise.
+</para>
+<para>Function <function>dstr_get_data_length</function> returns negative value
+on error, zero if there is no data in dynamic string and positive if there was
+no error and data present.
+</para>
+</refsect1>
+
+<refsect1><title>See Also</title>
+<para><xref linkend="dstring_t"/></para>
+</refsect1>
+
+</refentry> 

lib/cds/doc/dstr_init.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="dstr_init">
+
+<refmeta><refentrytitle>dstr_init</refentrytitle>
+<manvolnum>3</manvolnum></refmeta>
+
+<refnamediv>
+<refname>dstr_init</refname>
+<refname>dstr_destroy</refname>
+<refpurpose>initialization and destruction of <structname>dstring_t</structname>
+structure</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv><funcsynopsis>
+
+<funcsynopsisinfo>
+#include &lt;cds/dstring.h&gt;
+</funcsynopsisinfo>
+
+<funcprototype>
+  <funcdef>int <function>dstr_init</function></funcdef>
+  <paramdef>dstring_t *<parameter>dstr</parameter></paramdef>
+  <paramdef>int <parameter>buff_size</parameter></paramdef>
+</funcprototype>
+
+<funcprototype>
+  <funcdef>int <function>dstr_destroy</function></funcdef>
+  <paramdef>dstring_t *<parameter>dstr</parameter></paramdef>
+</funcprototype>
+
+</funcsynopsis></refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><function>dstr_init</function> function initializes
+<structname>dstring_t</structname> structure. The
+value of <varname>buff_size</varname> is the size of newly allocated data
+buffers. These buffers are internal and are allocated if needed by any of
+dstring functions.</para>
+
+<para><function>dstr_destroy</function> function destroys all allocated data
+buffers. After calling <function>dstr_destroy</function> can't be called any of
+dstring manipulation functions except <function>dstr_init</function>.
+</para>
+</refsect1>
+
+<refsect1><title>Return value</title>
+<para>Both functions return 0 if successful, nonzero otherwise.
+</para>
+</refsect1>
+
+</refentry> 

lib/cds/doc/dstring.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<reference><title>Dynamic string</title>
+
+<partintro>
+<para>Dynamic string is data structure used for simple string operations
+hiding internal operations like memory allocations from the user.</para>
+
+<para>Functions and data structures for dynamic string are declared in 
+<filename class='headerfile'>dstring.h</filename>.</para>
+</partintro>
+
+<include xmlns="http://www.w3.org/2001/XInclude" href="dstring_t.xml"/>
+<include xmlns="http://www.w3.org/2001/XInclude" href="dstr_init.xml"/>
+<include xmlns="http://www.w3.org/2001/XInclude" href="dstr_append.xml"/>
+<include xmlns="http://www.w3.org/2001/XInclude" href="dstr_get_data.xml"/>
+
+</reference>

lib/cds/doc/dstring_t.xml

@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="dstring_t">
+
+<refmeta><refentrytitle>dstring_t</refentrytitle>
+<manvolnum>3</manvolnum></refmeta>
+
+<refnamediv><refname>dstring_t</refname>
+<refpurpose>data structure for dynamic string representation</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv><synopsis>
+#include &lt;cds/dstring.h&gt;
+
+typedef struct _dstring_t {
+	dlink_t buffers;
+	int len;
+	int buff_size;
+} dstring_t;
+</synopsis></refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para>This structure represents dynamic string. It allows concatenation of
+multiple strings without worry about memory allocations.</para>
+
+<para>Internaly it uses list of data buffers which are allocated 
+if needed. The content of dynamic string may be copied out from internal buffers
+using simple function call (see <xref linkend="dstr_get_data"/>).
+</para>
+
+<para>This structure is used as base for simple object serialization (see <xref
+linkend="serialization"/>).
+</para>
+
+<refsect2><title>Members</title>
+<para><variablelist>
+<varlistentry>
+	<term><varname>buffers</varname></term>
+	<listitem><para>linked list of allocated data buffers</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><varname>len</varname></term>
+	<listitem><para>whole string length</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><varname>buff_size</varname></term>
+	<listitem><para>size of newly allocated buffers</para></listitem>
+</varlistentry>
+</variablelist></para>
+<para>Warning - structure internals may change! For manipulation use
+manipulation functions.</para>
+</refsect2>
+
+</refsect1>
+
+<refsect1><title>Example</title>
+<programlisting>
+#include &lt;cds/dstring.h&gt;
+#include &lt;cds/sstr.h&gt;
+
+int main(int argc, char **argv)
+{
+	dstring_t str;
+	str_t s;
+
+	dstr_init(&amp;str, 256);
+	dstr_append_zt(&amp;str,"This is a ");
+	dstr_append_zt(&amp;str,"very long ");
+	dstr_append_zt(&amp;str,"string.");
+	if (dstr_get_str(&amp;str, &amp;s) == 0) {
+		printf("result: %.*s\n", FMT_STR(s));	
+		str_free_content(&amp;s);
+	}
+	dstr_destroy(&amp;str);
+
+	return 0;
+}	
+</programlisting>
+<para>This will result in</para>
+<para><computeroutput>result: This is a very long
+string.</computeroutput>
+</para>
+</refsect1>
+
+<refsect1><title>Todo</title>
+<para>Create a function like sprintf.
+</para>
+</refsect1>
+
+<refsect1><title>See Also</title>
+<para>
+<xref linkend="dstr_init"/>,
+<xref linkend="dstr_get_data"/>,
+<xref linkend="dstr_append"/>,
+<xref linkend="str_t"/>
+</para>
+</refsect1>
+
+</refentry> 

lib/cds/doc/serialization.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<reference id="serialization">
+<title>Serialization</title>
+
+<partintro>
+<para>Serialization is a simple way to store and load data structures. It is
+used for example for storing SIP dialogs into database in SER's PA module.</para>
+<para>There is a set of functions for serializing basic data elements (strings,
+numbers, ...). These functions can be used as base for complex structures
+serialization (see <xref linkend="sstream_t.example"/>).</para>
+</partintro>
+
+<include xmlns="http://www.w3.org/2001/XInclude" href="sstream_t.xml"/>
+
+</reference>

lib/cds/doc/sstr.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<reference id="sstr">
+<title>String</title>
+
+<partintro>
+<para>String is basic data structure. Standard zero terminated C strings have
+some bad properties which may slow down processing or disallow use of binary
+values. This structure is an attempt to do it better :-).</para>
+<para>This structure was taken from SIP Express
+Router due to it's usability and need of testing some parts of SER's code
+outside of <quote>SER's environment</quote>. Many of string functions were
+inspired by or directly taken from SER's code. Another reason for this structure 
+was to put string operations to one place and not leave them independently and
+often duplictly in SER's modules.</para>
+</partintro>
+
+<include xmlns="http://www.w3.org/2001/XInclude" href="str_t.xml"/>
+
+</reference>

lib/cds/doc/sstream_t.xml

@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="sstream_t">
+
+<refmeta><refentrytitle>sstream_t</refentrytitle>
+<manvolnum>3</manvolnum></refmeta>
+
+<refnamediv><refname>sstream_t</refname>
+<refpurpose>input/output serialization stream</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv><synopsis>
+#include &lt;cds/serialize.h&gt;
+
+typedef struct {
+	dstring_t out;
+	str_t in;
+	int in_pos;
+	enum { sstream_in, sstream_out } type;
+} sstream_t;
+</synopsis></refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para>This structure represents input and output serialization stream.</para> 
+<refsect2><title>Members</title>
+<para><variablelist>
+<varlistentry>
+	<term><varname>out</varname></term>
+	<listitem><para>Dynamic string holding output data in the case of output
+	stream.</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><varname>in</varname></term>
+	<listitem><para>String holding input data in the case of input 
+	stream.</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><varname>in_pos</varname></term>
+	<listitem><para>Actual position in input data (points to first unread char) 
+	in the case of input stream.</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><varname>type</varname></term>
+	<listitem><para>Member holding stream type - input or output.</para></listitem>
+</varlistentry>
+</variablelist></para>
+<para>Warning - internals of this data structure may change! Use it only through
+manipulation functions.
+</para>
+</refsect2>
+</refsect1>
+
+<refsect1 id="sstream_t.example"><title>Example</title>
+<programlisting>
+#include &lt;cds/sstr.h&gt;
+#include &lt;cds/serialize.h&gt;
+
+typedef struct {
+	str_t name;
+	int number;
+	char c;
+} test_t;
+
+int serialize_test_struct(sstream_t *store, test_t *t)
+{
+	if (serialize_str(store, &amp;t->name) != 0) return -1;
+	if (serialize_int(store, &amp;t->number) != 0) return -1;
+	if (serialize_char(store, &amp;t->c) != 0) return -1;
+	return 0;
+}
+
+int main(int argc, char **argv)
+{
+	sstream_t store;
+	str_t data;
+	test_t a = { name: {"test A", 6}, number: 13, c: 'x' };
+	test_t b;
+
+	str_clear(&amp;data);
+
+	/* storing structure to the string */
+	
+	init_output_sstream(&amp;store, 256);
+	if (serialize_test_struct(&amp;store, &amp;a) == 0) {
+		if (get_serialized_sstream(&amp;store, &amp;data) != 0)
+			printf("can't get data\n");
+	}
+	else printf("can't serialize\n");
+	destroy_sstream(&amp;store);
+
+	/* loading structure from the string */
+	
+	init_input_sstream(&amp;store, data.s, data.len);
+	if (serialize_test_struct(&amp;store, &amp;b) == 0) {
+		printf("test_t = { %.*s, %d, %c }\n", 
+			FMT_STR(b.name), b.number, b.c);
+		
+		/* cleanup */
+		str_free_content(&amp;b.name);
+	}
+	else printf("can't deserialize\n");
+	destroy_sstream(&amp;store);
+
+	/* cleanup */
+	str_free_content(&amp;data);
+
+	return 0;
+}
+
+</programlisting>
+</refsect1>
+
+</refentry> 
+
+

lib/cds/doc/str_t.xml

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="str_t">
+
+<refmeta><refentrytitle>str_t</refentrytitle>
+<manvolnum>3</manvolnum></refmeta>
+
+<refnamediv><refname>str_t</refname>
+<refpurpose>data structure for string representation</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv><synopsis>
+#include &lt;cds/sstr.h&gt;
+
+outside of SIP Express Router:
+
+typedef struct {
+	char *s;
+	int len;
+} str_t;
+
+inside of SIP Express Router:
+
+typedef str str_t;
+
+</synopsis></refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para>This structure represents string. If compiled with SER it is defined using 
+SER string defined elsewhere: <programlisting>typedef str str_t;</programlisting>
+</para>
+<para>Otherwise it is defined as structure containing pointer to data buffer and
+length of this buffer.
+</para> 
+</refsect1>
+
+</refentry> 
+

lib/cds/dstring.h

@@ -41,7 +41,7 @@ typedef struct dstr_buff {
 
 /** Dynamic string structure. It is used
  * for muliple appends of any strings. */
-typedef struct dstring {
+typedef struct _dstring_t {
 	dlink_t buffers;
 	/** the length of whole string */
 	int len;

lib/cds/sstr.c

@@ -187,7 +187,7 @@ void str_clear(str_t *s)
 	}
 }
 
-char *str_strchr(const str *s, char c)
+char *str_strchr(const str_t *s, char c)
 {
 	if (s) {
 		int i;

lib/cds/sstr.h

@@ -87,7 +87,7 @@ int str_prefix(const str_t *a, const str_t *b); /* ss_start */
 void str_clear(str_t *s);
 
 /** locate character in string */
-char *str_strchr(const str *s, char c);
+char *str_strchr(const str_t *s, char c);
 
 #ifdef __cplusplus
 }