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 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, odbx_bind() also enables 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 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 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() respectively 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 tables 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 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 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 operations 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 authentication 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()

                                          20 March 2014                              odbx_bind(3)