Connection Infrastructure

Database Independent Abstraction Layer for C: libdbi Programmer's Guide (OUTDATED SEE README!)
Prev | Chapter 3. libdbi API Reference | Next

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

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