Provided by: libopendbx1-dev_1.4.6-17_amd64 
NAME
OpenDBX::Conn - Encapsulates a connection to a database.
SYNOPSIS
Public Member Functions
void bind (const char *database, const char *who='', const char *cred='', odbxbind
method=ODBX_BIND_SIMPLE) throw ( std::exception )
Authenticates the user and selects the database using C style string parameters.
void bind (const string &database, const string &who='', const string &cred='', odbxbind
method=ODBX_BIND_SIMPLE) throw ( std::exception )
Authenticates the user and selects the database using C++ style string parameters.
Conn () throw ()
The default constructor for newly created connection objects without parameters.
Conn (const char *backend, const char *host='', const char *port='') throw ( std::exception )
Creates a connection object using C style string parameters.
Conn (const Conn &ref) throw ()
Copy constructor.
Conn (const string &backend, const string &host='', const string &port='') throw ( std::exception )
Creates a connection object using C++ style string parameters.
Stmt create (const char *sql, unsigned long size=0, Stmt::Type type=Stmt::Simple) throw ( std::exception
)
Creates a statement object from a SQL text string using a C style buffer.
Stmt create (const string &sql, Stmt::Type type=Stmt::Simple) throw ( std::exception )
Creates a statement object from a SQL text string using a C++ string.
string & escape (const char *from, unsigned long fromlen, string &to) throw ( std::exception )
Escapes potentially dangerous characters in user input using a C style buffer.
string & escape (const string &from, string &to) throw ( std::exception )
Escapes potentially dangerous characters in user input using a C++ style string parameter.
void finish () throw ( std::exception )
Cleans up the connection object.
bool getCapability (odbxcap cap) throw ( std::exception )
Tests if the database driver module does understand certain extensions.
void getOption (odbxopt option, void *value) throw ( std::exception )
Gets the value of a certain option provided by the database driver module.
Conn & operator= (const Conn &ref) throw ()
Assigns a connection instance to another one.
void setOption (odbxopt option, void *value) throw ( std::exception )
Sets a certain option provided by the database driver module.
void unbind () throw ( std::exception )
Releases the connection to the database and resets the authentication status.
~Conn () throw ()
Destroys the connection instance if no other references exist.
Detailed Description
Encapsulates a connection to a database.
Author
Norbert Sendetzky norbert@linuxnetworks.de
Version
1.0
Constructor & Destructor Documentation
OpenDBX::Conn::Conn ()
The default constructor for newly created connection objects without parameters. This is method is
provided to enable programmers to use connection objects as member variables of other classes. They are
initialized at construction time of the encapsulating object when no values for backend, host and port
are available yet.
It's necessary to replace the created object later on by a connection instance where the necessary
parameters have been given via one of the other constructors. Calling one of the member functions of an
instance created by the default constructor isn't possible and will throw an exception.
Returns
Empty connection instance
See also
Conn( const char*, const char*, const char* )
Conn( const string&, const string&, const string& )
OpenDBX::Conn::Conn (const char * backend, const char * host = '', const char * port = '')std::exception
Creates a connection object using C style string parameters. Initializes a new connection using the
parameters backend, host and port, but doesn't open the connection to the database yet. This method
allows C style strings as values for all parameters. Another constructor for C++ style strings is also
available. It returns a new connection instance, which can be used to query options implemented by the
driver or to create a statement. In case of an error, it throws an OpenDBX exception with error message,
code and severity.
The parameter backend is the name of the driver the OpenDBX library should use to connect to a database.
The name must be one of the implemented and available drivers on the system and is case sensitive. All
driver names are in lower case, e.g. 'mysql'.
Depending on the database driver, host can have different meanings. Normally, it's the name or IP address
of the server hosting the database server application. In case of serverless database implementations
like SQLite it's the directory path where the database file is located. The path must contain the
platform specific path separators like slash ('/') on Unix-like systems and backslash ('\') on Windows
systems. Also the path must end with the path separator like '/path/to/file/".
Furthermore port can be the number or name the database server application is listening to. If a name
instead of the number is allowed depends on the database client library but the number as string does
always work. If an empty string is given, the default port of the database server application is used by
the database client library.
Parameters
backend Name of the backend module to use
host Name or IP address of the database server
port Name or number of the port used by the database server
Returns
Connection instance
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
See also
Conn( const string&, const string&, const string& )
OpenDBX::Conn::Conn (const string & backend, const string & host = '', const string & port =
'')std::exception
Creates a connection object using C++ style string parameters. Initializes a new connection using the
parameters backend, host and port, but doesn't open the connection to the database yet. This method
allows C++ style strings as values for all parameters. Another construtor for C style strings is also
available. It returns a new connection instance, which can be used to query options implemented by the
driver or to create a statement. In case of an error, it throws an OpenDBX exception with error message,
code and severity.
The parameter backend is the name of the driver the OpenDBX library should use to connect to a database.
The name must be one of the implemented and available drivers on the system and is case sensitive. All
driver names are in lower case, e.g. 'mysql'.
Depending on the database driver, host can have different mearings. Normally, it's the name or IP address
of the server hosting the database server application. In case of serverless database implementations
like SQLite it's the directory path where the database file is located. The path must contain the
platform specific path separators like slash ('/') on Unix-like systems and backslash ('\') on Windows
systems. Also the path must end with the path separator like '/path/to/file/".
Furthermore port can be the number or name the database server application is listening to. If a name
instead of the number is allowed depends on the database client library but the number as string does
always work. If an empty string is given, the default port of the database server application is used by
the database client library.
Parameters
backend Name of the backend module to use
host Name or IP address of the database server
port Name or number of the port used by the database server
Returns
Connection instance
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
See also
Conn( const char*, const char*, const char* )
OpenDBX::Conn::~Conn ()
Destroys the connection instance if no other references exist. Each connection object uses a reference
counter to remember if the connection is shared with other objects. If this isn't the case or if this
object is the last one referencing the connection, the connection is closed and the allocated memory is
freed.
OpenDBX::Conn::Conn (const Conn & ref)
Copy constructor. Enables the transfer of the internal state of an object ref of the same type to this
object. Both objects share the same database connection and the reference counter afterwards. The
reference counter is incremented each time an object is copied and will be decremented if it is
destroyed.
Parameters
ref Original connection object instance
Member Function Documentation
void OpenDBX::Conn::bind (const char * database, const char * who = '', const char * cred = '', odbxbind
method = ODBX_BIND_SIMPLE)std::exception
Authenticates the user and selects the database using C style string parameters. After initializing the
object instance with one of the constructors taking a backend, host and port string as parameter, it's
necessary to authenticate the user and select a database. Depending on the database client library, it
also establishes the connection to the database server. This method accepts C style strings for the
database name, the user name and the password.
The first parameter, the name of the database will be used to select the database all further commands
are operating on. The database is the container for the tables, views, etc., which store the records and
provide access to them.
Authentication is done in most cases by a combination of a user name and a password. If the user name is
known by the database server and the supplied password matches with the stored one, the database server
will allow the user to operate on the selected database and its tables provided the user has permissions
to read and/or modify the content.
The method parameter can be used to select different methods of authentication. At the moment, only
simple authentication (ODBX_BIND_SIMPLE) with user name and password is available.
Parameters
database Name of the database managed by the database server
who Name of the user account known by the database server
cred Necessary credential which belongs to the user account
method Method used for authentication
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
void OpenDBX::Conn::bind (const string & database, const string & who = '', const string & cred = '',
odbxbind method = ODBX_BIND_SIMPLE)std::exception
Authenticates the user and selects the database using C++ style string parameters. After initializing the
object instance with one of the constructors taking a backend, host and port string as parameter, it's
necessary to authenticate the user and select a database. Depending on the database client library, it
also establishes the connection to the database server. This method accepts C++ style strings for the
database name, the user name and the password.
The first parameter, the name of the database will be used to select the database all further commands
are operating on. The database is the container for the tables, views, etc., which store the records and
provide access to them.
Authentication is done in most cases by a combination of a user name and a password. If the user name is
known by the database server and the supplied password matches with the stored one, the database server
will allow the user to operate on the selected database and its tables provided the user has permissions
to read and/or modify the content.
The method parameter can be used to select different methods of authentication. At the moment, only
simple authentication (ODBX_BIND_SIMPLE) with user name and password is available.
Parameters
database Name of the database managed by the database server
who Name of the user account known by the database server
cred Necessary credential which belongs to the user account
method Method used for authentication
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
Stmt OpenDBX::Conn::create (const char * sql, unsigned long size = 0, Stmt::Type type =
Stmt::Simple)std::exception
Creates a statement object from a SQL text string using a C style buffer. This method returns an instance
of the Stmt class that contains the statement sent to the database server later on. Currently, only
simple statements are supported, which are sent to the database server for parsing and returning the
result after calling Stmt::execute(). Later on also prepared statements will be possible which are parsed
by the database server when creating the object and only the parameters will be sent to the database
server on execution. This can speed up processing especially if the statement is executed multiple times
with different content for the parameters.
The parameter named sql must contain the SQL text string that should be sent to the database server for
execution. It have to be a C style buffer in this case. For a reference of valid SQL statements, please
have a look at the documentation of your database server.
The length of the statement excluding the trailing '0' byte should be given via the second parameter
size. If the length of the statement is unknown, you can also supply zero (0) as size value which is also
the default value if you hand over only one parameter. In this case, the length of the string is
calculated internally by this function before the statement is given to the native database library.
Via the last parameter it can be selected how the statement should be treated internally by the OpenDBX
and the native database library. Currently, only simple processing is available which sends complete SQL
statements including its parameters as string to the database server for parsing and execution. Later on,
also prepared statement handling will be available which parses the statements first and sends only the
parameters to the server before execution. This parameter is also optional.
The returned object is representing the given statement, which can be executed later on. The statement is
only valid for the current connection and as soon as the connection gets invalid or is closed, working
with this object will throw an error.
Parameters
sql SQL text string containing a valid statement understood by the database server
size Size of the SQL text string in bytes
type Type of statement object that should be created
Returns
Statement instance bound to this connection
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
See also
Stmt
Stmt OpenDBX::Conn::create (const string & sql, Stmt::Type type = Stmt::Simple)std::exception
Creates a statement object from a SQL text string using a C++ string. This method returns an instance of
the Stmt class that contains the statement sent to the database server later on. Currently, only simple
statements are supported, which are sent to the database server for parsing and returning the result
after calling Stmt::execute(). Later on also prepared statements will be possible which are parsed by the
database server when creating the object and only the parameters will be sent to the database server on
execution. This can speed up processing especially if the statement is executed multiple times with
different content for the parameters.
The parameter named sql must contain the SQL text string that should be sent to the database server for
execution. It have to be a C++ style string in this case. For a reference of valid SQL statements, please
have a look at the documentation of your database server.
Via the last parameter type it can be selected how the statement should be treated internally by the
OpenDBX and the native database library. Currently, only simple processing is available which sends
complete SQL statements including its parameters as string to the database server for parsing and
execution. Later on, also prepared statement handling will be available which parses the statements first
and sends only the parameters to the server before execution. This parameter is also optional.
The returned object is representing the given statement, which can be executed later on. The statement is
only valid for the current connection and as soon as the connection gets invalid or is closed, working
with this object will throw an error.
Parameters
sql SQL text string containing a valid statement understood by the database server
type Type of statement object that should be created
Returns
Statement instance bound to this connection
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
See also
Stmt
string & OpenDBX::Conn::escape (const char * from, unsigned long fromlen, string & to)std::exception
Escapes potentially dangerous characters in user input using a C style buffer. For preventing SQL
injection attacks which can have desasterous effects, all text input that will be part of an SQL
statement must be escaped. This does also apply to user content that is already stored in the database
and should be copied to another record or stored again as the escaping is removed before the database
server writes the content to disk.
The first parameter must contain the character sequence that should be escaped as C style string. This
string itself won't be modified by this method.
The escaped string will be written to the third parameter named to, which have to be also an C++ style
string. After transforming the input to an escaped string, the result may be more then twice the size of
the original input. The additional escape sequences aren't stored in the database column so only the
original string will be written to the disk.
A C++ reference of the third parameter containing the escaped string afterwards is also returned by this
method to providing the possibility to write more elegant code.
Parameters
from Input string with which may contain dangerous characters
fromlen Size of the input string to escape in bytes
to String instance where the escaped characters should be written to
Returns
Reference to the second parameter containing the escaped characters
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
string & OpenDBX::Conn::escape (const string & from, string & to)std::exception
Escapes potentially dangerous characters in user input using a C++ style string parameter. For preventing
SQL injection attacks which can have desasterous effects, all text input that will be part of an SQL
statement must be escaped. This does also apply to user content that is already stored in the database
and should be copied to another record or stored again as the escaping is removed before the database
server writes the content to disk.
The first parameter must contain the character sequence that should be escaped as C++ style string. This
string itself won't be modified by this method.
The escaped string will be written to the third parameter named to, which have to be also an C++ style
string. After transforming the input to an escaped string, the result may be more then twice the size of
the original input. The additional escape sequences aren't stored in the database column so only the
original string will be written to the disk.
A C++ reference of the second parameter containing the escaped string afterwards is also returned by this
method too, providing the possibility to write more elegant code.
Parameters
from Input string with which may contain dangerous characters
to String instance where the escaped characters should be written to
Returns
Reference to the second parameter containing the escaped characters
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
void OpenDBX::Conn::finish ()std::exception
Cleans up the connection object.
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
bool OpenDBX::Conn::getCapability (odbxcap cap)std::exception
Tests if the database driver module does understand certain extensions. The OpenDBX library consists of a
basic set of functions that must be implemented by all drivers and optional sets for additional
functionality. This method allows an application to ask the driver selected by the first parameter of the
constructor of this object if it supports one or more optional sets. The available sets and its constants
are:
• ODBX_CAP_BASIC
The core function set which have to be implemented by all backends. It consists of all functions
necessary to connect to, send textual queries to and process simple results returned from the database
server as well as error handling functions.
• ODBX_CAP_LO
The function set for handling large objects whose content isn't accessible by the basic function.
Currently, Firebird/Interbase and Oracle requires using the LOB functions.
The basic set makes sure that all drivers can handle connections to the databases, send statements and
retrieve results. It's supported by all drivers and usually don't have to be checked.
Some databases client libraries provide the content of large objects not via the basic functions.
Instead, the Result::fieldValue() method returns only a handle to the large object and reading or
modifying the content of this data object requires calling additional methods.
Parameters
cap Constant of the capability
Returns
True if supported, false if not
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
void OpenDBX::Conn::getOption (odbxopt option, void * value)std::exception
Gets the value of a certain option provided by the database driver module. It asks the backend module for
implemented options and their current values. This function can be used at every stage and its primary
use is to find out supported features of the backend module. This features can be enable with setOption()
before the connection to the database server is established by calling bind().
There are several option values defined as named constants in the opendbx/api.h header file. A few of
them are for informational purpose only while most of the options can also be set to different values by
setOption() to change the behavior of the backend module. These options are:
• ODBX_OPT_API_VERSION
The API version implemented by the backend. It returns a five digit number representing the API
version of the backend module in the form XYYZZ where X is the major number, YY the revision and ZZ the
minor number of the API.
• ODBX_OPT_THREAD_SAFE
If it is safe to use this backend and especially the native database client library in an application
which uses threads where more than one thread opens database connections via the OpenDBX library.
• ODBX_OPT_TLS
The database client library may support transmitting all data securely by encrypting the network
traffic via SSL or TLS.
• ODBX_OPT_MULTI_STATEMENTS
The database server may be able to support multiple SQL statements in one string sent to the database.
• ODBX_OPT_PAGED_RESULTS
All database servers and client libraries are able to transfer the records row by row. Some of them
can also transfer multiple rows or even all at once to minimize server load, network traffic and
latency. The downside of this is an increased memory consumption.
• ODBX_OPT_COMPRESS
Support of compressed network traffic between database client and server. This can lead to higher
throughput if the network is the bottleneck.
• ODBX_OPT_MODE
Some database servers support different modes of operation, e.g. modes for compliance to other SQL
implementations or completely different query languages.
The parameter value must be a pointer to an integer variable where the backend module will store the
result for the supplied option. If it's not stated otherwise, the value assigned to the this parameter
will be of boolean nature and therefore is ODBX_ENABLE for a supported option or ODBX_DISABLE for an
option which isn't supported.
Parameters
option Constant of the option
value Pointer to memory where the result is stored
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
Conn & OpenDBX::Conn::operator= (const Conn & ref)
Assigns a connection instance to another one. Assigns the internal state of an object ref of the same
type to this object. Both objects share the same database connection and the reference counter
afterwards. The reference counter is incremented each time an object is copied and will be decremented if
it is destroyed.
Parameters
ref Connection instance
Returns
Connection reference of this instance
void OpenDBX::Conn::setOption (odbxopt option, void * value)std::exception
Sets a certain option provided by the database driver module. Changes the value of the specified option
in the backend module or the native database library. Before trying to set an option, it should be tested
with getOption() first to ensure that it is supported by the backend. Almost all options need to be set
before connecting to the database server using bind() to take any effect.
There are several option values defined as named constants in the opendbx/api.h header file. The possible
options are:
• ODBX_OPT_TLS
Use encryption to transmit all data securely over the network via SSL or TLS. This option can be set
to ODBX_TLS_NEVER (the default value) to prevent encrpytion, ODBX_TLS_ALWAYS to enforce encryption and
to fail if it can't be used between the client library and the server or ODBX_TLS_TRY to use encryption
if possible with the option to fall back to a connection which isn't encrypted.
• ODBX_OPT_MULTI_STATEMENTS
Enables the database server to accept multiple statements in one string to the database if the value
of value is set to ODBX_ENABLE. Although, it might be possible to disable it by setting it to
ODBX_DISABLE.
• ODBX_OPT_PAGED_RESULTS
All database servers and client libraries are able to transfer the records row by row. Some of them
can also transfer multiple rows or even all at once to minimize server load, network traffic and
latency. The downside of this is an increased memory consumption. If paged results are supported by the
backend, passing positive values will fetch the specified number of records at once from the database
server. The value of zero ('0') is special in this case because it asks the backend module to retrieve
all records at once.
• ODBX_OPT_COMPRESS
Enable compressed network traffic between database client and server. This can maximize the throughput
if the network is the bottleneck. Pass an integer variable with ODBX_ENABLE to enable compression or
with ODBX_DISABLE to disable it for this connection.
• ODBX_OPT_MODE
Some database servers support different modes of operation, e.g. modes for compliance to other SQL
implementations or completely different query languages. The value for this option must point to a zero
terminated string.
If not stated otherwise, the type of the variable passed to the second parameter named value must be an
integer pointer. Its values must be in the range specified by the option being changed.
Parameters
option Constant of the option
value Pointer to memory which contains the new value
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
void OpenDBX::Conn::unbind ()std::exception
Releases the connection to the database and resets the authentication status.
Exceptions
std::invalid_argument If the object was only initialized by the default constructor
OpenDBX::Exception If the underlying database library returns an error
Author
Generated automatically by Doxygen for opendbx from the source code.
Version 1.4.6 Wed Apr 3 2024 11:07:55 OpenDBX::Conn(3)