SIP Express Router v0.8.8 - Developer's Guide
<<< PreviousThe Database InterfaceNext >>>

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. Detaileddescription of functions follows.

bind_dbmod

This function is special, it's 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(void);

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 sql://username:password@host:port/database where:

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:

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 neccessary to call db_free_query function once you are finished with the result.

Strings in the result are not duplicated, they will be discarded if you call db_free_query, make a copy yourself if you need to keep it after db_free_query.

You must call db_free_query BEFORE you can call db_query again !

The function returns 0 if everything is OK, otherwise value < 0 is returned.

db_free_query

This function frees all memory allocated previously in db_query, it is neccessary 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_query(db_con_t* _h, db_res_t* _r);

The function takes 2 parameters:

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:

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:

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:

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:

The function returns 0 if everything is OK, otherwise the function returns value < 0.

<<< PreviousHomeNext >>>
The Database InterfaceUpBasic Modules