3.1. Driver Infrastructure Functions

These functions are called by libdbi at startup and when the libdbi user establishes or takes down a database engine connection.

3.1.1. dbd_register_driver

void dbd_register_driver(const dbi_info_t **_driver_info, const char ***_custom_functions, const char ***_reserved_words);

This is the first function called after the driver module is loaded into memory. It passes back meta-information back to libdbi through the pointers passed as arguments.

Arguments

_driver_info: A pointer used to link to the driver's information struct.

_custom_functions: A pointer used to link to the driver's string array of custom database-specific functions.

_reserved_words: A pointer used to link to the driver's string array of reserved words.

3.1.2. dbd_initialize

int dbd_initialize(dbi_driver_t *driver);

Performs any database-specific server initialization. This is called right after dbd_register_driver().

Arguments

driver: The driver's pointer.

Returns

-1 on error, 0 on success. If -1 is returned, the driver will not be added to the list of available drivers.

3.1.3. dbd_connect

int dbd_connect(dbi_conn_t *conn);

Connects to the database, setting the connection's DB-specific connection handle and current database name. Connection parameters are already filled through the connection's option settings. The standard options that all drivers must recognize (if applicable) are: host, port, username, password, dbname, and encoding. Any driver-specific functions must be prefixed with the name of the driver and an underscore, such as "mysql_compression".

Arguments

conn: The target connection instance of the driver.

Returns

<0 on error, 0 on success.

3.1.4. dbd_disconnect

int dbd_disconnect(dbi_conn_t *conn);

Disconnects from the database server.

Arguments

conn: The target connection instance of the driver.

Returns

-1 on error, 0 on success.

3.1.5. dbd_geterror

int dbd_geterror(dbi_conn_t *conn, int *errno, char **errstr);

Retrieves and stores error information, in numeric and/or string format.

Arguments

conn: The target connection.

errno: The int variable to hold the error number.

errstr: The string to hold the error description. The driver is supposed to provide the string as allocated memory which is further managed by libdbi.

Returns

0 if there was an error, 1 if errno was filled, 2 if errstr was filled, 3 if both errno and errstr were filled.

3.1.6. dbd_get_socket

int dbd_get_socket(dbi_conn_t *conn);

Retrieves the socket of the client/server connection used by the database client library, if applicable.

Arguments

conn: The target connection.

Returns

The file descriptor of the socket if successful, -1 if there was an error. Drivers of database engines that do not use sockets should return 0.