Google

NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.77">

3.3. Connection Infrastructure

3.3.1. dbi_conn_new

dbi_conn dbi_conn_new(const char *name)

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

Arguments

name: The name of the desired driver.

Returns

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

3.3.2. dbi_conn_open

dbi_conn dbi_conn_open(dbi_driver Driver)

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

Arguments

Driver: The target driver.

Returns

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

3.3.3. dbi_conn_get_driver

dbi_driver dbi_conn_get_driver(dbi_conn Conn)

Returns the driver type of the specified connection.

Arguments

Conn: The target connection.

Returns

The driver type of the target connection.

3.3.4. dbi_conn_set_option

int dbi_conn_set_option(dbi_conn Conn, const char *key, char *value)

Sets a specified connection option to a string value.

Arguments

Conn: The target connection.

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_conn_set_option_numeric

int dbi_conn_set_option_numeric(dbi_conn Conn, const char *key, int value)

Sets a specified connection option to a numeric value.

Arguments

Conn: The target connection.

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_conn_get_option

const char *dbi_conn_get_option(dbi_conn Conn, const char *key)

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

Arguments

Conn: The target connection.

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_conn_get_option_numeric

int dbi_conn_get_option_numeric(dbi_conn Conn, const char *key)

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

Arguments

Conn: The target connection.

key: The name of the target setting.

Returns

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

3.3.8. dbi_conn_get_option_list

const char *dbi_conn_get_option_list(dbi_conn Conn, const char *current)

Enumerates the list of available options for a connection. 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

Conn: The target connection.

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_conn_clear_option

void dbi_conn_clear_option(dbi_conn Conn, const char *key)

Removes the target option setting from a connection.

Arguments

Conn: The target connection.

key: The name of the target setting.

3.3.10. dbi_conn_clear_options

void dbi_conn_clear_options(dbi_conn Conn)

Removes all option settings from a connection.

Arguments

Conn: The target connection.

3.3.11. dbi_conn_get_socket

int dbi_conn_get_socket(dbi_conn Conn)

Obtain the file descriptor number for the backend connection socket.

Arguments

Conn: The target connection

Returns

-1 on failure, the file descriptor number on success

3.3.12. dbi_conn_close

void dbi_conn_close(dbi_conn Conn)

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

Arguments

Conn: The target connection.

3.3.13. Error Handling

3.3.13.1. dbi_conn_error

int dbi_conn_error(dbi_conn Conn, const char **errmsg_dest)

Returns a formatted message with the error number and description resulting from the previous database operation.

Arguments

Conn: The target connection.

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. This string is managed by libdbi, so it must not be modified or freed.

Returns

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

3.3.13.2. dbi_conn_error_handler

void dbi_conn_error_handler(dbi_conn Conn, dbi_conn_error_handler_func 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 (and return nothing):

  • dbi_conn Conn: the connection object that triggered the error, from which dbi_conn_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

Conn: The target connection.

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.