c09database.xml

<chapter id="c09database">
	<title>Database API</title>
	<para>
		Internally, &kamailio; uses a reduced set of SQL operations to access
		the records on the storage system. This allowed to write DB driver modules
		for non-SQL storage systems, such as <emphasis role="strong">db_text</emphasis>
		-- a tiny DB engine using text files.
	</para>
	<para>
		Therefore, the interface provides data types and functions that are independent
		of underlying DB storage. A DB driver module has to implement the functions specified
		by the interface and provide a function named <emphasis role="strong">db_bind_api(...)</emphasis>
		to link to the interface functions.
	</para>
	<para>
		Starting with version 3.0.0, &kamailio; has two variants of database APIs, stored
		as internal libraries, named <emphasis role="strong">srdb1</emphasis> and
		<emphasis role="strong">srdb2</emphasis>. Most of &kamailio; modules are using
		<emphasis role="strong">srdb1</emphasis>, thus for this document the focus will
		be on how to use this option.
	</para>
	<para>
		The DB1 interface is implemented in the <emphasis role="strong">lib/srdb1</emphasis> directory. To
		use it, one has to include the file <emphasis role="strong">lib/srdb1/db.h</emphasis>.
	</para>
	<section id="c09apistructure">
		<title>DB1 API Structure</title>
		<para>
			It is the structure that gets filled when binding to a DB driver module. It links to
			the interface functions implemented in the module.
		</para>
		<example id="c09d_db_func">
			<title>Definition</title>
<programlisting  format="linespecific">
...
typedef struct db_func {
	unsigned int      cap;            /* Capability vector of the database transport */
	db_use_table_f    use_table;      /* Specify table name */
	db_init_f         init;           /* Initialize database connection */
	db_close_f        close;          /* Close database connection */
	db_query_f        query;          /* query a table */
	db_fetch_result_f fetch_result;   /* fetch result */
	db_raw_query_f    raw_query;      /* Raw query - SQL */
	db_free_result_f  free_result;    /* Free a query result */
	db_insert_f       insert;         /* Insert into table */
	db_delete_f       delete;         /* Delete from table */ 
	db_update_f       update;         /* Update table */
	db_replace_f      replace;        /* Replace row in a table */
	db_last_inserted_id_f  last_inserted_id;  /* Retrieve the last inserted ID
	                                            in a table */
	db_insert_update_f insert_update; /* Insert into table, update on duplicate key */ 
	db_insert_delayed_f insert_delayed;       /* Insert delayed into table */
	db_affected_rows_f affected_rows; /* Numer of affected rows for last query */
} db_func_t;
...
			</programlisting>
		</example>
		<para>
			The attribute <emphasis role="strong">cap</emphasis> is a bitmask of implemented
			functions, making easy to detect the capabilities of the DB driver module. A module
			using the DB API should check at startup that the DB driver configured to be used
			has the required capabilities. For example, <emphasis role="strong">msilo</emphasis>
			module need <emphasis role="strong">select</emphasis>,
			<emphasis role="strong">delete</emphasis> and
			<emphasis role="strong">insert</emphasis> capabilities. The flags for capabilities
			are enumerated in the next figure (located in <emphasis role="strong">lib/srdb1/db_cap.h</emphasis>).
		</para>
