db-api.txt

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

# $Id: db-api.txt,v 1.10 2004/08/04 14:26:25 janakj Exp $
# 
# History:
# --------
#  2004-06-06  updated (bind_dbmod and obsoleted db_* macros)  (andrei)

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 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.


1 Data types

There are several new data types. All of them are defined in header file db.h,
a client must include the header file to be able to use them.

1.1 Type db_con_t

1.1.1 Description

This type represents a database connection, all database functions (described 
below) use a variable of this type as one argument. In other words, variable 
of db_con_t type serves as a handle for a particular database connection.

1.1.2 Definition

   typedef struct db_con {
        char* table;     /* Default table to use */
        void* con;       /* Database connection */
        void* res;       /* Result of previous operation */
        void* row;       /* Internal, not for public use */
        int connected;   /* 1 if connection is established */
   } db_con_t;

1.1.3 Macros

There are no macros for db_con_t type.


1.2 Type db_key_t

1.2.1 Description

This type represents a database key. Every time you need to specify a key 
value, this type should be used. In fact, this type is identical to const 
char*.

1.2.2 Definition
   
   typedef const char* db_key_t;

1.2.3 Macros

There are no macros (It is not needed).


1.3 Type db_type_t

1.3.1 Description

Each cell in a database table can be of a different type. To distinguish
among these types, the db_type_t enumeration is used. Every value of the
enumeration represents one datatype that is recognized by the database
API. This enumeration is used in conjunction with db_type_t. For more
information, see the next section.

1.3.2 Definition

   typedef enum {
       DB_INT,       /* Integer number */
       DB_DOUBLE,    /* Decimal number */
       DB_STRING,    /* String */
       DB_STR,       /* str structure */
       DB_DATETIME   /* Date and time */
       DB_BLOB       /* Binary large object */
       DB_BITMAP     /* Bitmap, one-dimensional array of flags */
   } db_type_t;

1.3.3 Macros

There are no macros.


1.4 Type db_val_t

1.4.1 Description

This structure represents a value in the database. Several datatypes are
recognized and converted by the database API:

DB_INT      - Value in the database represents an integer number
DB_DOUBLE   - Value in the database represents a decimal number
DB_STRING   - Value in the database represents a string
DB_STR      - Value in the database represents a string
DB_DATETIME - Value in the database represents date and time
DB_BLOB     - Value in the database represents binary large object
DB_BITMAP   - Value in the database represents an array of flags

These datatypes are automaticaly recognized, converted from internal database
representation and stored in the variable of corresponding type.

1.4.2 Definition

    typedef struct db_val {
         db_type_t type;              /* Type of the value */
         int nul;                     /* NULL flag */
         union {                      
             int int_val;             /* Integer value */
             double double_val;       /* Double value */
             time_t time_val;         /* Unix time_t value */
             const char* string_val;  /* Zero terminated string */
	     str str_val;             /* str structure */
             str blob_val;            /* Structure describing blob */
             unsigned int bitmap_val; /* Array of flags */
         } val;
    } db_val_t;

1.4.3 Macros

Note: All macros expect reference to db_val_t variable as the parameter.

1.4.3.1 VAL_TYPE(value) Macro

Use this macro if you need to set/get the type of the value

Example: VAL_TYPE(val) = DB_INT;
         if (VAL_TYPE(val) == DB_FLOAT) ...

1.4.3.2 VAL_NULL(value) Macro

Use this macro if you need to set/get the null flag. Non-zero flag means that 
the corresponding cell in the database contained no data (NULL value in MySQL
terminology).

Example: if (VAL_NULL(val) == 1) {
             printf("The cell is NULL");
         }

1.4.3.3 VAL_INT(value) Macro

Use this macro if you need to access integer value in the db_val_t structure.

Example: if (VAL_TYPE(val) == DB_INT) {
             printf("%d", VAL_INT(val));
         }

1.4.3.4 VAL_DOUBLE(value) Macro 

