Data Structures | Typedefs | Functions

lib/srdb1/db.h File Reference

db.c More...

#include "db_key.h"
#include "db_op.h"
#include "db_val.h"
#include "db_con.h"
#include "db_res.h"
#include "db_cap.h"
#include "db_row.h"
#include "db_res.h"
Include dependency graph for lib/srdb1/db.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

Typedefs

Functions

Detailed Description

Generic 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. Notes: If possible, use the predefined macros if you need to access any structure attributes. For additional description, see the comments in the sources of mysql module.

If you want to see more complicated examples of how the API could be used, take a look at the sources of the usrloc or auth modules.

Definition in file lib/srdb1/db.h.

Typedef Documentation

typedef int(* db_abort_transaction_f)(db1_con_t *_h)

Use this function if you have an error after having started a transaction and you want to rollback any uncommitted changes before continuing.

Parameters:
_h structure representing database connection
Returns:
1 if there was something to rollbak, 0 if not, negative on failure

Definition at line 368 of file lib/srdb1/db.h.

typedef int(* db_affected_rows_f)(const db1_con_t *_h)

The function returns the rows affected by the last query. If any other type of query was the last, it returns null.

Parameters:
_h structure representing database connection
Returns:
returns the number of rows as integer or returns -1 on error

Definition at line 342 of file lib/srdb1/db.h.

typedef int(* db_bind_api_f)(db_func_t *dbb)

The function links the functions implemented by the module to the members of db_func_t structure

Parameters:
dbb db_func_t structure representing the variable where to bind
Returns:
0 if everything is ok, otherwise returns -1

Definition at line 505 of file lib/srdb1/db.h.

typedef void(* db_close_f)(db1_con_t *_h)

The function closes previously open connection and frees all previously allocated memory. The function db_close must be the very last function called.

Parameters:
_h db1_con_t structure representing the database connection

Definition at line 128 of file lib/srdb1/db.h.

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)

This function implements DELETE SQL directive, it is possible to delete one or more rows from a table. If _k is NULL and _v is NULL and _n is zero, all rows are deleted, the resulting table will be empty. If _o is NULL, the equal operator "=" will be used for the comparison.

Parameters:
_h database connection handle
_k array of keys (column names) that will be matched
_o array of operators to be used with key-value pairs
_v array of values that the row must match to be deleted
_n number of keys-value parameters in _k and _v parameters
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 244 of file lib/srdb1/db.h.

typedef int(* db_end_transaction_f)(db1_con_t *_h)
Parameters:
_h structure representing database connection
Returns:
0 if everything is OK, otherwise returns < 0

Definition at line 358 of file lib/srdb1/db.h.

typedef int(* db_fetch_result_f)(const db1_con_t *_h, db1_res_t **_r, const int _n)

Gets a partial result set, fetch a number of rows from a database result. This function initialize the given result structure on the first run, and fetches the nrows number of rows. On subsequenting runs, it uses the existing result and fetches more rows, until it reaches the end of the result set. Because of this the result needs to be null in the first invocation of the function. If the number of wanted rows is zero, the function returns anything with a result of zero.

Parameters:
_h structure representing database connection
_r structure for the result
_n the number of rows that should be fetched
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 179 of file lib/srdb1/db.h.

typedef int(* db_free_result_f)(db1_con_t *_h, db1_res_t *_r)

This function frees all memory allocated previously in db_query. Its neccessary to call this function on a db1_res_t structure if you don't need the structure anymore. You must call this function before you call db_query again!

Parameters:
_h database connection handle
_r pointer to db1_res_t structure to destroy
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 210 of file lib/srdb1/db.h.

typedef struct db_func db_func_t

This structure holds function pointer to all database functions. Before this structure can be used it must be initialized with bind_dbmod.

See also:
bind_dbmod
typedef db1_con_t*(* db_init2_f)(const str *_sqlurl, db_pooling_t _pooling)

This function initialize the database API and open a new database connection. This function must be called after bind_dbmod but before any other database API function is called.

The function takes one parameter, the parameter must contain the 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: Hosname 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 the name of the database (optional).

See also:
bind_dbmod
Parameters:
_sqlurl database connection URL
_pooling whether or not to use a pooled connection
Returns:
returns a pointer to the db1_con_t representing the connection if it was successful, otherwise 0 is returned

Definition at line 119 of file lib/srdb1/db.h.

typedef db1_con_t*(* db_init_f)(const str *_sqlurl)

This function initialize the database API and open a new database connection. This function must be called after bind_dbmod but before any other database API function is called.

The function takes one parameter, the parameter must contain the 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: Hosname 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 the name of the database (optional).

See also:
bind_dbmod
Parameters:
_sqlurl database connection URL
Returns:
returns a pointer to the db1_con_t representing the connection if it was successful, otherwise 0 is returned

Definition at line 94 of file lib/srdb1/db.h.

typedef int(* db_insert_delayed_f)(const db1_con_t *_h, const db_key_t *_k, const db_val_t *_v, const int _n)

This function implements INSERT DELAYED SQL directive. It is possible to insert one or more rows in a table with delay using this function.

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
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 330 of file lib/srdb1/db.h.