<programlisting  format="linespecific">
...
typedef enum db_cap {
	DB_CAP_QUERY =     1 &lt;&lt; 0,  /* driver can perform queries                                     */
	DB_CAP_RAW_QUERY = 1 &lt;&lt; 1,  /* driver can perform raw queries                                 */
	DB_CAP_INSERT =    1 &lt;&lt; 2,  /* driver can insert data                                         */
	DB_CAP_DELETE =    1 &lt;&lt; 3,  /* driver can delete data                                         */
	DB_CAP_UPDATE =    1 &lt;&lt; 4,  /* driver can update data                                         */
	DB_CAP_REPLACE =   1 &lt;&lt; 5,  /* driver can replace (also known as INSERT OR UPDATE) data       */
	DB_CAP_FETCH   =   1 &lt;&lt; 6,  /* driver supports fetch result queries                           */
	DB_CAP_LAST_INSERTED_ID = 1 &lt;&lt; 7,  /* driver can return the ID of the last insert operation   */
	DB_CAP_INSERT_UPDATE = 1 &lt;&lt; 8,  /* driver can insert data into database, update on duplicate  */
	DB_CAP_INSERT_DELAYED = 1 &lt;&lt; 9, /* driver can do insert delayed                               */
	DB_CAP_AFFECTED_ROWS = 1 &lt;&lt; 10  /* driver can return number of rows affected by last query    */
} db_cap_t;
...
		</programlisting>
	</section>
	
	<section id="c09dbapi_functions">
		<title>DB1 API Functions</title>
		<para>
		</para>
		<section id="c09f_init">
			<title>Function init(...)</title>
			<para>
				Parse the DB URL and open a new connection to database.
			</para>
			<example id="c09t_init">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef db1_con_t* (*db_init_f) (const str* _url);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_url</emphasis> - database URL. Its format depends
						on DB driver. For an SQL server like MySQL has to be:
						<emphasis role="strong">mysql://username:password@server:port/database</emphasis>.
						For <emphasis role="strong">db_text</emphasis> has to be:
						<emphasis role="strong">text:///path/to/db/directory</emphasis>.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function returns pointer to db1_con_t* representing the connection structure or NULL
				in case of error.
			</para>
		</section>


		<section id="c09f_close">
			<title>Function close(...)</title>
			<para>
				The function closes previously open connection and frees all previously allocated
				memory. The function db_close must be the very last function called.
			</para>
			<example id="c09t_close">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef void (*db_close_f) (db1_con_t* _h);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - db1_con_t structure representing the
						database connection.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function returns nothing.
			</para>
		</section>

		<section id="c09f_use_table">
			<title>Function use_table(...)</title>
			<para> 
				Specify table name that will be used for subsequent operations (insert, delete,
				update, query).
			</para>
			<example id="c09t_use_table">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_use_table_f)(db1_con_t* _h, const str * _t);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_t</emphasis> - table name.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>


		<section id="c09f_query">
			<title>Function query(...)</title>
			<para> 
				Query table for specified rows. 
				This function implements the SELECT SQL directive.
			</para>
			<example id="c09t_query">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_query_f) (const db1_con_t* _h, const db_key_t* _k, const db_op_t* _op,
				const db_val_t* _v, const db_key_t* _c, const int _n, const int _nc,
				const db_key_t _o, db1_res_t** _r);

...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_k</emphasis> - array of column names that will be
						compared and their values must match.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_op</emphasis> - array of operators to be used with
						key-value pairs.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_v</emphasis> - array of values, columns specified 
						in _k parameter must match these values.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_c</emphasis> - array of column names that you
						are interested in.	
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_n</emphasis> - number of key-value pairs to match
						in _k and _v parameters.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_nc</emphasis> -  number of columns in _c parameter.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_o</emphasis> -  order by statement for query.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_r</emphasis> -  address of variable where pointer to
						the result will be stored.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
			<para>	<emphasis role="strong">Note:</emphasis>
				If _k and _v parameters are NULL and _n is zero, you will get the whole table.
				If _c is NULL and _nc is zero, you will get all table columns in the result.
				Parameter _r will point to a dynamically allocated structure, it is neccessary to 
				call db_free_result function once you are finished with the result.
				If _op is 0, equal (=) will be used for all key-value pairs comparisons.
				Strings in the result are not duplicated, they will be discarded if you call. Make 
				a copy of db_free_result if you need to keep it after db_free_result.
				You must call db_free_result before you can call db_query again!
			</para>
		</section>

		<section id="c09f_fetch_result">
			<title>Function fetch_result(...)</title>
			<para> 
				Fetch a number of rows from a result.
			</para>
			<example id="c09t_fetch_result">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_fetch_result_f) (const db1_con_t* _h, db1_res_t** _r, const int _n);

...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_r</emphasis> - structure for the result.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_n</emphasis> - the number of rows that should be fetched.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>

		<section id="c09f_raw_query">
			<title>Function raw_query(...)</title>
			<para> 
				This function can be used to do database specific queries. Please use this function 
				only if needed, as this creates portability issues for the different databases. 
				Also keep in mind that you need to escape all external data sources that you use.
				You could use the escape_common and unescape_common functions in the core for this task.
			</para>
			<example id="c09t_raw_query">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_raw_query_f) (const db1_con_t* _h, const str* _s, db1_res_t** _r);

