Provided by: libopendbx1-dev_1.4.6-16_amd64 bug

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.