typedef int(* db_insert_f)(const db1_con_t *_h, const db_key_t *_k, const db_val_t *_v, const int _n)

This function implements INSERT SQL directive, you can insert one or more rows in a table using this function.

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
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 224 of file lib/srdb1/db.h.

typedef int(* db_insert_update_f)(const db1_con_t *_h, const db_key_t *_k, const db_val_t *_v, const int _n)

The function implements the INSERT ON DUPLICATE KEY UPDATE SQL directive. It is possible to insert a row and update if one already exists. The old row will not deleted before the insertion of the new data.

Parameters:
_h structure representing database connection
_k key names
_v values of the keys
_n number of key=value pairs
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 315 of file lib/srdb1/db.h.

typedef int(* db_last_inserted_id_f)(const db1_con_t *_h)

The function returns the value generated for an AUTO_INCREMENT column by the previous INSERT or UPDATE statement. Use this function after you have performed an INSERT statement into a table that contains an AUTO_INCREMENT field.

Parameters:
_h structure representing database connection
Returns:
returns the ID as integer or returns 0 if the previous statement does not use an AUTO_INCREMENT value.

Definition at line 300 of file lib/srdb1/db.h.

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)

This function implements the SELECT SQL directive. 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_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 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!

See also:
db_free_result
Parameters:
_h database connection handle
_k array of column names that will be compared and their values must match
_op array of operators to be used with key-value pairs
_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 statement for query
_r address of variable where pointer to the result will be stored
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 160 of file lib/srdb1/db.h.

typedef int(* db_raw_query_f)(const db1_con_t *_h, const str *_s, db1_res_t **_r)

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.

See also:
escape_common
unescape_common
Parameters:
_h structure representing database connection
_s the SQL query
_r structure for the result
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 197 of file lib/srdb1/db.h.

typedef int(* db_replace_f)(const db1_con_t *handle, const db_key_t *keys, const db_val_t *vals, const int n, const int _un, const int _m)

The function implements the REPLACE SQL directive. It is possible to insert a row and replace if one already exists. The old row will be deleted before the insertion of the new data.

Parameters:
_h structure representing database connection
_k key names
_v values of the keys
_n number of key=value pairs
_un number of keys to build the unique key, starting from first _k
_m mode - first update, then insert, or first insert, then update
Note:
the last two parameters are used only if the DB server does not have native replace command (like postgres - the module doing an internal implementation using synchronized update/affected rows/insert mechanism)
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 285 of file lib/srdb1/db.h.

typedef int(* db_start_transaction_f)(db1_con_t *_h)
Parameters:
_h structure representing database connection
Returns:
0 if everything is OK, otherwise returns < 0

Definition at line 350 of file lib/srdb1/db.h.

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)

The function implements UPDATE SQL directive. It is possible to modify one or more rows in a table using this function.

Parameters:
_h database connection handle
_k array of keys (column names) that will be matched
_o array of operators to be used with key-value pairs
_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
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 263 of file lib/srdb1/db.h.

typedef int(* db_use_table_f)(db1_con_t *_h, const str *_t)

The function db_use_table takes a table name and stores it db1_con_t structure. All subsequent operations (insert, delete, update, query) are performed on that table.

Parameters:
_h database connection handle
_t table name
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Definition at line 70 of file lib/srdb1/db.h.

Function Documentation

int db_api_init ( void   ) 

This function must be executed by DB connector modules at load time to initialize the internals of DB API library.

Returns:
returns 0 on successful initialization, -1 on error.

Definition at line 519 of file lib/srdb1/db.c.

References db_query_init().

Referenced by db_mysql_alloc_buffer().

Here is the call graph for this function:

Here is the caller graph for this function:

int db_bind_mod ( const str *  mod,
db_func_t *  mydbf 
)

This function is special, it's only purpose is to call find_export function in the core and find the addresses of all other database related functions. The db_func_t callback given as parameter is updated with the found addresses.

This function must be called before any other database API call!

The database URL is of the form "mysql://username:password@host:port/database" or "mysql" (database module name). In the case of a database connection URL, this function looks only at the first token (the database protocol). In the example above that would be "mysql":

See also:
db_func_t
Parameters:
mod database connection URL or a database module name
dbf database module callbacks
Returns:
returns 0 if everything is OK, otherwise returns value < 0

Bind database module functions.

Parameters:
mod 
mydbf 
Returns:
returns 0 on success, -1 on error
Note:
on error mydbf will contain only 0s

Definition at line 158 of file lib/srdb1/db.c.

References _str::len, MAX_URL_LENGTH, and _str::s.

Referenced by carrierroute_db_init(), domainpolicy_db_bind(), group_db_bind(), init_ds_db(), matrix_db_init(), mod_init(), pl_init_db(), and userblacklist_db_init().

Here is the caller graph for this function:

int db_check_table_version ( db_func_t *  dbf,
db1_con_t *  dbh,
const str *  table,
const unsigned int  version 
)

Small helper function to check the table version.

