db/db.h File Reference

Generic Database Interface. 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 dependency graph for db/db.h:

Go to the source code of this file.

Data Structures
struct	db_func
	Database module callbacks. More...
Typedefs
typedef int(*	db_bind_api_f )(db_func_t *dbb)
	Bind the DB API exported by a module.
typedef void(*	db_close_f )(db_con_t *_h)
	Close a database connection and free all memory used.
typedef int(*	db_delete_f )(const db_con_t *_h, const db_key_t *_k, const db_op_t *_o, const db_val_t *_v, const int _n)
	Delete a row from the specified table.
typedef int(*	db_fetch_result_f )(const db_con_t *_h, db_res_t **_r, const int _n)
	Gets a partial result set, fetch rows from a result.
typedef int(*	db_free_result_f )(db_con_t *_h, db_res_t *_r)
	Free a result allocated by db_query.
typedef struct db_func	db_func_t
	Database module callbacks.
typedef db_con_t *(*	db_init_f )(const str *_sqlurl)
	Initialize database connection and obtain the connection handle.
typedef int(*	db_insert_f )(const db_con_t *_h, const db_key_t *_k, const db_val_t *_v, const int _n)
	Insert a row into the specified table.
typedef int(*	db_insert_update_f )(const db_con_t *_h, const db_key_t *_k, const db_val_t *_v, const int _n)
	Insert a row into specified table, update on duplicate key.
typedef int(*	db_last_inserted_id_f )(const db_con_t *_h)
	Retrieve the last inserted ID in a table.
typedef int(*	db_query_f )(const db_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, db_res_t **_r)
	Query table for specified rows.
typedef int(*	db_raw_query_f )(const db_con_t *_h, const str *_s, db_res_t **_r)
	Raw SQL query.
typedef int(*	db_replace_f )(const db_con_t *handle, const db_key_t *keys, const db_val_t *vals, const int n)
	Insert a row and replace if one already exists.
typedef int(*	db_update_f )(const db_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)
	Update some rows in the specified table.
typedef int(*	db_use_table_f )(db_con_t *_h, const str *_t)
	Specify table name that will be used for subsequent operations.
Functions
int	db_bind_mod (const str *mod, db_func_t *dbf)
	Bind database module functions.
int	db_check_table_version (db_func_t *dbf, db_con_t *dbh, const str *table, const unsigned int version)
	Check the table version.
void	db_do_close (db_con_t *_h, void(*free_connection)())
	Helper for db_close function.
db_con_t *	db_do_init (const str *url, void *(*new_connection)())
	Helper for db_init function.
int	db_table_version (const db_func_t *dbf, db_con_t *con, const str *table)
	Get the version of a table.
int	db_use_table (db_con_t *_h, const str *_t)
	Stores the name of a table.

---

Detailed Description

Generic Database Interface.

db.c 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 db/db.h.

---

Typedef Documentation

typedef int(* db_bind_api_f)(db_func_t *dbb)

Bind the DB API exported by a module.

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 399 of file db/db.h.

typedef void(* db_close_f)(db_con_t *_h)

Close a database connection and free all memory used.

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

db_con_t structure representing the database connection

Definition at line 98 of file db/db.h.

typedef int(* db_delete_f)(const db_con_t *_h, const db_key_t *_k, const db_op_t *_o, const db_val_t *_v, const int _n)

Delete a row from the specified table.

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 214 of file db/db.h.

typedef int(* db_fetch_result_f)(const db_con_t *_h, db_res_t **_r, const int _n)

Gets a partial result set, fetch rows from a result.

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 149 of file db/db.h.

typedef int(* db_free_result_f)(db_con_t *_h, db_res_t *_r)

Free a result allocated by db_query.

This function frees all memory allocated previously in db_query. Its neccessary to call this function on a db_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 db_res_t structure to destroy

Returns:

returns 0 if everything is OK, otherwise returns value < 0

Definition at line 180 of file db/db.h.

typedef struct db_func db_func_t

Database module callbacks.

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 db_con_t*(* db_init_f)(const str *_sqlurl)

