odbx_bind(3)

NAME

odbx_bind, odbx_bind_simple - User authentication for a database connection

SYNOPSIS

FC#include <opendbx/api.h>F[0]

FCint odbx_bindF[0] FC(odbx_t* handle, const char* database, const char* who, const char* cred, int method);F[0]

FCint odbx_bind_simpleF[0] FC(odbx_t* handle, const char* database, const char* who, const char* cred);F[0]

DESCRIPTION

FCodbx_bindF[0]() associates a connection created by FCodbx_initF[0]() to a specific database after the server verified and accepted the user credentials. All further operations will (normally) only affect the tables and records within this database. The operations may be limited to certain subset depending on the privileges granted to the given user account. If binding to the database instance succeeded, FCodbx_bindF[0]() also enables compatibility to the ANSI SQL standard if this is possible for the database server implementation.

FCodbx_bind_simpleF[0]() performs the same tasks as FCodbx_bindF[0]() but can't do anything else than simple user name / password authentication. It shouldn't be used in applications linking to the OpenDBX library version 1.1.1 or later and it will be removed from the library at a later stage.

Both functions accept almost the same parameters. The FChandleF[0] parameter always has to be a pointer to a valid connection object allocated by FCodbx_initF[0](). The availability of certain options or the behavior of the connection associated to the given odbx_t pointer can be queried by calling FCodbx_get_optionF[0]() respectively changed by FCodbx_set_optionF[0](). Changes must be done before calling FCodbx_bindF[0]() to take any effect. Examples of options are the thread-safetiness of the native database client library or the support for sending multiple statements at once.

FCdatabaseF[0] is necessary to let the database server know which database should be used for executing all further requests. In combination with the authentication parameters FCwhoF[0] and FCcredF[0], it usually allows or denies operations on tables and records within this database. Contrary to that, SQLite doesn't use FCwhoF[0] and FCcredF[0] but relies on the file system permissions instead to grant access to the whole database file. If they are used, the supplied values for all three parameters must be zero-terminated strings and should be in exactly the same character case as stored by the database manager. Otherwise, if they are unused they can also be NULL. Some database libraries also support default values provided by a configuration file if a parameter is NULL.

FCmethodF[0] specifies the mechanism for authenticating a user account before it can perform operations on tables and records. Currently, all database backend modules only support the FCODBX_BIND_SIMPLEF[0] method which provides basic user name / password authentication. In this case, the parameter FCwhoF[0] must be the name of an user account while FCcredF[0] has to be the password that belongs to the given account.

An already associated connection object can be detached from the database and rebound to the same database server. It is possible to bind it to another database, with another user account and other options set by detaching the connection object with FCodbx_unbindF[0]() first before invoking FCodbx_bindF[0]() with the same or with different parameters again.

RETURN VALUE

FCodbx_initF[0]() returns FCODBX_ERR_SUCCESSF[0], or an error code whose value is less than zero if one of the operations couldn't be completed successfully. Possible error codes are listed in the error section and they can be feed to FCodbx_errorF[0]() and FCodbx_error_typeF[0]() to get further details.

ERRORS

-FCODBX_ERR_BACKENDF[0]

The backend module returned an error because it couldn't connect to the database or the authentication using the supplied parameters failed

-FCODBX_ERR_PARAMF[0]

One of the supplied parameters is invalid or is NULL and this isn't allowed in the used backend module or in the native database client library

-FCODBX_ERR_NOMEMF[0]

Allocating additionally required memory failed

-FCODBX_ERR_SIZEF[0]

The length of a string exceeded the available buffer size

-FCODBX_ERR_NOTSUPF[0]

The supplied authentication method is not supported by the backend module

SEE ALSO

FCodbx_errorF[0](), FCodbx_error_typeF[0](), FCodbx_initF[0](), FCodbx_queryF[0](), FCodbx_unbindF[0]()