Parameters:
dbf database module callbacks
dbh database connection handle
table checked table
version checked version
Returns:
0 means ok, -1 means an error occured

Definition at line 432 of file lib/srdb1/db.c.

References db_table_version(), _str::len, and _str::s.

Referenced by carrierroute_db_init(), matrix_db_init(), mod_init(), register_udomain(), and userblacklist_db_init().

Here is the call graph for this function:

Here is the caller graph for this function:

void db_do_close ( db1_con_t *  _h,
void(*)()  free_connection 
)

This helper method does some work for the closing of a database connection. No function should be called after this

Parameters:
_h database connection handle
(*free_connection) Pointer to the db specifc free_connection method

Helper for db_close function.

Note:
No function should be called after this

Definition at line 342 of file lib/srdb1/db.c.

References pool_remove(), and db1_con_t::tail.

Referenced by db_mysql_close(), and db_postgres_close().

Here is the call graph for this function:

Here is the caller graph for this function:

db1_con_t* db_do_init ( const str *  url,
void *(*)()  new_connection 
)

This helper method do the actual work for the database specific db_init functions.

Parameters:
url database connection URL
(*new_connection)() Pointer to the db specific connection creation method
Returns:
returns a pointer to the db1_con_t representing the connection if it was successful, otherwise 0 is returned.

Helper for db_init function.

Note:
No function should be called before this

Definition at line 269 of file lib/srdb1/db.c.

References db_do_init2().

Referenced by db_mysql_init(), and db_postgres_init().

Here is the call graph for this function:

Here is the caller graph for this function:

db1_con_t* db_do_init2 ( const str *  url,
void *(*)()  new_connection,
db_pooling_t  pooling 
)

This helper method do the actual work for the database specific db_init functions.

Parameters:
url database connection URL
(*new_connection)() Pointer to the db specific connection creation method
pooling whether or not to use a pooled connection
Returns:
returns a pointer to the db1_con_t representing the connection if it was successful, otherwise 0 is returned.

Helper for db_init2 function.

Note:
No function should be called before this

Definition at line 279 of file lib/srdb1/db.c.

References free_db_id(), _str::len, MAX_URL_LENGTH, new_db_id(), pool_get(), pool_insert(), _str::s, and db1_con_t::tail.

Referenced by db_do_init(), and db_postgres_init2().

Here is the call graph for this function:

Here is the caller graph for this function:

int db_fetch_next ( db_func_t *  dbf,
int  frows,
db1_con_t *  _h,
db1_res_t **  _r 
)
Returns:
-1 error; 0 ok with no fetch capability; 1 ok with fetch capability

Definition at line 435 of file db_query.c.

References DB_CAP_FETCH, and DB_CAPABILITY.

int db_fetch_query ( db_func_t *  dbf,
int  frows,
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 
)
Returns:
-1 error; 0 ok with no fetch capability; 1 ok with fetch capability

Definition at line 389 of file db_query.c.

References DB_CAP_FETCH, and DB_CAPABILITY.

int db_load_bulk_data ( db_func_t *  binding,
db1_con_t *  handle,
str *  name,
db_key_t *  cols,
unsigned int  count,
unsigned int  strict,
db1_res_t *  res 
)

Generic query helper method for load bulk data, e.g. lcr tables

Parameters:
binding database module binding
handle database connection
name database table name
cols queried columns
count number of queried columns
strict if set to 1 an error is returned when no data could be loaded, otherwise just a warning is logged
res database result, unchanged on failure and if no data could be found
Returns:
0 if the query was run successful, -1 otherwise

Definition at line 474 of file lib/srdb1/db.c.

References _str::len, RES_ROW_N, and _str::s.

int db_table_version ( const db_func_t *  dbf,
db1_con_t *  connection,
const str *  table 
)

Returns the version number of a given table from the version table. Instead of this function you could also use db_check_table_version

Parameters:
dbf database module callbacks
con database connection handle
table checked table
Returns:
the version number if present, 0 if no version data available, < 0 on error

Get the version of a table.

Parameters:
dbf 
connection 
table 
Returns:
If there is no row for the given table, return version 0

Definition at line 368 of file lib/srdb1/db.c.

References DB1_INT, _str::len, RES_ROW_N, RES_ROWS, ROW_VALUES, _str::s, TABLENAME_COLUMN, VAL_INT, VAL_NULL, VAL_STR, VAL_TYPE, VERSION_COLUMN, and VERSION_TABLE.

Referenced by db_check_table_version(), domainpolicy_db_ver(), init_ds_db(), and pl_init_db().

Here is the caller graph for this function:

int db_use_table ( db1_con_t *  _h,
const str *  _t 
)

Stores the name of the table that will be used by subsequent database functions calls in a db1_con_t structure.

Parameters:
_h database connection handle
_t stored name
Returns:
0 if everything is ok, otherwise returns value < 0

Definition at line 449 of file lib/srdb1/db.c.

References CON_TABLE, and _str::s.

Referenced by db_mysql_use_table(), and db_postgres_use_table().

Here is the caller graph for this function:

Generated on Tue May 22 2012 13:10:20 for SIP Router by  doxygen 1.7.1