airdbc.h File Reference

AirDBC Database Connectivity API. More...

#include <airdbc/drv_pg.h>
#include <airdbc/drv_oci.h>

Go to the source code of this file.

Defines

#define ADB_ERROR_DOMAIN   g_quark_from_string("AirDBCError")
 All AirDBC errors are returned within the ADB_ERROR_DOMAIN.
#define ADB_ERROR_RDBMS   1
 An underlying parse or execution error from the driver.
#define ADB_ERROR_CONNECT   2
 A connection error.
#define ADB_ERROR_ARGUMENT   3
 An argument passed to an AirDBC call had a bad format or value.
#define ADB_ERROR_RANGE   4
 An argument passed to an AirDBC call was out of range.

Typedefs

typedef _AdbConnection AdbConnection
 An AirDBC connection.
typedef _AdbStatement AdbStatement
 An AirDBC prepared statement.
typedef _AdbResultSet AdbResultSet
 An AirDBC result set.

Functions

AdbConnectionadb_conn_create (const char *uri, GError **err)
 Create a new, unopened AdbConnection.
gboolean adb_conn_open (AdbConnection *conn, GError **err)
 Ensure that an AdbConnection is open.
gboolean adb_conn_close (AdbConnection *conn, GError **err)
 Ensure that an AdbConnection is closed.
gboolean adb_conn_is_open (AdbConnection *conn)
 Determine the state of a connection.
void adb_conn_free (AdbConnection *conn)
 Destroy an AdbConnection, and free all storage associated with it.
gboolean adb_transaction_begin (AdbConnection *conn, GError **err)
 Begin a transaction on a given AdbConnection.
gboolean adb_transaction_commit (AdbConnection *conn, GError **err)
 Commit the current transaction on a given AdbConnection.
gboolean adb_transaction_rollback (AdbConnection *conn, GError **err)
 Roll back the current transaction on a given AdbConnection.
AdbStatementadb_stmt_prepare (AdbConnection *conn, char *sql, uint32_t param_maxlen, GError **err)
 Prepare a statement for binding an execution on a given AdbConnection.
void adb_stmt_free (AdbStatement *stmt)
 Destroy an AdbStatement, and free all storage associated with it.
gboolean adb_stmt_bind (AdbStatement *stmt, uint32_t pos, const char *val, GError **err)
 Bind a parameter value to a given AdbStatement by parameter position.
gboolean adb_stmt_bind_named (AdbStatement *stmt, const char *name, const char *val, GError **err)
 Bind a parameter value to a given AdbStatement by parameter name.
gboolean adb_stmt_execute (AdbStatement *stmt, GError **err)
 Execute an AdbStatement that does not return an AdbResultSet.
AdbResultSetadb_stmt_query (AdbStatement *stmt, GError **err)
 Execute an AdbStatement that returns an AdbResultSet.
void adb_rs_free (AdbResultSet *rs)
 Destroy an AdbResultSet, and free all storage associated with it.
gboolean adb_rs_next (AdbResultSet *rs, GError **err)
 Advance a given AdbResultSet's cursor to the next row.
uint32_t adb_rs_column_count (AdbResultSet *rs, GError **err)
 Return the number of columns in a given AdbResultSet.
char * adb_rs_column_name (AdbResultSet *rs, uint32_t col, GError **err)
 Return the name of a given column in an AdbResultSet.
gboolean adb_rs_fetch (AdbResultSet *rs, uint32_t col, const char **val, GError **err)
 Fetch a value from a given column of the current row of an AdbResultSet.
gboolean adb_rs_fetch_named (AdbResultSet *rs, const char *name, const char **val, GError **err)
 Fetch a value from a named column of the current row of an AdbResultSet.


Detailed Description

AirDBC Database Connectivity API.

This file provides the client interface for AirDBC applications.


Define Documentation

#define ADB_ERROR_CONNECT   2
 

A connection error.

The AdbConnection is closed.


Typedef Documentation

typedef struct _AdbConnection AdbConnection
 

An AirDBC connection.

Encapsulates a single restartable connection to a single RDBMS instance. Created by adb_conn_create(), and destroyed by adb_conn_free(). AdbConnections are created in disconnected state; adb_conn_open will open the connection. An AdbConnection may be closed by adb_conn_close(), or automatically if the underlying driver detects disconnection.

typedef struct _AdbResultSet AdbResultSet
 

An AirDBC result set.

