oracular (3) odbx_bind.3.gz

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()

                                                21 September 2024                                   odbx_bind(3)