3.3. Driver Infrastructure

3.3.1. dbi_driver_new

dbi_driver dbi_driver_new(const char *name)

Creates a driver instance of the plugin specified by "name". This is a shortcut for calling dbi_plugin_open() and passing the result to dbi_driver_open().

Arguments

name: The name of the desired plugin.

Returns

A driver instance of the specified plugin, or NULL if there was an error.

3.3.2. dbi_driver_open

dbi_driver dbi_driver_open(dbi_plugin Plugin)

Creates a driver instance of the specified plugin. This driver can be used to perform queries and set options.

Arguments

Plugin: The target plugin.

Returns

A driver instance of the specified plugin, or NULL if there was an error.

3.3.3. dbi_driver_get_plugin

dbi_plugin dbi_driver_get_plugin(dbi_driver Driver)

Returns the plugin type of the specified driver.

Arguments

Driver: The target driver.

Returns

The plugin type of the target driver.

3.3.4. dbi_driver_set_option

int dbi_driver_set_option(dbi_driver Driver, const char *key, char *value)

Sets a specified driver option to a string value.

Arguments

Driver: The target driver.

key: The name of the target setting. Must only contain alphanumerics and the underscore character.

value: The string value of the target setting.

Returns

-1 on error, 0 on success.

3.3.5. dbi_driver_set_option_numeric

int dbi_driver_set_option_numeric(dbi_driver Driver, const char *key, int value)

Sets a specified driver option to a numeric value.

Arguments

Driver: The target driver.

key: The name of the target setting. Must only contain alphanumerics and the underscore character.

value: The numeric value of the target setting.

Returns

-1 on error, 0 on success.

3.3.6. dbi_driver_get_option

const char *dbi_driver_get_option(dbi_driver Driver, const char *key)

Retrieves the string value of the specified option set for a driver.

Arguments

Driver: The target driver.

key: The name of the target setting.

Returns

A read-only string with the setting, or NULL if it is not available.

3.3.7. dbi_driver_get_option_numeric

int dbi_driver_get_option_numeric(dbi_driver Driver, const char *key)

Retrieves the integer value of the specified option set for a driver.

Arguments

Driver: The target driver.

key: The name of the target setting.

Returns

The value of the setting, or -1 if it is not available.

3.3.8. dbi_driver_get_option_list

const char *dbi_driver_get_option_list(dbi_driver Driver, const char *current)

Enumerates the list of available options for a driver. If current is NULL, the first available option will be returned. If current is a valid option name, the next available option will be returned.

Arguments

Driver: The target driver.

current: The key name of the target option.

Returns

The key name of the next option, or NULL if there was an error or there are no more options.

3.3.9. dbi_driver_clear_option

void dbi_driver_clear_option(dbi_driver Driver, const char *key)

Removes the target option setting from a driver.

Arguments

Driver: The target driver.

key: The name of the target setting.

3.3.10. dbi_driver_clear_options

void dbi_driver_clear_options(dbi_driver Driver)

Removes all option settings from a driver.

Arguments

Driver: The target driver.

3.3.11. dbi_driver_close

void dbi_driver_close(dbi_driver Driver)

Disconnects the specified driver connection from the database and cleans up the driver session.

Arguments

Driver: The target driver.

3.3.12. Error Handling

3.3.12.1. dbi_driver_error

int dbi_driver_error(dbi_driver Driver, char **errmsg_dest)

Generates a formatted message with the error number and description resulting from the previous database operation, copying the message into the specified string.

Arguments

Driver: The target driver.

errmsg_dest: The target string pointer, which will point to the error message. If NULL, no error message will be created, but the error number will still be returned.

Returns

The error number of the most recent database operation if it resulted in an error. If not, this will return -1.

3.3.12.2. dbi_driver_error_handler

void dbi_driver_error_handler(dbi_driver Driver, void *function, void *user_argument)

Registers an error handler callback to be triggered whenever the database encounters an error. The callback function should perform as little work as possible, since the state in which it is called can be uncertain. The actual function declaration must accept two parameters:

  • dbi_driver_t *driver: a pointer to the driver that triggered the error, from which dbi_error() can be called, and

  • void *user_argument: a pointer to whatever data (if any) was registered along with the handler.

To remove the error handler callback, specify NULL as the function and user_argument.

Arguments

Driver: The target driver.

function: A pointer to the function to call when the error handler should be triggered.

user_argument: Any data to pass along to the function when it is triggered. Set to NULL if unused.