Encapsulates a single result set returned by the execution of an AdbStatement. Created by adb_stmt_query(), and destroyed by adb_rs_free().Some drivers may require that each statement have at most one active AdbResultSet.

typedef struct _AdbStatement AdbStatement
 

An AirDBC prepared statement.

Encapsulates a single parameterized SQL statement, designed to be used multiple times. Each AdbStatement is scoped to an AdbConnection, which must be open when the statement is created with adb_stmt_prepare(). Statements are destroyed by adb_stmt_free().


Function Documentation

gboolean adb_conn_close AdbConnection conn,
GError **  err
 

Ensure that an AdbConnection is closed.

Closes the connection if it is open; otherwise, does nothing.

Parameters:
conn AdbConnection to close
err error description
Returns:
TRUE on success, FALSE otherwise

AdbConnection* adb_conn_create const char *  uri,
GError **  err
 

Create a new, unopened AdbConnection.

Connects to a database specified by a URI of the following format:

driver://username:password@host:port/dbname/additional

where username, password, port, and additional are optional. Supported drivers are "postgresql" (PostgreSQL 8.x+ via libpq 4.x) and "oci" (Oracle 9+ via Oracle Call Interface [libclntsh]). For postgresql URIs, port defaults to 5432. For oci URIs, host must always be localhost and port defaults to 0; because of the way Oracle Net Services works, all database connections are mediated by the local Oracle client software installation.

Parameters:
uri AirDBC database URI
err error description
Returns:
A new AdbConnection, or NULL on error.

void adb_conn_free AdbConnection conn  ) 
 

Destroy an AdbConnection, and free all storage associated with it.

Ensure that all scoped AdbStatements and AdbResultSets have been freed before calling this. If the AdbConnection is open, closes the connection and ignores the result.

Parameters:
conn an AdbConnection to free

gboolean adb_conn_is_open AdbConnection conn  ) 
 

Determine the state of a connection.

Parameters:
conn AdbConnection to check connection state of.
Returns:
TRUE if the connection is open, FALSE if closed.

gboolean adb_conn_open AdbConnection conn,
GError **  err
 

Ensure that an AdbConnection is open.

Opens the connection if it is closed; otherwise, does nothing.

Parameters:
conn AdbConnection to open
err error description
Returns:
TRUE on success, FALSE otherwise

uint32_t adb_rs_column_count AdbResultSet rs,
GError **  err
 

Return the number of columns in a given AdbResultSet.

Parameters:
rs AdbResultSet to get column count from
err error description
Returns:
column count, or 0 on error

char* adb_rs_column_name AdbResultSet rs,
uint32_t  col,
GError **  err
 

Return the name of a given column in an AdbResultSet.

The name's storage is managed by the AdbResultSet, and must be copied if intended to be used after the AdbResultSet is freed.

Parameters:
rs AdbResultSet to get column name from
col zero-indexed column number to name
err error description
Returns:
the column name, or NULL on error.

gboolean adb_rs_fetch AdbResultSet rs,
uint32_t  col,
const char **  val,
GError **  err
 

Fetch a value from a given column of the current row of an AdbResultSet.

Not valid on a newly executed query until adb_rs_next() has been called. The returned value's storage is managed by the AdbResultSet and scoped to the current row, and must be copied if intended to be used after the row cursor is advanced using adb_rs_next().

Parameters:
rs AdbResultSet to get value from
col zero-indexed column number to fetch
val fetched value (out-parameter)
err error description
Returns:
TRUE on success, FALSE otherwise

gboolean adb_rs_fetch_named AdbResultSet rs,
const char *  name,
const char **  val,
GError **  err
 

Fetch a value from a named column of the current row of an AdbResultSet.

Not valid on a newly executed query until adb_rs_next() has been called. The returned value's storage is managed by the AdbResultSet and scoped to the current row, and must be copied if intended to be used after the row cursor is advanced using adb_rs_next().

Parameters:
rs AdbResultSet to get value from
name name of column to fetch
val fetched value (out-parameter)
err error description
Returns:
TRUE on success, FALSE otherwise

void adb_rs_free AdbResultSet rs  ) 
 

Destroy an AdbResultSet, and free all storage associated with it.

Parameters:
rs an AdbResultSet to free

gboolean adb_rs_next AdbResultSet rs,
GError **  err
 

Advance a given AdbResultSet's cursor to the next row.