...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_s</emphasis> -  the SQL query.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_r</emphasis> - structure for the result.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>


		<section id="c09f_free_result">
			<title>Function free_result(...)</title>
			<para> 
				Free a result allocated by db_query.
			</para>
			<example id="c09t_free_result">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_free_result_f) (db1_con_t* _h, db1_res_t* _r);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_r</emphasis> -  pointer to db1_res_t structure to
						destroy.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>

		<section id="c09f_insert">
			<title>Function insert(...)</title>
			<para> 
				 Insert a row into the specified table.
			</para>
			<example id="c09t_insert">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_insert_f) (const db1_con_t* _h, const db_key_t* _k,
				const db_val_t* _v, const int _n);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_k</emphasis> -   array of keys (column names).
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_v</emphasis> -   array of values for keys specified
						in _k parameter.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_n</emphasis> -  number of keys-value pairs int _k 
						and _v parameters.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>

		<section id="c09f_delete">
			<title>Function delete(...)</title>
			<para> 
				Delete a row from the specified table.
			</para>
			<example id="c09t_delete">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_delete_f) (const db1_con_t* _h, const db_key_t* _k, const db_op_t* _o,
				const db_val_t* _v, const int _n);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_k</emphasis> -  array of keys (column names) that 
						will be matched.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_o</emphasis> -   array of operators to be used with 
						key-value pairs.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_v</emphasis> -    array of values that the row must
						match to be deleted.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_n</emphasis> -  number of keys-value pairs int _k 
						and _v parameters.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>

		<section id="c09f_update">
			<title>Function update(...)</title>
			<para> 
				Update some rows in the specified table.
			</para>
			<example id="c09t_update">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_update_f) (const db1_con_t* _h, const db_key_t* _k, const db_op_t* _o,
				const db_val_t* _v, const db_key_t* _uk, const db_val_t* _uv,
				const int _n, const int _un);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_k</emphasis> -   array of keys (column names)
						that will be matched.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_o</emphasis> -   array of operators to be used with key-value pairs.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_v</emphasis> -   array of values that the row must match to be modified.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_uk</emphasis> -   array of keys (column names) that will be modified.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_uv</emphasis> -   new values for keys specified 
						in _k parameter.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_n</emphasis> -  number of key-value pairs in
						_v parameters.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_un</emphasis> -  number of key-value pairs in
						_uv parameters.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>


		<section id="c09f_replace">
			<title>Function replace(...)</title>
			<para> 
				Insert a row and replace if one already exists.
			</para>
			<example id="c09t_replace">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_replace_f) (const db1_con_t* handle, const db_key_t* keys,
				const db_val_t* vals, const int n);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_k</emphasis> -   array of keys (column names).
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_v</emphasis> -   array of values for keys specified
						in _k parameter.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_n</emphasis> -  number of keys-value pairs int _k 
						and _v parameters.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>

		<section id="c09f_last_inserted_id">
			<title>Function last_inserted_id(...)</title>
			<para> 
				 Retrieve the last inserted ID in a table.
			</para>
			<example id="c09t_last_inserted_id">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_last_inserted_id_f) (const db1_con_t* _h);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> -  structure representing database
						connection
					</para>
				</listitem>
					</itemizedlist>
			<para>
				The function returns the ID as integer or returns 0 if the previous statement
				does not use an AUTO_INCREMENT value.
			</para>
		</section>

		<section id="c09f_insert_update">
			<title>Function insert_update(...)</title>
			<para> 
				Insert a row into specified table, update on duplicate key.
			</para>
			<example id="c09t_insert_update">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_insert_update_f) (const db1_con_t* _h, const db_key_t* _k,
				const db_val_t* _v, const int _n);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_k</emphasis> -   array of keys (column names).
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_v</emphasis> -   array of values for keys specified
						in _k parameter.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_n</emphasis> -  number of keys-value pairs int _k 
						and _v parameters.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>

		<section id="c09f_insert_delayed">
			<title>Function insert_delayed(...)</title>
			<para> 
				Insert delayed a row into specified table - don't wait for confirmation from database
				server.
			</para>
			<example id="c09t_insert_delayed">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_insert_delayed_f) (const db1_con_t* _h, const db_key_t* _k,
				const db_val_t* _v, const int _n);

