| Database Independent Abstraction Layer for C: libdbi Driver Author's Guide | ||
|---|---|---|
| Prev | Chapter 3. Driver Functions | Next |
libdbi implements a couple of functions which come in handy when implementing database engine drivers. Call them from your driver code if appropriate.
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.
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.
A new DBI result object.
Sets a result's number of fields and allocates memory for field information to be stored.
result: The target result.
numfields: The number of fields in the result set.
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.
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.
Allocates a new row, ready to be filled with data.
numfields: The number of fields in the result set.
A new DBI row, or NULL on error.
Associates and stores the row with the result set, once the row's data has been filled.
result: The target result set.
row: The target row object.
rowidx: The index of the row.
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.
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.
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.
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.
A result object, or NULL if there is an error.
Adds a key-value pair to the list of driver capabilities.
driver: The target driver.
capname: The key.
value: The value.
Adds a key-value pair to the list of connection capabilities.
conn: The target connection.
capname: The key.
value: The value.
Parses the input time, date, or datetime string and converts the value into a time_t value.
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.
The numeric equivalent of the input based on UTC. In case of an error, this function returns the start of the Unix epoch.
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.
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.
The length, in bytes, of the escaped string.
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.
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.
The length, in bytes, of the escaped string.
Decodes a zero-terminated string with escaped characters as created by _dbd_encode_binary.
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.
The length, in bytes, of the unescaped binary string.