1odbx_bind(3) OpenDBX odbx_bind(3)
2
6 odbx_bind, odbx_bind_simple - User authentication for a database con‐
7 nection
8
10 #include <opendbx/api.h>
11 int odbx_bind (odbx_t* handle, const char* database, const char* who,
14 const char* cred, int method);
15 int odbx_bind_simple (odbx_t* handle, const char* database, const char*
17 who, const char* cred);
18
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 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 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 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 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 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
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
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 -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 -ODBX_ERR_NOMEM
88 Allocating additionally required memory failed
89 -ODBX_ERR_SIZE
91 The length of a string exceeded the available buffer size
92 -ODBX_ERR_NOTSUP
94 The supplied authentication method is not supported by the back‐
95 end module
96
98 odbx_error(), odbx_error_type(), odbx_init(), odbx_query(), odbx_un‐
99 bind()
100 2 February 2021 odbx_bind(3)