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

# 7.2. Driver Infrastructure

## 7.2.1. dbi_driver_list_r

``dbi_driver dbi_driver_list_r`(dbi_driver Current, dbi_inst Inst);`

Enumerates all loaded drivers of the given instance. If Current is NULL, the first available driver will be returned. If Current is a valid driver, the next available driver will be returned.

Arguments

  `Current`: The current driver in the list of drivers, or NULL to retrieve the first one.

  `Inst`: The instance handle.

Returns

  The next available driver, or NULL if there is an error or no more are available.

Availability

  0.9.0

## 7.2.2. dbi_driver_list

``dbi_driver dbi_driver_list`(dbi_driver Current);`

Enumerates all loaded drivers. If Current is NULL, the first available driver will be returned. If Current is a valid driver, the next available driver will be returned.

> Note: This function is deprecated. Use dbi_driver_list_r instead.

Arguments

  `Current`: The current driver in the list of drivers, or NULL to retrieve the first one.

Returns

  The next available driver, or NULL if there is an error or no more are available.

## 7.2.3. dbi_driver_open_r

``dbi_driver dbi_driver_open_r`(const char *name, dbi_inst Inst);`

Locate the driver with the specified name.

Arguments

  `name`: The name of the driver to open.

  `Inst`: The instance handle.

Returns

  The requested driver, or NULL if there is no such driver.

Availability

  0.9.0

## 7.2.4. dbi_driver_open

``dbi_driver dbi_driver_open`(const char *name);`

Locate the driver with the specified name.

> Note: This function is deprecated. Use dbi_driver_open_r instead.

Arguments

  `name`: The name of the driver to open.

Returns

  The requested driver, or NULL if there is no such driver.

## 7.2.5. dbi_driver_get_instance

``int dbi_driver_get_instance`(dbi_driver Driver);`

Retrieves the handle of the instance that loaded the driver.

Arguments

  `Driver`: The target driver.

Returns

  The instance handle, or NULL in case of an error.

Availability

  0.9.0

## 7.2.6. dbi_driver_is_reserved_word

``int dbi_driver_is_reserved_word`(dbi_driver Driver, const char *word);`

Looks for the specified word in the list of reserved words. The result of this function may vary between databases. Case does not matter.

Arguments

  `Driver`: The target driver.

  `word`: The word to check against the reserved word list.

Returns

  -1 if an error occurs, 0 if the word is not reserved, 1 otherwise.

## 7.2.7. dbi_driver_specific_function

``void *dbi_driver_specific_function`(dbi_driver Driver, const char *name);`

Returns a function pointer to the specifed custom function. This can be used to access database-specific functionality, but it will restrict your code to one particular database, lessening the benefits of using libdbi.

Arguments

  `Driver`: The target driver.

  `name`: The name of the custom function.

Returns

  If the custom function is found, a pointer to that function. If not, returns NULL.

Availability

  0.9.0

## 7.2.8. dbi_driver_quote_string

``int dbi_driver_quote_string`(dbi_driver Driver, char **orig);`

Encloses the target string in the types of quotes that the database expects, and escapes any special characters. The original string will be freed and `orig` will point to a newly allocated one (which you still must free on your own). If an error occurs, the original string will not be freed.

> Note: This function is deprecated. Use dbi_conn_quote_string instead.

Arguments

  `Driver`: The target driver.

  `orig`: A pointer to the string to quote and escape.

Returns

  The new string's length in bytes, excluding the terminating zero byte, or 0 in case of an error. The length of a quoted empty string is 2 bytes.

## 7.2.9. dbi_driver_quote_string_copy

``int dbi_driver_quote_string_copy`(dbi_driver Driver, char **orig, char **newstr);`

Encloses the target string in the types of quotes that the database expects, and escapes any special characters. The original string will be left alone, and `newstr` will point to a newly allocated string containing the quoted string (which you still must free on your own). In case of an error, `newstr` is an invalid pointer which you must not attempt to deallocate.

> Note: This function is deprecated. Use dbi_conn_quote_string_copy instead.

