Driver Infrastructure

Database Independent Abstraction Layer for C: libdbi Programmer's Guide
Prev | Chapter 3. libdbi API Reference | Next

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

Prev | Home | Next
Plugin Infrastructure | Up | SQL and Database Infrastructure