NAME

       odbx_bind, odbx_bind_simple - User authentication for a database connection

SYNOPSIS

       #include <opendbx/api.h>

       int odbx_bind (odbx_t* handle, const char* database, const char* who, const char* cred, int method);

       int odbx_bind_simple (odbx_t* handle, const char* database, const char* who, const char* cred);

DESCRIPTION

       odbx_bind()  associates a connection created by odbx_init() to a specific database after the server veri‐
       fied 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,  odbx_bind()  also  en‐
       ables compatibility to the ANSI SQL standard if this is possible for the database server implementation.

       odbx_bind_simple()  performs  the  same  tasks as odbx_bind() but can't do anything else than simple user
       name / password authentication. It shouldn't be used in applications linking to the OpenDBX library  ver‐
       sion 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 handle parameter always has to be a pointer to a
       valid connection object allocated by odbx_init(). The availability of certain options or the behavior  of
       the connection associated to the given odbx_t pointer can be queried by calling odbx_get_option() respec‐
       tively  changed by odbx_set_option(). Changes must be done before calling odbx_bind() 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.

       database  is  necessary  to  let the database server know which database should be used for executing all
       further requests. In combination with the authentication parameters who and cred, it  usually  allows  or
       denies  operations  on  tables and records within this database. Contrary to that, SQLite doesn't use who
       and cred 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.

       method  specifies the mechanism for authenticating a user account before it can perform operations on ta‐
       bles and records. Currently, all database backend modules only support the ODBX_BIND_SIMPLE method  which
       provides  basic  user name / password authentication. In this case, the parameter who must be the name of
       an user account while cred 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  data‐
       base  server.  It is possible to bind it to another database, with another user account and other options
       set by detaching the connection object with odbx_unbind() first before invoking odbx_bind() with the same
       or with different parameters again.

RETURN VALUE

       odbx_init() returns ODBX_ERR_SUCCESS, or an error code whose value is less than zero if one of the opera‐
       tions couldn't be completed successfully. Possible error codes are listed in the error section  and  they
       can be feed to odbx_error() and odbx_error_type() to get further details.

ERRORS

       -ODBX_ERR_BACKEND
              The  backend module returned an error because it couldn't connect to the database or the authenti‐
              cation using the supplied parameters failed

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

       -ODBX_ERR_NOMEM
              Allocating additionally required memory failed

       -ODBX_ERR_SIZE
              The length of a string exceeded the available buffer size

       -ODBX_ERR_NOTSUP
              The supplied authentication method is not supported by the backend module

SEE ALSO

       odbx_error(), odbx_error_type(), odbx_init(), odbx_query(), odbx_unbind()

                                                 8 January 2025                                     odbx_bind(3)