http://libdbi.sourceforge.net'> ]> libdbi Driver Author's Guide David A. Parker Neon Goat Productions

david@neongoat.com

Markus Hoenicka

mhoenicka@users.sourceforge.net

Document revision: $Id: driver-guide.sgml,v 1.1 2005/08/04 21:34:03 mhoenicka Exp $ $Date: 2005/08/04 21:34:03 $ 2001-2005 David Parker, Neon Goat Productions Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in . libdbi implements a database-independent abstraction layer in C, similar to the DBI/DBD layer in Perl. Writing one generic set of code, programmers can leverage the power of multiple databases and multiple simultaneous database connections by using this framework. This guide explains the internal DBD interface for libdbi drivers, and provides a reference for all available driver helper functions.

libdbi provides application developers with a database independent abstraction layer for C. It handles the database-specific implementations for each type of database, so that you can use the same exact code with any type of database server that libdbi supports. You can initiate and use multiple database connections simultaneously, regardless of the types of database servers you are connecting to. The plugin architecture allows for new database drivers to be easily added dynamically by a third party. To aid the development of new database drivers, libdbi ships a template which contains everything you need to get started. Copy the drivers/example directory to your CVS version of the libdbi-drivers project, rename it to the name of your database engine, and replace the string "example" by the name of your database engine in all files in that directory. This should get you pretty far. Check the name of the client library in the Makefile.am and the name of the client library headers in the driver source file. Then have a peek at the existing drivers, and implement the functions in the driver source template accordingly.

In this guide, the terms author and programmer are used interchangably, since the target audience is the software developer writing a driver for libdbi.

libdbi is Copyright © 2001-2005, David Parker and Mark Tobenkin. libdbi is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Please email us with any bugs, ideas, feature requests, or questions. The libdbi website has the latest version of this documentation and the libdbi software, as well as a central database of third-party drivers. &www; David Parker david@neongoat.com Mark Tobenkin mark@brentwoodradio.com Markus Hoenicka mhoenicka@users.sourceforge.net

These functions are called by libdbi at startup and when the libdbi user establishes or takes down a database engine connection.

void dbd_register_driver const dbi_info_t **_driver_info const char ***_custom_functions const char ***_reserved_words This is the first function called after the driver module is loaded into memory. It passes back meta-information back to libdbi through the pointers passed as arguments. Arguments _driver_info: A pointer used to link to the driver's information struct. _custom_functions: A pointer used to link to the driver's string array of custom database-specific functions. _reserved_words: A pointer used to link to the driver's string array of reserved words.

int dbd_initialize dbi_driver_t *driver Performs any database-specific server initialization. This is called right after dbd_register_driver(). Arguments driver: The driver's pointer. Returns -1 on error, 0 on success. If -1 is returned, the driver will not be added to the list of available drivers.

int dbd_connect dbi_conn_t *conn Connects to the database, setting the connection's DB-specific connection handle and current database name. Connection parameters are already filled through the connection's option settings. The standard options that all drivers must recognize (if applicable) are: host, port, username, password, dbname, and encoding. Any driver-specific functions must be prefixed with the name of the driver and an underscore, such as "mysql_compression". Arguments conn: The target connection instance of the driver. Returns <0 on error, 0 on success.

int dbd_disconnect dbi_conn_t *conn Disconnects from the database server. Arguments conn: The target connection instance of the driver. Returns -1 on error, 0 on success.

int dbd_geterror dbi_conn_t *conn int *errno char **errstr Retrieves and stores error information, in numeric and/or string format. Arguments conn: The target connection. errno: The int variable to hold the error number. errstr: The string to hold the error description. Returns 0 if there was an error, 1 if errno was filled, 2 if errstr was filled, 3 if both errno and errstr were filled.

int dbd_get_socket dbi_conn_t *conn Retrieves the socket of the client/server connection used by the database client library, if applicable. Arguments conn: The target connection. Returns The file descriptor of the socket if successful, -1 if there was an error. Drivers of database engines that do not use sockets should return 0.

These functions are called by libdbi when the libdbi user runs queries and accesses their results. There are also a bunch of helper functions that deal with the character encodings as well as with string escaping and quoting.

int dbd_goto_row dbi_result_t *result unsigned long long rowidx Jumps to the specifed row in the result set. Internal row counts start at 0. Arguments result: The target result handle. row: The target row number. Returns 1 on success, 0 on error.

int dbd_fetch_row dbi_result_t *result unsigned long long rowidx Fetches the target row, retrieving one-time field information if necessary. Also see the and helper functions. Arguments result: The target result object. rowidx: The number of the row to fetch. Internal row numbers start at zero. Returns 0 on error, 1 on successful fetch.

int dbd_free_query dbi_result_t *result Frees the target result handle. Arguments result: The target result handle. Returns 0 on success.

const char *dbd_get_encoding dbi_conn_t *conn Returns the character encoding used by the current connection. Arguments conn: The target connection. Returns A zero-terminated string containing the IANA name of the character encoding.

const char *dbd_encoding_to_iana const char *db_encoding Converts the database-engine-specific name of a character encoding to the corresponging IANA name. Arguments db_encoding: A pointer to a string containing the character encoding name. Returns A zero-terminated string containing the IANA name of the character encoding. If there is no equivalent IANA name, the original string will be returned.

const char *dbd_encoding_from_iana const char *iana_encoding Converts the IANA name of a character encoding to the corresponging database-engine-specific name. Arguments iana_encoding: A pointer to a string containing the character encoding name. Returns A zero-terminated string containing the database-engine-specific name of the character encoding. If there is no equivalent IANA name, the original string will be returned.

