Driver Infrastructure Functions

Database Independent Abstraction Layer for C: libdbi Driver Author's Guide
Prev | Chapter 3. Driver Functions | Next

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

Prev | Home | Next
Driver Functions | Up | Internal Database Query Functions