...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> - database connection handle.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_k</emphasis> -   array of keys (column names).
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_v</emphasis> -   array of values for keys specified
						in _k parameter.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis role="strong">_n</emphasis> -  number of keys-value pairs int _k 
						and _v parameters.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				The function 0 if everything is OK, otherwise returns value negative value.
			</para>
		</section>

		<section id="c09f_affected_rows">
			<title>Function affected_rows(...)</title>
			<para> 
				 Retrieve the number of affected rows by last operation done to database.
			</para>
			<example id="c09t_affected_rows">
				<title>Function type</title>
<programlisting  format="linespecific">
...
typedef int (*db_affected_rows_f) (const db1_con_t* _h);
...
				</programlisting>
			</example>
			<para>
				Parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis role="strong">_h</emphasis> -  structure representing database
						connection
					</para>
				</listitem>
					</itemizedlist>
			<para>
				The function returns the number of affected rows by previous DB operation.
			</para>
		</section>

	</section>
	
	<section id="c09dbapi_datatypes">
		<title>DB API Data Types</title>
		<para>
		</para>
		<section id="c09t_db_key_t">
			<title>Type db_key_t</title>
			<para>
				This type represents a database key (column). Every time you need to specify
				a key value, this type should be used.
			</para>
			<example id="c09d_db_key_t">
				<title>Definition</title>
				<programlisting  format="linespecific">
...
typedef str* db_key_t;
...
				</programlisting>
			</example>
		</section>

		<section id="c09t_db_op_t">
			<title>Type db_op_t</title>
			<para>
				This type represents an expression operator uses for SQL queries.
			</para>
			<example id="c09d_db_op_t">
				<title>Definition</title>
				<programlisting  format="linespecific">
...
typedef const char* db_op_t;
...
				</programlisting>
			</example>
			<para>
				Predefined operators are:
			</para>
			<example id="c09d_db_op_t_predefined">
				<title>DB Expression Operators</title>
				<programlisting  format="linespecific">
...
typedef const char* db_op_t;
/** operator less than */
#define OP_LT  "&lt;"
/** operator greater than */
#define OP_GT  "&gt;"
/** operator equal */
#define OP_EQ  "="
/** operator less than equal */
#define OP_LEQ "&lt;="
/** operator greater than equal */
#define OP_GEQ "&gt;="
/** operator negation */
#define OP_NEQ "!="
...
				</programlisting>
			</example>
		</section>	
		<section id="c09t_db_type_t">
			<title>Type db_type_t</title>
			<para>
			 Each cell in a database table can be of a different type. To distinguish 
			 among these types, the db_type_t enumeration is used. Every value of the
			 enumeration represents one datatype that is recognized by the database API. 
			</para>
			<example id="c09d_db_type_t">
				<title>Definition</title>
				<programlisting  format="linespecific">
...
typedef enum {
	DB1_INT,        /* represents an 32 bit integer number      */
	DB1_BIGINT,     /* represents an 64 bit integer number      */
	DB1_DOUBLE,     /* represents a floating point number       */
	DB1_STRING,     /* represents a zero terminated const char* */
	DB1_STR,        /* represents a string of 'str' type        */
	DB1_DATETIME,   /* represents date and time                 */
	DB1_BLOB,       /* represents a large binary object         */
	DB1_BITMAP      /* an one-dimensional array of 32 flags     */
	} db_type_t;
...
				</programlisting>
			</example>
		</section>	

		<section id="c09t_db_val_t">
			<title>Type db_val_t</title>
			<para>
				This structure represents a value in the database. Several datatypes are
				recognized and converted by the database API. These datatypes are 
				automatically recognized, converted from internal database representation 
				and stored in the variable of corresponding type.
				Modules that want to use this values needs to copy them to another memory
				location, because after the call to free_result there are not more available.
				If the structure holds a pointer to a string value that needs to be freed 
				because the module allocated new memory for it then the free flag must be
				set to a non-zero value. A free flag of zero means that the string data must
				be freed internally by the database driver.		
			</para>
			<example id="c09d_db_val_t">
				<title>Definition</title>
				<programlisting  format="linespecific">