Use this macro if you need to access double value in the db_val_t structure.

Example: if (VAL_TYPE(val) == DB_DOUBLE) {
             printf("%f", VAL_DOUBLE(val));
         }

1.4.3.5 VAL_TIME(value) Macro 

Use this macro if you need to access time_t value in the db_val_t structure.

Example: time_t tim;
         if (VAL_TYPE(val) == DB_DATETIME) {
             tim = VAL_TIME(val);
         }

1.4.3.6 VAL_STRING(value) Macro 

Use this macro if you need to access string value in the db_val_t structure.

Example: if (VAL_TYPE(val) == DB_STRING) {
             printf("%s", VAL_STRING(val));
         }

1.4.3.7 VAL_STR(value) Macro

Use this macro if you need to access str structure in the db_val_t structure.

Example: if (VAL_TYPE(val) == DB_STR) {
             printf("%.*s", VAL_STR(val).len, VAL_STR(val).s);
         }

1.4.3.8 VAL_BLOB(value) Macro

Use this macro if you need to access blob value in the db_val_t structure.

Example: if (VAL_TYPE(val) == DB_BLOB) {
	     printf("%.*s", VAL_BLOB(val).len, VAL_BLOB(val).s);
         }

1.4.3.9 VAL_BITMAP(value) Macro

Use this macro if you need to access bitmap value in the db_val_t structure.

Example: if (VAL_TYPE(val) == DB_BITMAP) {
	    printf("%d", VAL_BITMAP(val));
	 }

1.5 Type db_row_t

1.5.1 Description

This type represents one row in a database table. In other words, the row is an
array of db_val_t variables, where each db_val_t variable represents exactly 
one cell in the table.

1.5.2 Definition

   typedef struct db_row {
       db_val_t* values;    /* Array of values in the row */
       int n;               /* Number of values in the row */
   } db_val_t;

1.5.3 Macros

1.5.3.1 ROW_VALUES(row) Macro 

Use this macro to get pointer to the array of db_val_t structures.

Example: db_val_t* v = ROW_VALUES(row);
         if (VAL_TYPE(v) == DB_INT) ....

1.5.3.2 ROW_N(row) Macro 

Use this macro to get number of cells in the row.

Example: db_val_t* val = ROW_VALUES(row);
         for(i = 0; i < ROW_N(row); i++) {
             switch(VAL_TYPE(val + i)) {
             case DB_INT: ...; break;
             case DB_DOUBLE: ...; break;
             ...
             }
         }


1.6 Type db_res_t

1.6.1 Description

This type represents a result returned by db_query function (see below). The 
result can consist of zero or more rows (see db_row_t description).

Note: A variable of type db_res_t returned by db_query function uses dynamicaly
      allocated memory, don't forget to call db_free_result if you don't need 
      the variable anymore. You will encounter memory leaks if you fail to do 
      this !

In addition to zero or more rows, each db_res_t object contains also an array 
of db_key_t objects. The objects represent keys (names of columns).

1.6.2 Definition

   typedef struct db_res {
       struct {
           db_key_t* keys;    /* Array of column names */
           db_type_t* types;  /* Array of column types */
           int n;             /* Number of columns */
       } col;
       struct db_row* rows;   /* Array of rows */
       int n;                 /* Number of rows */
   } db_res_t;

1.6.3 Macros

1.6.3.1 RES_NAMES(res) Macro 

Use this macro if you want to obtain pointer to the array of cell names.

Example: db_key_t* column_names = ROW_NAMES(row);

1.6.3.2 RES_COL_N(res) Macro 

Use this macro if you want to get the number of columns in the result.

Example: int ncol = RES_COL_N(res)
         for(i = 0; i < ncol; i++) {
             /* do something with the column */
         }

1.6.3.3 RES_ROWS(res) Macro 

Use this macro if you need to obtain pointer to array of rows.

Example: db_row_t* rows = RES_ROWS(res);
 
1.6.3.4 RES_ROW_N(res) Macro