$Revision$ $Date$ This is a generic database interface for modules that need to utilize a database. The interface should be used by all modules that access database. The interface will be independent of the underlying database server. If possible, use predefined macros if you need to access any structure attributes. For additional description, see comments in sources of mysql module. If you want to see more complicated examples of how the API could be used, see sources of dbexample, usrloc or auth modules.

There are several data types. All of them are defined in header files under db subdirectory, a client must include db.h header file to be able to use them.

There are several functions that implement the database API logic. All function names start with db_ prefix, except bind_dbmod. bind_dbmod is implemented in db.c file, all other functions are implemented in a standalone module. Detailed description of functions follows.

This function is special, its only purpose is to call find_export function in the SER core and find addresses of all other functions (starting with db_ prefix). This function MUST be called FIRST ! int bind_dbmod The function takes no parameters. The function returns 0 if it was able to find addresses of all other functions, otherwise value < 0 is returned.

Use this function to initialize the database API and open a new database connection. This function must be called after bind_dbmod but before any other function is called. db_con_t* db_init const char* _sql_url The function takes one parameter, the parameter must contain database connection URL. The URL is of the form mysql://username:password@host:port/database where: username - Username to use when logging into database (optional). password - Password if it was set (optional). host - Hostname or IP address of the host where database server lives (mandatory). port - Port number of the server if the port differs from default value (optional). database - If the database server supports multiple databases, you must specify name of the database (optional). The function returns pointer to db_con_t* representing the connection if it was successful, otherwise 0 is returned.

The function closes previously open connection and frees all previously allocated memory. The function db_close must be the very last function called. void db_close db_con_t* _h The function takes one parameter, this parameter is a pointer to db_con_t structure representing database connection that should be closed. Function doesn't return anything.

This function implements SELECT SQL directive. int db_query db_con_t* _h db_key_t* _k db_val_t* _v db_key_t* _c int _n int _nc db_key_t* _o db_res_t** _r The function takes 8 parameters: _h - Database connection handle. _k - Array of column names that will be compared and their values must match. _v - Array of values, columns specified in _k parameter must match these values. _c - Array of column names that you are interested in. _n - Number of key-value pairs to match in _k and _v parameters. _nc - Number of columns in _c parameter. _o - Order by. _r - Address of variable where pointer to the result will be stored. 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 _r will point to a dynamically allocated structure, it is necessary to call db_free_result function once you are finished with the result. Strings in the result are not duplicated, they will be discarded if you call db_free_result, make a copy yourself if you need to keep it after db_free_result. You must call db_free_result BEFORE you can call db_query again ! The function returns 0 if everything is OK, otherwise value < 0 is returned.

This function frees all memory allocated previously in db_query, it is necessary to call this function for a db_res_t structure if you don't need the structure anymore. You must call this function BEFORE you call db_query again ! int db_free_result db_con_t* _h db_res_t* _r The function takes 2 parameters: _h - Database connection handle. _r - Pointer to db_res_t structure to destroy. The function returns 0 if everything is OK, otherwise the function returns value < 0.

This function implements INSERT SQL directive, you can insert one or more rows in a table using this function. int db_insert db_con_t* _h db_key_t* _k db_val_t* _v int _n The function takes 4 parameters: _h - Database connection handle. _k - Array of keys (column names). _v - Array of values for keys specified in _k parameter. _n - Number of keys-value pairs int _k and _v parameters. The function returns 0 if everything is OK, otherwise the function returns value < 0.

This function implements DELETE SQL directive, it is possible to delete one or more rows from a table. int db_delete db_con_t* _h db_key_t* _k db_val_t* _v int _n The function takes 4 parameters: _h - Database connection handle. _k - Array of keys (column names) that will be matched. _v - Array of values that the row must match to be deleted. _n - Number of keys-value parameters in _k and _v parameters. If _k is NULL and _v is NULL and _n is zero, all rows are deleted (table will be empty). The function returns 0 if everything is OK, otherwise the function returns value < 0.

The function implements UPDATE SQL directive. It is possible to modify one or more rows in a table using this function. int db_update db_con_t* _h db_key_t* _k db_val_t* _v db_key_t* _uk db_val_t* _uv int _n int _un The function takes 7 parameters: _h - Database connection handle. _k - Array of keys (column names) that will be matched. _v - Array of values that the row must match to be modified. _uk - Array of keys (column names) that will be modified. _uv - New values for keys specified in _k parameter. _n - Number of key-value pairs in _k and _v parameters. _un - Number of key-value pairs in _uk and _uv parameters. The function returns 0 if everything is OK, otherwise the function returns value < 0.

The function db_use_table takes a table name and stores it in db_con_t structure. All subsequent operations (insert, delete, update, query) are performed on that table. int db_use-table db_con_t* _h cons char* _t The function takes 2 parameters: _h - Database connection handle. _t - Table name. The function returns 0 if everything is OK, otherwise the function returns value < 0.