Database Independent Abstraction Layer for C: libdbi Programmer's Guide | ||
---|---|---|
Prev | Chapter 3. libdbi API Reference | Next |
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().
name: The name of the desired plugin.
A driver instance of the specified plugin, or NULL if there was an error.
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.
Plugin: The target plugin.
A driver instance of the specified plugin, or NULL if there was an error.
dbi_plugin dbi_driver_get_plugin(dbi_driver Driver) |
Returns the plugin type of the specified driver.
Driver: The target driver.
The plugin type of the target driver.
int dbi_driver_set_option(dbi_driver Driver, const char *key, char *value) |
Sets a specified driver option to a string value.
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.
-1 on error, 0 on success.
int dbi_driver_set_option_numeric(dbi_driver Driver, const char *key, int value) |
Sets a specified driver option to a numeric value.
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.
-1 on error, 0 on success.
const char *dbi_driver_get_option(dbi_driver Driver, const char *key) |
Retrieves the string value of the specified option set for a driver.
Driver: The target driver.
key: The name of the target setting.
A read-only string with the setting, or NULL if it is not available.
int dbi_driver_get_option_numeric(dbi_driver Driver, const char *key) |
Retrieves the integer value of the specified option set for a driver.
Driver: The target driver.
key: The name of the target setting.
The value of the setting, or -1 if it is not available.
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.
Driver: The target driver.
current: The key name of the target option.
The key name of the next option, or NULL if there was an error or there are no more options.
void dbi_driver_clear_option(dbi_driver Driver, const char *key) |
Removes the target option setting from a driver.
Driver: The target driver.
key: The name of the target setting.
void dbi_driver_clear_options(dbi_driver Driver) |
Removes all option settings from a driver.
Driver: The target driver.
void dbi_driver_close(dbi_driver Driver) |
Disconnects the specified driver connection from the database and cleans up the driver session.
Driver: The target driver.
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.
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.
The error number of the most recent database operation if it resulted in an error. If not, this will return -1.
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.
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.