SIP Express Router v0.8.8 - Developer's Guide
<<< PreviousNext >>>

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

Note

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.

Data types

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

Type db_con_t

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. 

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;

There are no macros defined for db_con_t type.

Type db_key_t

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

		    typedef const char* db_key_t;

There are no macros defined (they are not needed).

Type db_type_t

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. 

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_type_t;

There are no macros defined.

Type db_val_t

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

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

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 */
    } val;
} db_val_t;

Note

All macros expect pinter to db_val_t variable as a parameter.

Type db_row_t

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. 

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;

Type db_res_t

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 dynamically allocated memory, don't forget to call db_free_query 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). 

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;

<<< PreviousHomeNext >>>
Additional Functions Functions