Initialize database connection and obtain the connection handle.

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 db_con_t representing the connection if it was successful, otherwise 0 is returned

Definition at line 89 of file db/db.h.

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

Insert a row into the specified table.

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 194 of file db/db.h.

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

Insert a row into specified table, update on duplicate key.

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 280 of file db/db.h.

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

Retrieve the last inserted ID in a table.

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 265 of file db/db.h.

typedef int(* db_query_f)(const db_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, db_res_t **_r)

Query table for specified rows.

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 130 of file db/db.h.

typedef int(* db_raw_query_f)(const db_con_t *_h, const str *_s, db_res_t **_r)

Raw SQL query.

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 167 of file db/db.h.

typedef int(* db_replace_f)(const db_con_t *handle, const db_key_t *keys, const db_val_t *vals, const int n)

Insert a row and replace if one already exists.

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

Returns:

returns 0 if everything is OK, otherwise returns value < 0

Definition at line 250 of file db/db.h.

typedef int(* db_update_f)(const db_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)

Update some rows in the specified table.

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 233 of file db/db.h.

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

Specify table name that will be used for subsequent operations.

The function db_use_table takes a table name and stores it db_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 65 of file db/db.h.

---

Function Documentation

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

Bind database module functions.

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 148 of file db/db.c.

References db_func::close, db_check_api(), db_func::delete, db_func::fetch_result, find_mod_export(), db_func::free_result, db_func::init, db_func::insert, db_func::insert_update, db_func::last_inserted_id, _str::len, len, LM_CRIT, LM_DBG, LM_ERR, MAX_URL_LENGTH, NULL, pkg_free, pkg_malloc, db_func::query, db_func::raw_query, db_func::replace, _str::s, db_func::update, and db_func::use_table.

Referenced by avpops_db_bind(), carrierroute_db_init(), cpl_db_bind(), domain_db_bind(), domainpolicy_db_bind(), group_db_bind(), init(), init_addresses(), init_db_data(), init_dlg_db(), init_ds_db(), init_trusted(), lcr_db_bind(), mod_init(), uridb_db_bind(), and userblacklist_db_init().

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

Check the table 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 402 of file db/db.c.

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

Referenced by auth_fixup(), carrierroute_db_init(), cpl_db_bind(), domain_db_ver(), init_addresses(), init_child_trusted(), init_db_data(), init_dlg_db(), init_trusted(), mod_init(), register_udomain(), and userblacklist_db_init().

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

Helper for db_close function.

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 311 of file db/db.c.

References LM_ERR, pkg_free, pool_remove(), and db_con_t::tail.

Referenced by db_mysql_close(), db_oracle_close(), db_postgres_close(), and db_unixodbc_close().

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

Helper for db_init function.

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 db_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 248 of file db/db.c.

References free_db_id(), id, _str::len, LM_DBG, LM_ERR, MAX_URL_LENGTH, new_db_id(), pkg_free, pkg_malloc, pool_get(), pool_insert(), _str::s, and db_con_t::tail.

Referenced by db_mysql_init(), db_oracle_init(), db_postgres_init(), and db_unixodbc_init().

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

Get the version of a 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 337 of file db/db.c.

References DB_INT, DB_STR, db_func::free_result, _str::len, LM_CRIT, LM_DBG, LM_ERR, NULL, db_func::query, RES_ROW_N, RES_ROWS, ROW_VALUES, _str::s, str_init, TABLENAME_COLUMN, db_func::use_table, VAL_INT, VAL_NULL, VAL_STR, VAL_TYPE, version, VERSION_COLUMN, VERSION_TABLE, and ZSW.

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

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

Stores the name of a table.

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

Parameters:

	_h	database connection handle
	_t	stored name

Returns:

0 if everything is ok, otherwise returns value < 0

Definition at line 419 of file db/db.c.

References CON_TABLE, LM_ERR, and _str::s.

Referenced by bdb_use_table(), db_mysql_use_table(), db_oracle_use_table(), db_postgres_use_table(), db_unixodbc_use_table(), and dbt_use_table().