-       ratbox-services database abstraction         -
- Copyright (C) 2006 Lee Hardy <lee -at- leeh.co.uk> -
- Copyright (C) 2006 ircd-ratbox development team    -
------------------------------------------------------

This document describes the database abstraction layer contained in
ratbox-services, allowing the code to be database agnostic and tie in to
different database software.

- void rsdb_init(void) -
------------------------

This function is called to initialise the database so it is ready for use.

- void rsdb_shutdown(void) -
----------------------------

This function is called on termination to close the database safely.

- const char *rsdb_quote(const char *src) -
-------------------------------------------

This function is called when a string taken from user input needs to be
safely quoted to avoid SQL injection.  rsdb_quote() will not be called more
than once in a single function call, as such it is assumed it will return a
static string that does not need any memory cleaned up.

rsdb_quote() is generally called only from the custom rs_snprintf()
function, where the "%Q" modifier has been added to quote strings inline.

- void rsdb_exec(rsdb_callback cb, const char *format, ...) -
-------------------------------------------------------------

This function is called to execute an SQL statement with an optional
callback.  The format accepts the string modifier "%Q" to pass input through
rsdb_quote() so it is safe.

When passed a callback function, this should be called by rsdb_exec() for
each row returned by the query.  This callback function takes three
arguments, an int containing the number of fields, a char ** array
containing each of the field values, and a char ** array containing the
field names.

- struct rsdb_table -
---------------------

This struct is used when returning an entire table worth of data.  It
comprises the following members:
	char ***row	- An array of the rows and columns in the result
			  set, row[row_position][column_position]
	int row_count	- Number of rows in the result set
	int col_count	- Number of columns in the result set
	void *arg	- Generic storage for rsdb_exec_fetch_end()

- void rsdb_exec_fetch(struct rsdb_table *data, const char *format, ...) -
--------------------------------------------------------------------------

This function is called to execute an SQL statement without using a
callback, it will return the entire result set.  The format accepts the
string modifier "%Q" to pass input through rsdb_quote().

The rsdb_table struct passed to this function does not need to be memset
before use, as rsdb_exec_fetch() will reset the struct itself.  Anything
calling rsdb_exec_fetch() must also call rsdb_exec_fetch_end() to cleanup.

- void rsdb_exec_fetch_end(struct rsdb_table *data) -
-----------------------------------------------------

This function is called to cleanup the memory allocated by the database and
ratbox-services for the query.

- void rsdb_transaction(rsdb_transtype type) -
----------------------------------------------

This function is used primarily for sqlite, to group a large number of
queries together for efficiency.  It is passed either RSDB_TRANS_START or
RSDB_TRANS_END.