char *dbd_get_engine_version dbi_conn_t *conn char *versionstring Returns the version string of the database engine that serves the current connection. Arguments conn: The current connection. versionstring: A pointer to a string that can hold at least VERSIONSTRING_LENGTH bytes, including the trailing NULL byte. The function will write the version string to this buffer. Returns versionstring which now contains a zero-terminated string representing the database engine version. This string contains only digits and periods. Returns an empty string in case of an error.

dbi_result_t *dbd_list_dbs dbi_conn_t *conn const char *pattern Performs a query that retrieves the list of databases, with the database name as the first column in the result set. If pattern is non-NULL, only databases whose name match pattern are listed. Arguments conn: The target connection. pattern: A SQL regular expression that limits the search, or NULL to list all tables. Returns A DBI result object, or NULL if an error occurs.

dbi_result_t *dbd_list_tables dbi_conn_t *conn const char *db const char *pattern Performs a query that retrieves the list of tables in the specified database, with the table name as the first column in the result set. If pattern is non-NULL, lists only the tables that match pattern. Arguments conn: The target connection. db: The name of the database where tables should be looked for. pattern: A SQL regular expression that limits the search, or NULL to list all tables. Returns A DBI result object, or NULL if an error occurs.

size_t dbd_quote_string dbi_driver_t *driver const char *orig char *dest Given a string, wrap quotes around that string and escape any characters that the database server needs escaped. The use of this function in user programs is deprecated, but drivers must still implement it at the moment. If the quoting and escaping does not depend on the connection parameters, it is perfectly legal to let your implementation of call this function (it is not possible to do it the other way). libdbi makes sure that both orig and dest are non-NULL before calling this function. Arguments driver: A pointer to the driver itself, which may be useful in weird cases. orig: The string to quote and escape. dest: The destination for the new string, which is already allocated as (strlen(orig)*2)+4+1. In the worst case, each character will need to be escaped, with two quote characters at both the beginning and end of the string, plus one for the terminating NULL. Returns The length of the new string.

size_t dbd_conn_quote_string dbi_conn_t *conn const char *orig char *dest Given a string, wrap quotes around that string and escape any characters that the database server needs escaped. The use of this function in user programs is preferred over . If the quoting and escaping does not depend on the connection parameters, it is perfectly legal to let your implementation of this function call . libdbi makes sure that both orig and dest are non-NULL before calling this function. Arguments conn: A pointer to the current connection. orig: The string to quote and escape. dest: The destination for the new string, which is already allocated as (strlen(orig)*2)+4+1. In the worst case, each character will need to be escaped, with two quote characters at both the beginning and end of the string, plus one for the terminating NULL. Returns The length of the new string.

size_t dbd_quote_binary dbi_conn_t *conn const char *orig size_t from_length char **dest Given a binary string (which may contain NULL bytes and other non-printable characters), wrap quotes around that string and escape any characters that the database server needs escaped. If the function returns an error, *dest is not a valid pointer to a string. Arguments conn: A pointer to the current connection. orig: The string to quote and escape. from_length: The length, in bytes, of the binary string. dest: A pointer to the destination of the new zero-terminated string. The function allocates the required memory as required and updates the pointer that dest points to accordingly. Returns The length of the new string, or DBI_LENGTH_ERROR in case of an error.

dbi_result_t *dbd_query dbi_conn_t *conn const char *statement Performs a query and keeps track of meta-information about the query. Also see the helper function. Arguments conn: The target connection. statement: The zero-terminated query string to execute. Returns A DBI result object, or NULL on error.

dbi_result_t *dbd_query_null dbi_conn_t *conn const unsigned char *statement size_t st_length Performs a query using a binary query string and keeps track of meta-information about the query. Also see the helper function. Arguments conn: The target connection. statement: The query string to execute, which may contain NULL bytes and other non-printable characters. st_length: The length of the binary query string. Returns A DBI result object, or NULL on error.

const char *dbd_select_db dbi_conn_t *conn const char* db Selects a new database on the server. Arguments conn: The target connection. db: The name of the database to switch to. Returns The database name on success, NULL on error, or an empty string if the operation is not supported by the database server.

unsigned long long dbd_get_seq_last dbi_conn_t *conn const char *sequence Returns the row ID generated by the last INSERT command. Arguments conn: The target connection. sequence: The name of the sequence if the database engine requires this, or NULL if it is not required. Returns The row ID if successful, otherwise 0.

unsigned long long dbd_get_seq_next dbi_conn_t *conn const char *sequence Increments the sequence counter by the preset increment, and returns the resulting row ID. Arguments conn: The target connection. sequence: The name of the sequence if the database engine requires this, or NULL if it is not required. Returns The row ID if successful, otherwise 0. Also return 0 if the database engine does not implement this feature.

int dbd_ping dbi_conn_t *conn Checks whether the database connection is still alive. Arguments conn: The target connection. Returns 1 if the connection is alive, otherwise 0. This function may be implemented such that it automatically attempts to reconnect if the connection went down. If the reconnect is successful, the function should also return 1.

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

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.

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.

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.

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.

void _dbd_internal_error_handler dbi_conn_t *conn const char *errmsg const int errno Saves error message information generated by libdbi (rather than by the database or its API). 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. errno: The error number to store.

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.

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.

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.

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.

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.

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

size_t _dbd_decode_binary const unsigned char *in unsigned char *out Decodes a zero-terminated string with escaped characters as created by . 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.

&freedoc-license;