Must be called after a successful adb_stmt_query() to start fetching data. Returns FALSE and sets *err to NULL at the end of the result set. Designed to be called as follows:

      rs = adb_stmt_query(stmt, &err);
      if (!rs) {
          ... handle adb_stmt_query() error ...
      }
      while (adb_rs_next(rs, &err) {
          ... fetch and process row ...
      }
      if (err) {
          ... handle adb_rs_next() error ...
      }

Parameters:
rs AdbResultSet to advance cursor on
err error description
Returns:
TRUE on success, FALSE otherwise

gboolean adb_stmt_bind AdbStatement stmt,
uint32_t  pos,
const char *  val,
GError **  err
 

Bind a parameter value to a given AdbStatement by parameter position.

This parameter will copy the string value into the statement, so it is safe to free or reuse values between bind and execute.

Parameters:
stmt AdbStatement to bind.
pos zero-indexed parameter position
val string value to bind (or NULL)
err error description
Returns:
TRUE on success, FALSE otherwise

gboolean adb_stmt_bind_named AdbStatement stmt,
const char *  name,
const char *  val,
GError **  err
 

Bind a parameter value to a given AdbStatement by parameter name.

This parameter will copy the string value into the statement, so it is safe to free or reuse values between bind and execute. If a given bind name appears multiple times in the statement, this will bind the given value to each such position.

Parameters:
stmt AdbStatement to bind.
name parameter name
val string value to bind (or NULL)
err error description
Returns:
TRUE on success, FALSE otherwise

gboolean adb_stmt_execute AdbStatement stmt,
GError **  err
 

Execute an AdbStatement that does not return an AdbResultSet.

This is intended for use with data manipulation or data definition statements, though it can be used for queries as well, to ignore the resulting result set.

Parameters:
stmt AdbStatement to execute.
err error description
Returns:
TRUE on success, FALSE otherwise

void adb_stmt_free AdbStatement stmt  ) 
 

Destroy an AdbStatement, and free all storage associated with it.

Parameters:
stmt an AdbStatement to free

AdbStatement* adb_stmt_prepare AdbConnection conn,
char *  sql,
uint32_t  param_maxlen,
GError **  err
 

Prepare a statement for binding an execution on a given AdbConnection.

Bind parameters are specified using Oracle-style syntax (i.e., ":name") and translated into the driver's native positional bind parameter syntax. Since bind parameter buffers must be statically sized for some drivers (i.e., Oracle), bind parameter lengths are limited to a constant size given in param_maxlen. If param_maxlen is given as 0, the bind parameter buffer size defaults to 64 bytes per parameter.

Parameters:
conn AdbConnection on which to prepare a statement. Must be open.
sql Parameterized SQL string to prepare.
param_maxlen Maximum length of each bind parameter. Defaults to 64.
err error description
Returns:
A new AdbStatement, or NULL on failure.

AdbResultSet* adb_stmt_query AdbStatement stmt,
GError **  err
 

Execute an AdbStatement that returns an AdbResultSet.

The result set's cursor will be positioned before the first row, so a call to adb_rs_next() is required before the first call to adb_rs_fetch().

Note that some drivers require only one AdbResultSet at once per AdbStatement to be active, so this call may fail if a previous AdbResultSet has not yet been freed.

Parameters:
stmt AdbStatement to execute.
err error description
Returns:
a new AdbResultSet, or NULL on failure.

gboolean adb_transaction_begin AdbConnection conn,
GError **  err
 

Begin a transaction on a given AdbConnection.

If the connection fails or an error occurs before the transaction is committed, all changes within the transaction will be rolled back. Some drivers may not support nested transactions.

Parameters:
conn AdbConnection to start transaction on
err error description
Returns:
TRUE on success, FALSE otherwise

gboolean adb_transaction_commit AdbConnection conn,
GError **  err
 

Commit the current transaction on a given AdbConnection.

Fails if no transaction is currently active.

Parameters:
conn AdbConnection to commit transaction on
err error description
Returns:
TRUE on success, FALSE otherwise

gboolean adb_transaction_rollback AdbConnection conn,
GError **  err
 

Roll back the current transaction on a given AdbConnection.

Fails if no transaction is currently active.

Parameters:
conn AdbConnection to roll back transaction on
err error description
Returns:
TRUE on success, FALSE otherwise


© 2005 Carnegie Mellon University
Generated Thu Nov 17 18:48:45 2005 for AirDBC 0.2.0 by Doxygen 1.4.5.