...
typedef struct {
	db_type_t type; /* Type of the value                              */
	int nul;		/* Means that the column in database has no value */
	int free;		/* Means that the value should be freed */
	/** Column value structure that holds the actual data in a union.  */
	union {
		int           int_val;    /* integer value              */
		long long     ll_val;     /* long long value            */
		double        double_val; /* double value               */
		time_t        time_val;   /* unix time_t value          */
		const char*   string_val; /* zero terminated string     */
		str           str_val;    /* str type string value      */
		str           blob_val;   /* binary object data         */
		unsigned int  bitmap_val; /* Bitmap data type           */
	} val;
} db_val_t;
...
				</programlisting>
			</example>
		</section>	

		<section id="c09t_db1_con_t">
			<title>Type db_con_t</title>
			<para>
				This structure represents a database connection, pointer to this structure
				are used as a connection handle from modules uses the db API.
			</para>
			<example id="c09d_db1_con_t">
				<title>Definition</title>
				<programlisting  format="linespecific">
...
typedef struct {
	const str* table;      /* Default table that should be used              */
	unsigned long tail;    /* Variable length tail, database module specific */
} db1_con_t;
...
				</programlisting>
			</example>
		</section>

		<section id="c09t_db_row_t">
			<title>Type db_row_t</title>
			<para>
				Structure holding the result of a query table function. It represents one
				row in a database table. In other words, the row is an array of db_val_t
				variables, where each db_val_t variable represents exactly one cell in the
				table.
			</para>			
			<example id="c09d_db_row_t">
				<title>Definition</title>
				<programlisting  format="linespecific">
...
typedef struct db_row {
	db_val_t* values;  /* Columns in the row */
	int n;             /* Number of columns in the row */
	} db_row_t;
...
				</programlisting>
			</example>
		</section>


		<section id="c09t_db1_res_t">
			<title>Type db1_res_t</title>
			<para>
				This type represents a result returned by db_query function (see below).
				The result can consist of zero or more rows (see db_row_t description).
			</para>			
			<para>
				<emphasis role="strong">Note:</emphasis> A variable of type db_res_t
				returned by db_query function uses dynamically allocated memory, don't forget
				to call db_free_result if you don't need the variable anymore. You will
				encounter memory leaks if you fail to do this! In addition to zero or more
				rows, each db_res_t object contains also an array of db_key_t objects. The
				objects represent keys (names of columns). 
			</para>
			<example id="c09d_db1_res_t">
				<title>Definition</title>
				<programlisting  format="linespecific">
...
typedef struct db1_res {
	struct {
		db_key_t* names;   /* Column names                    */
		db_type_t* types;  /* Column types                    */
		int n;             /* Number of columns               */
	} col;
	struct db_row* rows;   /* Rows                            */
	int n;                 /* Number of rows in current fetch */
	int res_rows;          /* Number of total rows in query   */
	int last_row;          /* Last row                        */
	} db1_res_t;
...
				</programlisting>
			</example>
		</section>
	</section>
	<section id="c09macros">
		<title>Macros</title>
		<para>
			The DB API offers a set of macros to make easier to access the attributes in various data
			structures.
		</para>
		<para>
			Macros for <emphasis role="strong">db_res_t</emphasis>:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					RES_NAMES(res) - get the pointer to column names
				</para>
			</listitem>
			<listitem>
				<para>
					RES_COL_N(res) - get the number of columns
				</para>
			</listitem>
			<listitem>
				<para>
					RES_ROWS(res) - get the pointer to rows
				</para>
			</listitem>
			<listitem>
				<para>
					RES_ROW_N(res) - get the number of rows
				</para>
			</listitem>
		</itemizedlist>
		<para>
			Macros for <emphasis role="strong">db_val_t</emphasis>:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					ROW_VALUES(row) - get the pointer to values in the row
				</para>
			</listitem>
			<listitem>
				<para>
					ROW_N(row) - get the number of values in the row
				</para>
			</listitem>
		</itemizedlist>
		<para>
			Macros for <emphasis role="strong">db_val_t</emphasis>:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					VAL_TYPE(val) - get/set the type of a value
				</para>
			</listitem>
			<listitem>
				<para>
					VAL_NULL(val) - get/set the NULL flag for a value
				</para>
			</listitem>
			<listitem>
				<para>
					VAL_INT(val) - get/set the integer value
				</para>
			</listitem>
			<listitem>
				<para>
					VAL_BIGINT(val) - get/set the big integer value
				</para>
			</listitem>
			<listitem>
				<para>
					VAL_STRING(val) - get/set the null-terminated string value
				</para>
			</listitem>
			<listitem>
				<para>
					VAL_STR(val) - get/set the str value
				</para>
			</listitem>
			<listitem>
				<para>
					VAL_DOUBLE(val) - get/set the double value
				</para>
			</listitem>
			<listitem>
				<para>
					VAL_TIME(val) - get/set the time value
				</para>
			</listitem>
			<listitem>
				<para>
					VAL_BLOB(val) - get/set the blob value
				</para>
			</listitem>
		</itemizedlist>
	</section>
	<section id="c09example">
		<title>Example of usage</title>
		<para>
			A simple example of doing a select. The table is named test and has two columns.
		</para>
		<programlisting  format="linespecific">
