opensips-1.6.4-2-notls_src.tar.gz

# $Id: db-api.txt 5903 2009-07-21 08:49:04Z bogdan_iancu $ # 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);