1odbx_bind(3)                        OpenDBX                       odbx_bind(3)
2
3
4

NAME

6       odbx_bind,  odbx_bind_simple  - User authentication for a database con‐
7       nection
8

SYNOPSIS

10       #include <opendbx/api.h>
11
12
13       int odbx_bind (odbx_t* handle, const char* database, const char* who,
14                     const char* cred, int method);
15
16       int odbx_bind_simple (odbx_t* handle, const char* database, const char*
17                            who, const char* cred);
18

DESCRIPTION

20       odbx_bind() associates a connection created by odbx_init() to a specif‐
21       ic  database  after  the  server verified and accepted the user creden‐
22       tials. All further operations will (normally) only  affect  the  tables
23       and records within this database. The operations may be limited to cer‐
24       tain subset depending on the privileges granted to the given  user  ac‐
25       count.  If binding to the database instance succeeded, odbx_bind() also
26       enables compatibility to the ANSI SQL standard if this is possible  for
27       the database server implementation.
28
29       odbx_bind_simple()  performs the same tasks as odbx_bind() but can't do
30       anything else than simple  user  name  /  password  authentication.  It
31       shouldn't  be  used in applications linking to the OpenDBX library ver‐
32       sion 1.1.1 or later and it will be removed from the library at a  later
33       stage.
34
35       Both  functions accept almost the same parameters. The handle parameter
36       always has to be a pointer to a valid connection  object  allocated  by
37       odbx_init(). The availability of certain options or the behavior of the
38       connection associated to the given odbx_t pointer  can  be  queried  by
39       calling  odbx_get_option()  respectively  changed by odbx_set_option().
40       Changes must be done before calling odbx_bind() to take any effect. Ex‐
41       amples  of  options  are  the  thread-safetiness of the native database
42       client library or the support for sending multiple statements at once.
43
44       database is necessary to let the database server  know  which  database
45       should  be used for executing all further requests. In combination with
46       the authentication parameters who and cred, it usually allows or denies
47       operations  on  tables  and  records  within this database. Contrary to
48       that, SQLite doesn't use who and cred but relies  on  the  file  system
49       permissions instead to grant access to the whole database file. If they
50       are used, the supplied values for all three parameters  must  be  zero-
51       terminated  strings and should be in exactly the same character case as
52       stored by the database manager. Otherwise, if they are unused they  can
53       also  be NULL. Some database libraries also support default values pro‐
54       vided by a configuration file if a parameter is NULL.
55
56       method specifies the mechanism for authenticating a user account before
57       it  can  perform operations on tables and records. Currently, all data‐
58       base backend modules only support  the  ODBX_BIND_SIMPLE  method  which
59       provides  basic  user name / password authentication. In this case, the
60       parameter who must be the name of an user account while cred has to  be
61       the password that belongs to the given account.
62
63       An  already associated connection object can be detached from the data‐
64       base and rebound to the same database server. It is possible to bind it
65       to another database, with another user account and other options set by
66       detaching the connection object with odbx_unbind() first before  invok‐
67       ing odbx_bind() with the same or with different parameters again.
68

RETURN VALUE

70       odbx_init()  returns  ODBX_ERR_SUCCESS, or an error code whose value is
71       less than zero if one of the operations couldn't be completed  success‐
72       fully.  Possible  error  codes are listed in the error section and they
73       can be feed to odbx_error() and odbx_error_type() to  get  further  de‐
74       tails.
75

ERRORS

77       -ODBX_ERR_BACKEND
78              The backend module returned an error because it couldn't connect
79              to the database or the authentication using the supplied parame‐
80              ters failed
81
82       -ODBX_ERR_PARAM
83              One  of  the  supplied parameters is invalid or is NULL and this
84              isn't allowed in the used backend module or in the native  data‐
85              base client library
86
87       -ODBX_ERR_NOMEM
88              Allocating additionally required memory failed
89
90       -ODBX_ERR_SIZE
91              The length of a string exceeded the available buffer size
92
93       -ODBX_ERR_NOTSUP
94              The supplied authentication method is not supported by the back‐
95              end module
96

SEE ALSO

98       odbx_error(), odbx_error_type(),  odbx_init(),  odbx_query(),  odbx_un‐
99       bind()
100
101
102
103                                2 February 2021                   odbx_bind(3)
Impressum