...
create table test (
    a int,
	b varchar(64)
);
...
		</programlisting>
		<para>
			The C code:
		</para>
		<programlisting  format="linespecific">
...
<![CDATA[
#include "../../dprint.h"
#include "../../lib/srdb1/db.h"

db_func_t db_funcs;      /* Database API functions */
db1_con_t* db_handle=0;   /* Database connection handle */

int db_example(char *db_url)
{
	str table;
	str col_a;
	str col_b;
	int nr_keys=0;
	db_key_t db_keys[1];
	db_val_t db_vals[1];
	db_key_t db_cols[1];
	db1_res_t* db_res = NULL;

    /* Bind the database module */
	if (db_bind_mod(&db_url, &db_funcs))
	{
		LM_ERR("failed to bind database module\n");
		return -1;
	}
	/* Check for SELECT capability */
	if (!DB_CAPABILITY(db_funcs, DB_CAP_QUERY))
	{
		LM_ERR("Database modules does not "
			"provide all functions needed here\n");
		return -1;
	}
	/* Connect to DB */
	db_handle = db_funcs.init(&db_url);
	if (!db_handle)
	{
		LM_ERR("failed to connect database\n");
		return -1;
	}

	/* Prepare the data for the query */
	table.s = "test";
	table.len = 4;

	col_a.s = "a";
	col_a.len = 1;
	col_b.s = "b";
	col_b.len = 1;

	db_cols[0] = &col_b;
	db_keys[0] = &col_a;
	
	db_vals[nr_keys].type = DB_INT;
	db_vals[nr_keys].nul = 0;
	db_vals[nr_keys].val.int_val = 1;
	nr_keys++;

	/* execute the query */
	/* -- select b from test where a=1 */
	db_funcs.use_table(db_handle, &table);
	if(db_funcs.query(db_handle, db_keys, NULL, db_vals, db_cols,
		nr_keys /*no keys*/, 1 /*no cols*/, NULL, &db_res)!=0)
	{
		LM_ERR("failed to query database\n");
		db_funcs.close(db_handle);
		return -1;
	}

	if (RES_ROW_N(db_res)<=0 || RES_ROWS(db_res)[0].values[0].nul != 0)
	{
		LM_DBG("no value found\n");
		if (db_res!=NULL && db_funcs.free_result(db_handle, db_res) < 0)
			LM_DBG("failed to free the result\n");
		db_funcs.close(db_handle);
		return -1;
	}

	/* Print the first value */
	if(RES_ROWS(db_res)[0].values[0].type == DB_STRING)
		LM_DBG("first value found is [%s]\n",
			(char*)RES_ROWS(db_res)[0].values[0].val.string_val);
	else if(RES_ROWS(db_res)[0].values[0].type == DB_STR)
		LM_DBG("first value found is [%.*s]\n",
			RES_ROWS(db_res)[0].values[0].val.str_val.len,
			(char*)RES_ROWS(db_res)[0].values[0].val.str_val.s);
	else
		LM_DBG("first value found has an unexpected type [%d]\n",
			RES_ROWS(db_res)[0].values[0].type);

	/* Free the result */
	db_funcs.free_result(db_handle, db_res);
	db_funcs.close(db_handle);

	return 0;
}
]]>
...
		</programlisting>
	</section>
</chapter>