$Revision$
$Date$

# The Database Interface

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.

## Data types

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.

## Functions

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.

### `bind_dbmod`

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.

### `db_init`

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.

### `db_close`

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.

### `db_query`

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.

### `db_free_result`

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.

### `db_insert`

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.

### `db_delete`

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.

### `db_update`

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.

### `db_use_table`

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.