Arguments

  `Driver`: The target driver.

  `orig`: A pointer to the string to quote and escape.

  `newstr`: After the function returns, this pointer will point to the quoted and escaped string.

Returns

  The quoted string's length in bytes, excluding the terminating zero byte, or 0 in case of an error. The length of a quoted empty string is 2 bytes.

## 7.2.10. dbi_driver_encoding_from_iana

``const char *dbi_driver_encoding_from_iana`(dbi_driver Driver, const char *iana_encoding);`

Requests the database engine specific name of the character encoding identified by its name as known to IANA. Use this function to pass the database engine specific encoding name to SQL queries , e.g. as part of a CREATE DATABASE command.

Arguments

  `Driver`: The target driver.

  `iana_encoding`: The IANA name of the character encoding.

Returns

  A string containing the database engine specific encoding name. If the encoding name cannot be translated, the IANA name is returned without translation.

Availability

  0.8.0

## 7.2.11. dbi_driver_encoding_to_iana

``const char *dbi_driver_encoding_to_iana`(dbi_driver Driver, const char *db_encoding);`

Requests the IANA name of the character encoding identified by its database engine specific name. Use this function to convert the database engine specific name returned by SQL queries to the corresponding common name.

Arguments

  `Driver`: The target driver.

  `db_encoding`: The database engine specific name of the character encoding.

Returns

  A string containing the IANA encoding name. If the encoding name cannot be translated, the database engine specific name is returned without translation.

Availability

  0.8.0

## 7.2.12. Driver Information

### 7.2.12.1. dbi_driver_get_name

``const char *dbi_driver_get_name`(dbi_driver Driver);`

Requests the name of the specified driver. The calling program must not attempt to free the returned string.

Arguments

  `Driver`: The target driver.

Returns

  A string containing the driver's name.

### 7.2.12.2. dbi_driver_get_filename

``const char *dbi_driver_get_filename`(dbi_driver Driver);`

Requests the filename of the specified driver. The calling program must not attempt to free the returned string.

Arguments

  `Driver`: The target driver.

Returns

  A string containing the driver's full path and file name.

### 7.2.12.3. dbi_driver_get_description

``const char *dbi_driver_get_description`(dbi_driver Driver);`

Requests a description of the specified driver. The calling program must not attempt to free the returned string.

Arguments

  `Driver`: The target driver.

Returns

  A string containing the driver's description. It will be one or two short sentences with no newlines.

### 7.2.12.4. dbi_driver_get_maintainer

``const char *dbi_driver_get_maintainer`(dbi_driver Driver);`

Requests the maintainer of the specified driver. The calling program must not attempt to free the returned string.

Arguments

  `Driver`: The target driver.

Returns

  A string containing the driver maintainer's full name and email address.

### 7.2.12.5. dbi_driver_get_url

``const char *dbi_driver_get_url`(dbi_driver Driver);`

Requests the maintainer's URL for the specified driver. This is useful for drivers maintained by a third party. The calling program must not attempt to free the returned string.

Arguments

  `Driver`: The target driver.

### 7.2.12.6. dbi_driver_get_version

``const char *dbi_driver_get_version`(dbi_driver Driver);`

Requests the version of the specified driver. The calling program must not attempt to free the returned string.

Arguments

  `Driver`: The target driver.

Returns

  A string containing the driver's version.

### 7.2.12.7. dbi_driver_get_date_compiled

``const char *dbi_driver_get_date_compiled`(dbi_driver Driver);`

Requests the compilation date of the specified driver. The calling program must not attempt to free the returned string.

Arguments

  `Driver`: The target driver.

Returns

  A string containing the date the driver was compiled.

### 7.2.12.8. dbi_driver_cap_get

``int dbi_driver_cap_get`(dbi_driver Driver, const char *capname);`

Requests the value of the driver capability which is specified as an argument.

Arguments

  `Driver`: The target driver.

  `capname`: A pointer to a string containing the name of the driver capability to be queried.

Returns

  The numeric value of the driver capability.

Prev | Home | Next
Instance Infrastructure | Up | Connection Infrastructure