Database Independent Abstraction Layer for C: libdbi Driver Author's Guide
Prev | Chapter 3. Driver Functions | Next

# 3.4. DBD Helper Functions

libdbi implements a couple of functions which come in handy when implementing database engine drivers. Call them from your driver code if appropriate.

## 3.4.1. _dbd_result_create

``dbi_result_t *_dbd_result_create`(dbi_conn_t *conn, void *handle, unsigned long long numrows_matched, unsigned long long numrows_affected);`

Allocates a new dbi_result_t, filling the number of rows matched and affected, storing the database-specific result handle, and allocating room for rows to be stored.

Arguments

  `conn`: The target connection.

  `handle`: The database-specific result handle used internally by the driver.

  `numrows_matched`: The number of rows matched by the query.

  `numrows_affected`: The number of rows affected by the query.

Returns

  A new DBI result object.

## 3.4.2. _dbd_result_set_numfields

``void _dbd_result_set_numfields`(dbi_result_t *result, unsigned int numfields);`

Sets a result's number of fields and allocates memory for field information to be stored.

Arguments

  `result`: The target result.

  `numfields`: The number of fields in the result set.

## 3.4.3. _dbd_result_add_field

``void _dbd_result_add_field`(dbi_result_t *result, unsigned int idx, char *name, unsigned short type, unsigned int attribs);`

Stores information about the target field into the result set.

Arguments

  `result`: The target result.

  `idx`: The numeric field index.

  `name`: The name of the field.

  `type`: The datatype of the field.

  `attribs`: The attributes of the field.

## 3.4.4. _dbd_row_allocate

``dbi_row_t *_dbd_row_allocate`(unsigned int numfields);`

Allocates a new row, ready to be filled with data.

Arguments

  `numfields`: The number of fields in the result set.

Returns

  A new DBI row, or NULL on error.

## 3.4.5. _dbd_row_finalize

``void _dbd_row_finalize`(dbi_result_t *result, dbi_row_t *row, unsigned long long rowidx);`

Associates and stores the row with the result set, once the row's data has been filled.

Arguments

  `result`: The target result set.

  `row`: The target row object.

  `rowidx`: The index of the row.

## 3.4.6. _dbd_internal_error_handler

``void _dbd_internal_error_handler`(dbi_conn_t *conn, const char *errmsg, const int errno);`

Saves error message information. libdbi makes this information available to the software to check the error status after each call to a libdbi API function. If an old error message string exists, it will be freed.

Arguments

  `conn`: The target connection.

  `errmsg`: The error message to store. This will be stdup'd by libdbi so it has its own copy. If NULL, libdbi will attempt to provide an appropriate message string.

  `errno`: The error number to store. Use only the predefined (in `include/dbi/dbi.h`) constants DBI_ERROR_*. If the error number is DBI_ERROR_DBD, libdbi will replace the error number and message by calling the driver function `dbd_geterror` which retrieves the error code and message from the database client library. If errmsg is NULL and errno is any other of the predefined constants, libdbi will provide its own message string.

## 3.4.7. _dbd_result_create_from_stringarray

``dbi_result_t *_dbd_result_create_from_stringarray`(dbi_conn_t *conn, unsigned long long numrows_matched, const char **stringarray);`

Creates a result object from an array of strings which contains the data of a single field for each row.

Arguments

  `conn`: The target connection.

  `numrows_matched`: The number of rows contained in the `stringarray`.

  `stringarray`: A pointer to an array of strings with `numrows_matched` members.

Returns

  A result object, or NULL if there is an error.

## 3.4.8. _dbd_register_driver_cap

``void _dbd_register_driver_cap`(dbi_driver_t *driver, const char *capname, int value);`

Adds a key-value pair to the list of driver capabilities.

Arguments

  `driver`: The target driver.

  `capname`: The key.

  `value`: The value.

## 3.4.9. _dbd_register_conn_cap

``void _dbd_register_conn_cap`(dbi_conn_t *conn, const char *capname, int value);`

Adds a key-value pair to the list of connection capabilities.

Arguments

  `conn`: The target connection.

  `capname`: The key.

  `value`: The value.

## 3.4.10. _dbd_parse_datetime

``time_t _dbd_parse_datetime`(const char *raw, unsigned int attribs);`

Parses the input time, date, or datetime string and converts the value into a time_t value.

Arguments

  `raw`: A zero-terminated string containing a time, date, or datetime value. Accepted formats are YYYY-MM-DD for date values, HH:MM:SS for time values, and YYYY-MM-DD HH:MM:SS for datetime values. The separators must be present, but can be any character.

  `attribs`: The field attributes of raw.

Returns

  The numeric equivalent of the input based on UTC. In case of an error, this function returns the start of the Unix epoch.

## 3.4.11. _dbd_escape_chars

``size_t _dbd_escape_chars`(char *dest, const char *orig, size_t orig_size, const char *toescape);`

Escapes the characters contained in `toescape` in the string `orig` and puts the result into the allocated memory pointed to by `dest`. The size of `dest` must be at least (`orig_size`*2)+5. The characters are escaped by preceding them with a backslash.

Arguments

  `dest`: Pointer to allocated memory which will receive the escaped string.

  `orig`: The string to escape.

  `orig_size`: The length of the string to escape.

  `toescape`: A string containing all characters that need escaping.

Returns

  The length, in bytes, of the escaped string.

## 3.4.12. _dbd_encode_binary

``size_t _dbd_encode_binary`(const unsigned char *in, size_t n, unsigned char *out);`

Encodes a binary string as a zero-terminated string which can be safely included in a SQL query. Use _dbd_decode_binary to decode the string again.

Arguments

  `in`: Pointer to the binary string.

  `n`: Length, in bytes, of the binary string `in`.

  `out`: Pointer to allocated memory which will receive the escaped string. The size must be at least 2 +(257*`n`)/254 bytes.

Returns

  The length, in bytes, of the escaped string.

## 3.4.13. _dbd_decode_binary

``size_t _dbd_decode_binary`(const unsigned char *in, unsigned char *out);`

Decodes a zero-terminated string with escaped characters as created by _dbd_encode_binary.

Arguments

  `in`: Pointer to the input string.

  `out`: Pointer to allocated memory which will receive the unescaped string. The output string is always shorter than the input string, i.e. if the size of `out` is the same as the size of `in`, you're on the safe side. The implementation allows to decode the string in place, i.e. `out` may be the same as `in`.

Returns

  The length, in bytes, of the unescaped binary string.

Prev | Home | Next
Public Database Query Functions | Up | GNU Free Documentation License