db-api.txt

用来作为linux中SIP SERVER,完成VOIP网络电话中服务器的功能

Use this macro if you need to obtain the number of rows in the result

Example: int n = RES_ROW_N(res);


1.7 Type db_op_t

1.7.1 Description

This type represents an expression operator. In fact, this type is 
identical to const char*.

1.7.2 Definition
   
   typedef const char* db_op_t;

1.7.3 Macros

There are no macros (It is not needed).


2 Functions

There are several functions that implement the database API logic. All function
names start with db_ prefix, except bind_dbmod. bind_dbmod function is 
implemented in db.c file, all other functions are implemented in a standalone 
database module. You will need to compile and link db.c in your module to be 
able to use the bind_dbmod function. Detailed function description follows.


2.1 Function bind_dbmod

2.1.1 Description

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__ !

2.1.2 Prototype

   int bind_dbmod(char* db_url, db_func_t* dbf);

2.1.3 Parameters

The function takes two parameters, the first parameter must contain a database 
connection URL or a database module name. The db_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":
The second parameter will be filled by this function with the corresponding
 database module callbacks (see the db_func_t structure definition in
  db.h and the callbacks definitions below).


2.1.4 Return Value

The function returns 0 if it was able to find the addresses of all the 
corresponding module database functions and a value < 0 otherwise.


2.2 Callback dbf.init

2.2.1 Description

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.

2.2.2 Prototype

   db_con_t* (*db_init_f)(const char* _sql_url);

2.2.3 Parameters

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:     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 
          name of the database (optional).


2.2.4 Return Value

The function returns pointer to db_con_t* representing the connection if it was
successful, otherwise 0 is returned.


2.3 Callback dbf.close

2.3.1 Description

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


2.3.2 Prototype

   void (*db_close_f)(db_con_t* _h);

2.3.3 Parameters

The function takes one parameter, this parameter is a pointer to db_con_t
structure representing database connection that should be closed.

2.3.4 Return Value

Function doesn't return anything.


2.4 Callback dbf.query

2.4.1 Description

This function implements SELECT SQL directive.

2.4.2 Prototype

   int (*db_query_f)(db_con_t* _h, db_key_t* _k, db_op_t* _op,
                db_val_t* _v, db_key_t* _c, 
	        int _n, int _nc, db_key_t _o, db_res_t** _r);

2.4.3 Parameters

The function takes 7 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
_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 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.

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 !

2.4.4 Return Value

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


2.5 Callback dbf.free_result

2.5.1 Description

This function frees all memory allocated previously in db_query, it is
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 !

2.5.2 Prototype

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

2.5.3 Parameters

The function takes 2 parameters:
_h: Database connection handle
_r: Pointer to db_res_t structure to destroy

2.5.4 Return Value

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


2.6 Callback dbf.insert

2.6.1 Description

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

2.6.2 Prototype

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

2.6.3 Parameters

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

2.6.4 Return Value

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


2.7 Callback dbf.delete

2.7.1 Description

This function implements DELETE SQL directive, it is possible to delete one or
more rows from a table.

2.7.2 Prototype

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

2.7.3 Parameters

The function takes 4 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

If _k is NULL and _v is NULL and _n is zero, all rows are deleted (table will
be empty).

If _o is NULL, equal operator (=) will be used everywhere.

2.7.4 Return Value

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


2.8 Callback dbf.update

2.8.1 Description

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

2.8.2 Prototype

   int (*db_update_f)(db_con_t* _h, db_key_t* _k, db_op_t* _o, db_val_t* _v,
	         db_key_t* _uk, db_val_t* _uv, int _n, int _un);

2.8.3 Parameters

The function takes 7 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 

2.8.4 Return Value

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


2.9 Callback dbf.use_table

2.9.1 Description

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.

2.9.2 Prototype

   int (*db_use_table_f)(db_con_t* _h, const char* _t);

2.9.3 Parameters

The function takes 2 parameters:
_h: Database connection handle
_t: Table name

2.9.4 Return Value

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