api		api
	/*		/*
	* OpenDBX - A simple but extensible database abstraction layer		* OpenDBX - A simple but extensible database abstraction layer
	* Copyright (C) 2004-2008 Norbert Sendetzky <norbert@linuxnetworks.de>		* Copyright (C) 2004-2009 Norbert Sendetzky <norbert@linuxnetworks.de>
	*		*
	* This library is free software; you can redistribute it and/or		* This library is free software; you can redistribute it and/or
	* modify it under the terms of the GNU Library General Public		* modify it under the terms of the GNU Library General Public
	* License as published by the Free Software Foundation; either		* License as published by the Free Software Foundation; either
	* version 2 of the License, or (at your option) any later version.		* version 2 of the License, or (at your option) any later version.
	*		*
	* This library is distributed in the hope that it will be useful,		* This library is distributed in the hope that it will be useful,
	* but WITHOUT ANY WARRANTY; without even the implied warranty of		* but WITHOUT ANY WARRANTY; without even the implied warranty of
	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	* Library General Public License for more details.		* Library General Public License for more details.
	skipping to change at line 31		skipping to change at line 31
	#include <opendbx/api.h>		#include <opendbx/api.h>
	#include <stdexcept>		#include <stdexcept>
	#include <vector>		#include <vector>
	#include <string>		#include <string>
	#ifndef ODBX_API_HPP		#ifndef ODBX_API_HPP
	#define ODBX_API_HPP		#define ODBX_API_HPP
	extern "C++" {		extern "C++" {
	namespace OpenDBX		/**
	{		* OpenDBX C++ API
	class Lob_Impl;		*
	class Result_Impl;		* The OpenDBX C++ API is an object-oriented database abstraction layer bas
	class Stmt_Impl;		ed
	class Conn_Impl;		* on the procedural C API of the OpenDBX library. The C++ API provides obj
	}		ects
			* encapsulating connections, statements, result sets and large objects.
			*
			* Using the API starts with establishing a connection to the database serv
			er by
			* creating an instance of the Conn class with the parameters backend, host
			and
			* port. Conn::getCapability() tests the implemented capabilites of the und
			erlying
			* database library while Conn::getOption() and Conn::setOption() cas be us
			ed to
			* test for and change a number of options. The options must be changed bef
			ore
			* authenticating the connection with the Conn::bind() method to have any e
			ffect.
			* It's also possible to rebind a connection using different credentials af
			ter
			* Conn::unbind() had been called. Additionally, the Conn class is able to
			* escape potentially dangerous character sequences with Conn::escape() if
			e.g.
			* user input should be part of a statement as value.
			*
			* The Conn::create() method creates and initializes a new statement instan
			ce
			* from a SQL string. Currently, there are only simple statement objects
			* implemented, which needs to be complete statements which can be sent to
			the
			* database with Stmt::execute(). This method returns a Result object
			* encapsulating one or more result sets returned by the database depending
			on
			* the statement sent.
			*
			* Each result set must be retrieved using Result::getResult(), while
			* Result::getRows() fetches a row from the current result set if the state
			ment
			* was a SELECT like statement. Otherwise, Result::rowsAffected() can be us
			ed
			* to get the number of rows that were touched by the statement. If the sta
			tement
			* may return rows, the Result::columnName() and Result::columnType() metho
			ds
			* are able to provide some informations about the columns indexed from 0 t
			o n.
			* It's also possible to map the column name with the Result::columnPos() m
			ethod
			* to the column index which is required be the other column methods. To ge
			t
			* the actual value and length of the content in the current row at the giv
			en
			* position, the Result::fieldValue() and Result::fieldLength() must be cal
			led.
			*
			* In case the unterlying database library requires special handling of lar
			ge
			* objects (binary or text LOBs), the value of Result::fieldValue() has to
			be
			* feed into the Result::getLob() method. It returns a Lob object which ena
			bles
			* the application to read from and write to a large object using Lob::read
			()
			* respectively Lob::write(). This is only necessary if the Conn::getCapabi
			lity()
			* method returns true when asking for ODBX_CAP_LO.
			*
			* If an error occurs in any of the object methods, the objects will throw
			an
			* instance of the Exception class with extends the runtime_error exception
			of
			* the STL. The instance contains an error message, the OpenDBX error code
			and
			* an error type indicating the severity of the error. This information can
			be
			* retrieved by the methods Exception::what(), Exception::getCode() and
			* Exception::getType().
			*
			* @author Norbert Sendetzky <norbert@linuxnetworks.de>
			* @version 1.0
			*/
	namespace OpenDBX		namespace OpenDBX
	{		{
	using std::string;		using std::string;
	class Lob;		class Lob_Iface;
	class Result;		class Result_Iface;
	class Stmt;		class Stmt_Iface;
	class Conn;		class Conn_Iface;
	/**		/**
	* Exception thrown by OpenDBX objects.		* Exceptions thrown by the OpenDBX classes.
			*
			* Most calls to methods of OpenDBX objects does throw an exception
			in case
			* an error occurs in the underlying database library. Additionally
			to other
			* exceptions which inherit from the STL exception class it will not
			only
			* contain a translated error message depending on the user settings
			but
			* also a machine readable error code and an indicator for the sever
			ity of
			* the eror.
			*
			* @author Norbert Sendetzky <norbert@linuxnetworks.de>
			* @version 1.0
	*/		*/
	class Exception : public std::runtime_error		class Exception : public std::runtime_error
	{		{
	protected:
	/**		/**
	* Error code (negative).		* Error code (negative).
	*/		*/
	int m_error;		int m_error;
	/**		/**
	* Severity of error (negative: fatal, zero: success, positi ve: warning)		* Severity of error (negative: fatal, zero: success, positi ve: warning)
	*/		*/
	int m_type;		int m_type;
	public:		public:
	/**		/**
	* Initializes exception object.		* Initializes the exception object.
			*
			* The first parameter, the error message, should be the hum
			an readable
			* description of what has gone wrong. It should also be alr
			eady translated
			* to the language of the user which depends on his environm
			ent settings
			* when e.g GNU gettext is used. Errors thrown by the OpenDB
			X C++ library
			* are already translated.
			*
			* The OpenDBX error code is the machine readable code for t
			he error which
			* has been occured.
			*
			* The last parameter must be a value indicating the severit
			y of the
			* thrown error. If the value is smaller than zero, the erro
			r is fatal
			* and the connection to the database can't be recovered and
			has to be
			* closed and reopened before the application can try to con
			tinue. In
			* case it's greater than zero, the operation failed but the
			database
			* connection is still usable. Zero represents a successful
			operation
			* and shouldn't be used because an exception should only be
			thrown in
			* error conditions.
	*		*
	* @param msg Error message		* @param msg Human readable error message
	* @param err OpenDBX error code		* @param err OpenDBX error code
	* @param type Severity of error (negative: fatal, zero: suc cess, positive: warning)		* @param type Severity of error (negative: fatal, zero: suc cess, positive: warning)
	* @return Exception		* @return Exception
	*/		*/
	Exception( string msg, int err, int type );		Exception( const string& msg, int err, int type ) throw();
	/**		/**
	* Returns the OpenDBX error code related to the error.		* Returns the OpenDBX error code related to the error.
	*		*
			* The machine readable code describing the error which occu
			red can be
			* used by the application to act differently depending on t
			he specific
			* error. Currently defined codes are:
			*
			* - ODBX_ERR_SUCCESS\n
			* The operation was successfully completed.
			* - ODBX_ERR_BACKEND\n
			* An error occured in the native database library or in t
			he
			* database server.
			* - ODBX_ERR_NOCAP\n
			* The capability isn't available in the currently selecte
			d backend.
			* - ODBX_ERR_PARAM\n
			* One of the given parameters is invalid and doesn't matc
			h the
			* expectations.
			* - ODBX_ERR_NOMEM\n
			* An out of memory condition occured.
			* - ODBX_ERR_SIZE\n
			* The internally allocated memory is unable to store the
			value.
			* - ODBX_ERR_NOTEXIST\n
			* The backend library wasn't found or loading the library
			failed.
			* - ODBX_ERR_NOOP\n
			* The required function isn't available or the operation
			isn't
			* possible in this backend.
			* - ODBX_ERR_OPTION\n
			* The given option is unknown an therefore invalid.
			* - ODBX_ERR_OPTRO\n
			* The requested option is read-only and its value can't b
			e changed.
			* - ODBX_ERR_OPTWR\n
			* Setting the given option to the new value failed.
			* - ODBX_ERR_RESULT\n
			* Waiting for the result set after sending a statement to
			the
			* database server failed.
			* - ODBX_ERR_NOTSUP\n
			* The requested functionality isn't supported by the back
			end.
			* - ODBX_ERR_HANDLE\n
			* The internal data structure which should store the deta
			ils for
			* accessing the database are invalid.
			*
	* @return Error code		* @return Error code
	*/		*/
	int getCode();		int getCode() const throw();
	/**		/**
	* Returns severity indicator.		* Returns severity indicator.
	*		*
			* The returned value classifies the error thrown. In case i
			t is negative,
			* the error is fatal (e.g. the connection to the database i
			s lost) and
			* the application can't continue without closing and reopen
			ing the
			* connection.
			*
			* If the value is positive, the database wasn't able to per
			form the
			* requested action but the connection is still OK and can b
			e used to
			* send more requests to the database.
			* On zero, everything was successfull and no error occured.
			This
			* shouldn't happen when catching one of these exceptions.
			*
	* @return Severity of error (negative: fatal, zero: success , positive: warning)		* @return Severity of error (negative: fatal, zero: success , positive: warning)
	*/		*/
	int getType();		int getType() const throw();
	};		};
	/**		/**
	* Handling large objects if supported by the database.		* Handling large objects if supported by the database.
			*
			* @author Norbert Sendetzky <norbert@linuxnetworks.de>
			* @version 1.0
	*/		*/
	class Lob		class Lob
	{		{
	protected:		friend class Result;
	/**		/**
	* Private implementation of object.		* Private implementation of object.
	*/		*/
	Lob_Impl* m_impl;		Lob_Iface* m_impl;
	/**		/**
	* Reference counter of copies.		* Reference counter of copies.
	*/		*/
	int* m_ref;		int* m_ref;
			protected:
	/**		/**
	* Default constructor.		* Default constructor.
	*		*
			* The default constructor isn't part of the public interfac
			e as the
			* object must not be created manually. Instead, the Result:
			:getLob()
			* method is a factory for instances of the large object cla
			ss.
			*
	* @return Lob instance		* @return Lob instance
	*/		*/
	Lob();		Lob() throw() {};
	/**		/**
	* Create large object instance.		* Create large object instance.
	*		*
			* The constructor isn't part of the public interface as the
			object must
			* not be created manually. Instead, the Result::getLob() m
			ethod is a
			* factory for instances of the large object class.
			*
	* @param impl Pointer to private implementation		* @param impl Pointer to private implementation
	* @return Lob instance		* @return Lob instance
			* @throws std::exception If an error occures
	*/		*/
	Lob( Lob_Impl* impl );		Lob( Lob_Iface* impl ) throw( std::exception );
	friend class Result;
	public:		public:
	/**		/**
	* Destroy large object instance if no other references exis t.		* Destroy large object instance if no other references exis t.
			*
			* Each large object uses a reference counter to remember if
			the
			* internal variables are shared with other objects. If this
			isn't the
			* case or if this object is the last one referencing the va
			riables,
			* the object is cleanup up and the allocated memory freed.
			*/
			~Lob() throw();
			/**
			* Copy constructor.
			*
			* Enables the transfer of the internal state of an object \
			a ref of the same
			* type to this object. Both objects share the same variable
			s
			* and the reference counter afterwards. The reference count
			er is
			* incremented each time an object is copied and will be dec
			remented if
			* it is destroyed.
			*
			* @param ref Original large object instance
	*/		*/
	~Lob();		Lob( const Lob& ref ) throw();
	/**		/**
	* Assign large object instance to another one.		* Assign large object instance to another one.
	*		*
			* Assigns the internal state of an object \a ref of the sam
			e type to this
			* object. Both objects share the same variables and the
			* reference counter afterwards. The reference counter is in
			cremented
			* each time an object is copied and will be decremented if
			it is
			* destroyed.
			*
	* @param ref Large object instance		* @param ref Large object instance
	* @return Large object reference of this instance		* @return Large object reference of this instance
	*/		*/
	Lob& operator=( const Lob& ref );		Lob& operator=( const Lob& ref ) throw();
	/**		/**
	* Close Lob and commit changes.		* Closes the large object and commits the changes.
			*
			* After reading from or writing new content into the large
			object, it
			* should be closed to commit changes to the disk and clean
			up the
			* resources. If this isn't done, the destructor of the obje
			ct tries to
			* close the large object automatically, but there's no guar
			antee it
			* was successful as the destructor doesn't throw an excepti
			on in case
			* of an error. Therefore, it's highly recommended to call t
			his method
			* once when you don't need the object any more.
			*
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	void close();		void close() throw( std::exception );
	/**		/**
	* Reads content from large object into the buffer.		* Reads content from large object into the buffer.
	*		*
			* To get the content of a large object, this method fetches
			the data
			* in one or more pieces from the server and stores it into
			the user
			* supplied buffer. The first call to read() will return the
			bytes from
			* the beginning. The second and all other calls will store
			subsequent
			* parts of the large object content into the buffer until t
			he end of
			* the data is reached. To reread the content a second time,
			you have
			* to close the large object handle and reopen it again as s
			ome databases
			* provide no way to reposition the internal file position i
			ndicator for
			* the stream. The large object content fetched from the ser
			ver is
			* stored into the user supplied \a buffer up to \a buflen b
			ytes.
			*
			* The method returns the number of bytes placed into \a buff
			er, which may
			* be up to \a buflen bytes. If the end of the content is rea
			ched and no
			* more data is available, the return value will be 0 (zero).
			*
	* @param buffer Pointer to a byte array where the data shou ld be written to		* @param buffer Pointer to a byte array where the data shou ld be written to
	* @param buflen Length of the given buffer in bytes		* @param buflen Length of the given buffer in bytes
	* @return Number of bytes written into the buffer		* @return Number of bytes written into the buffer
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	*/		*/
	ssize_t read( void* buffer, size_t buflen );		ssize_t read( void* buffer, size_t buflen ) throw( std::exce ption );
	/**		/**
	* Writes data from the buffer into the large object.		* Writes data from the buffer into the large object.
	*		*
			* It sends the data supplied in buffer to the server for st
			oring it
			* inside the large object. The function can be called more
			than once
			* to add subsequent parts of the content to the object. If
			it isn't a
			* new or empty object, the existing data will be overwritte
			n and
			* truncated to the new size. It's not possible to update on
			ly parts of
			* the content as some databases doesn't support to position
			the
			* internal file position indicator. The data which should b
			e send to
			* the server is read from \a buffer up to \a buflen bytes.
			*
			*The method returns the number of bytes read from \a buffer
			and sent to
			* the database server, which may be up to \a buflen bytes.
			It isn't
			* guaranteed that the complete chunk was sent to the server
			, so the
			* returned size may be less than the value in \a buflen.
			*
	* @param buffer Pointer to a byte array where the content i s stored		* @param buffer Pointer to a byte array where the content i s stored
	* @param buflen Length of the data in the buffer in bytes		* @param buflen Length of the data in the buffer in bytes
	* @return Number of bytes written into the large object		* @return Number of bytes written into the large object
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	*/		*/
	ssize_t write( void* buffer, size_t buflen );		ssize_t write( void* buffer, size_t buflen ) throw( std::exc eption );
	};		};
	/**		/**
	* Provides result sets from the database.		* Provides result sets from the database.
			*
			* @author Norbert Sendetzky <norbert@linuxnetworks.de>
			* @version 1.0
	*/		*/
	class Result		class Result
	{		{
	protected:		friend class Stmt;
	/**		/**
	* Private implementation of object.		* Private implementation of object.
	*/		*/
	Result_Impl* m_impl;		Result_Iface* m_impl;
	/**		/**
	* Reference counter of copies.		* Reference counter of copies.
	*/		*/
	int* m_ref;		int* m_ref;
			protected:
	/**		/**
	* Default constructor.		* Default constructor.
	*		*
			* The default constructor isn't part of the public interfac
			e as the
			* object must not be created manually. Instead, the Stmt::e
			xecute()
			* method is a factory for instances of the Result class.
			*
	* @return Result instance		* @return Result instance
	*/		*/
	Result();		Result() throw() {};
	/**		/**
	* Create Result instance.		* Creates a Result instance.
			*
			* The constructor isn't part of the public interface as the
			object must
			* not be created manually. Instead, the Stmt::execute() me
			thod is a
			* factory for instances of the Result class.
	*		*
	* @param impl Pointer to private implementation		* @param impl Pointer to private implementation
			* @throws std::exception If an error occures
	* @return Result instance		* @return Result instance
	*/		*/
	Result( Result_Impl* impl );		Result( Result_Iface* impl ) throw( std::exception );
	friend class Stmt;
	public:		public:
	/**		/**
	* Destroy Result instance if no other references exist.		* Destroys a Result instance if no other references exist.
			*
			* Each result object uses a reference counter to remember i
			f the
			* internal variables are shared with other objects. If this
			isn't the
			* case or if this object is the last one referencing the va
			riables,
			* the object is cleanup up and the allocated memory freed.
	*/		*/
	~Result();		~Result() throw();
	/**		/**
	* Assign Result instance to another one.		* Copy constructor.
	*		*
	* @param ref Result instance		* Enables the transfer of the internal state of an object \
	* @return Result reference of this instance		a ref of the same
			* type to this object. Both objects share the same variable
			s
			* and the reference counter afterwards. The reference count
			er is
			* incremented each time an object is copied and will be dec
			remented if
			* it is destroyed.
			*
			* @param ref Original result object instance
	*/		*/
	Result& operator=( const Result& ref );		Result( const Result& ref ) throw();
	/**		/**
	* Get unfetched rows and clean up the current result set.		* Assigns a Result instance to another one.
			*
			* Assigns the internal state of an object \a ref of the sam
			e type to this
			* object. Both objects share the same variables and the
			* reference counter afterwards. The reference counter is in
			cremented
			* each time an object is copied and will be decremented if
			it is
			* destroyed.
			*
			* @param ref Result instance
			* @return Result reference of this instance
	*/		*/
	void finish();		Result& operator=( const Result& ref ) throw();
	/**		/**
	* Fetch one result set from the database server.		* Retrieves unfetched rows and cleans up the available resu
			lt sets.
			*
			* After executing a statement, at least one result set is r
			eturned by
			* the database server. In case of data manipulation stateme
			nts, there
			* are no rows returned but you have to clean up the result
			set
			* nevertheless. This is usually done by calling and getResu
			lt() in a loop
			* until it returns "done". In order to simplify application
			development,
			* the finish() method does this for you.
			*
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
			*/
			void finish() throw( std::exception );
			/**
			* Fetches one result set from the database server.
			*
			* Retrieves the result of a query statement from the databa
			se server.
			* If the statement was an INSERT, UPDATE, DELETE or a simil
			ar
			* statement, the number of affected rows is available via r
			owsAffected().
			*
			* The \a timeout parameter restricts the time the function
			is waiting for
			* a result form the server. It may be NULL to wait until a
			result
			* arrives. Otherwise, it can contain any number of seconds
			and
			* microseconds in a timeval structure to wait for. The time
			val structure
			* must be set each time before calling getResult() because
			its content
			* may get changed by the function. If the server doesn't re
			spond within
			* the timeout, the query isn't canceled! Instead, the next
			call to this
			* function will wait for the same result set. Waiting the s
			pecified time
			* may be implemented in the backends if it is possible, but
			there is no
			* guarantee. If not, getResult() will return not before a r
			esponds
			* arrives.
			*
			* Dependent on the native database library, it may be possi
			ble to
			* retrieve all rows at once (if chunk is zero), one by one
			or more than
			* one row at once. All positive values including zero are a
			llowed as
			* values for \a chunk If paging (more than one row at once)
			is not
			* supported by the backend, it will use "one by one" or "al
			l at once"
			* if this is the only option provided.
			*
			* getResult() returns ODBX_RES_ROWS if a result set is avai
			lable and
			* ODBX_RES_DONE if no more results will be returned by the
			last
			* successful query. ODBX_RES_NOROWS is returned if the stat
			ement was
			* executed successfully but will not return a results set (
			like for
			* INSERT, UPDATE and DELETE statements) and ODBX_RES_TIMEOU
			T indicates
			* a timeout.
	*		*
	* @param timeout Pointer to a timeval struct specifying how long to wait for a result set from the database server		* @param timeout Pointer to a timeval struct specifying how long to wait for a result set from the database server
	* @param chunk Number of rows to fetch at once from the dat abase server (zero means all rows at once)		* @param chunk Number of rows to fetch at once from the dat abase server (zero means all rows at once)
	* @return Status or error code		* @return Status or error code
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	* @see odbxres		* @see odbxres
	*/		*/
	odbxres getResult( struct timeval* timeout = NULL, unsigned long chunk = 0 );		odbxres getResult( struct timeval* timeout = NULL, unsigned long chunk = 0 ) throw( std::exception );
	/**		/**
	* Makes data of next row available.		* Makes data of next row available.
	*		*
	* @return Status or error code		* Retrieves the values of a row from the current result set
			returned
			* by getResult(). Until this function is invoked, no row an
			d field data
			* is available via fieldLength() or fieldValue() and these
			functions
			* will throw an exception.
			*
			* getRow() will return ODBX_ROW_NEXT as long as rows are av
			ailable
			* from the result set. After the last row has been made ava
			ilable,
			* further calls to this function will return ODBX_ROW_DONE
			indicating
			* that the result set doesn't contain more rows.
			*
			* @return Status of the attempt to fetch one more row
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	odbxrow getRow();		odbxrow getRow() throw( std::exception );
	/**		/**
	* Returns the number of rows affected by DELETE, INSERT of UPDATE statements.		* Returns the number of rows affected by DELETE, INSERT of UPDATE statements.
	*		*
			* Returns the number of rows that have been changed by the
			current
			* statement whose result set was retrieved by getResult() a
			nd zero
			* if the database server didn't alter any rows. Affected ro
			ws are only
			* returned for DELETE, INSERT or UPDATE statements and thei
			r concrete
			* number depends on the database implementation. Some datab
			ase server
			* like MySQL may return a lower number than expected becaus
			e they
			* doesn't modify records whose values wouldn't change.
			*
	* @return Number of rows touched		* @return Number of rows touched
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	*/		*/
	uint64_t rowsAffected();		uint64_t rowsAffected() throw( std::exception );
	/**		/**
	* Returns the number of columns available in this result se t.		* Returns the number of columns available in this result se t.
	*		*
			* The number of columns will never change within a result s
			et with one
			* notable exception: MySQL returns all outstanding rows of
			a previous
			* result set first if they were not fetched completely by g
			etRow()
			* before. Therefore, the column count might change in this
			special
			* situation.
			*
	* @return Number of columns		* @return Number of columns
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	*/		*/
	unsigned long columnCount();		unsigned long columnCount() throw( std::exception );
	/**		/**
	* Maps the column name to the column number required by oth er methods.		* Maps the column name to the column number required by oth er methods.
	*		*
			* This method returns the index of the column which is name
			d like the
			* content of the string given via the parameter \a name. Th
			e column index will
			* not change within the result set.
			*
	* @param name Name of the column in the result set		* @param name Name of the column in the result set
	* @return Position of column in result set		* @return Position of column in result set
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	*/		*/
	unsigned long columnPos( const string& name );		unsigned long columnPos( const string& name ) throw( std::ex ception );
	/**		/**
	* Returns the name of the column in the current result set.		* Returns the name of the column in the current result set.
	*		*
			* Gets the name of the column specified by \a pos in the cu
			rrent result
			* set. The column names will not change within the result s
			et with the
			* exception of MySQL when the first result set wasn't retri
			eved
			* completely before getResult() was called again.
			*
	* @param pos Position of column in result set		* @param pos Position of column in result set
	* @return Column name		* @return Column name
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	*/		*/
	string columnName( unsigned long pos );		const string columnName( unsigned long pos ) throw( std::exc eption );
	/**		/**
	* Returns the type of the column in the current result set.		* Returns the type of the column in the current result set.
	*		*
			* The column type applies to all fields at the same positio
			n of the
			* rows fetched via getRow(). The definitions are based on t
			he SQL2003
			* standard and the data types of the database server have t
			o comply to
			* the specification of the standard. These are:
			*
			* Exact numeric values:
			* - ODBX_TYPE_BOOLEAN: True/false values
			* - ODBX_TYPE_SMALLINT: Signed 16 bit integer
			* - ODBX_TYPE_INTEGER: Signed 32 bit integer
			* - ODBX_TYPE_BIGINT: Signed 64 bit integer
			* - ODBX_TYPE_DECIMAL: Exact signed numeric values with us
			er defined precision
			*
			* Approximate numeric values:
			* - ODBX_TYPE_REAL: Approximate numeric values (signed) wit
			h 32 bit precision
			* - ODBX_TYPE_DOUBLE: Approximate numeric values (signed) w
			ith 64 bit precision
			* - ODBX_TYPE_FLOAT: Approximate numeric values (signed) wi
			th user defined precision
			*
			* String values:
			* - ODBX_TYPE_CHAR: Fixed number of characters
			* - ODBX_TYPE_NCHAR: Fixed number of characters using a nat
			ional character set
			* - ODBX_TYPE_VARCHAR: Variable number of characters
			* - ODBX_TYPE_NVARCHAR: Variable number of characters using
			a national character set
			*
			* Large objects:
			* - ODBX_TYPE_CLOB: Large text object
			* - ODBX_TYPE_NCLOB: Large text object using a national cha
			racter set
			* - ODBX_TYPE_XML: XML tree in text format
			* - ODBX_TYPE_BLOB: Large binary object
			*
			* Date and time values:
			* - ODBX_TYPE_TIME: Time including hours, minutes and secon
			ds
			* - ODBX_TYPE_TIME_TZ: Time with timezone information
			* - ODBX_TYPE_TIMESTAMP: Date and time
			* - ODBX_TYPE_TIMESTAMP_TZ: Date and time with timezone inf
			ormation
			* - ODBX_TYPE_DATE: Date including year, month and day
			* - ODBX_TYPE_INTERVAL: Date interval
			*
			* Arrays and sets:
			* - ODBX_TYPE_ARRAY: Array of values
			* - ODBX_TYPE_MULTISET: Associative arrays
			*
			* External links:
			* - ODBX_TYPE_DATALINK: URI locators like URL links
			*
			* Data types provided by database implementations which are
			not covered
			* by the SQL2003 standard are subsumed as ODBX_TYPE_UNKNOWN
			.
			*
	* @param pos Position of column in result set		* @param pos Position of column in result set
	* @return Column type		* @return Column type
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	* @see odbxtype		* @see odbxtype
	*/		*/
	odbxtype columnType( unsigned long pos );		odbxtype columnType( unsigned long pos ) throw( std::excepti on );
	/**		/**
	* Returns the size of the content in the current row at the specified postion.		* Returns the size of the content in the current row at the specified postion.
	*		*
			* The field is part of the current row which was retrieved
			by the
			* latest call to getRow() and is specified by the column in
			dex given by
			* \a pos.
			*
	* @param pos Position of column in result set		* @param pos Position of column in result set
	* @return Size of the data in bytes		* @return Size of the data in bytes
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	*/		*/
	unsigned long fieldLength( unsigned long pos );		unsigned long fieldLength( unsigned long pos ) throw( std::e xception );
	/**		/**
	* Returns a pointer to the content in the current row at th e specified postion.		* Returns a pointer to the content in the current row at th e specified postion.
	*		*
			* This function returns a pointer to the field data specifi
			ed by the
			* column index \a pos. The field is part of the current row
			which was
			* retrieved by the latest call to getRow(). All values exce
			pt binary
			* objects are handed back as strings terminated by the zero
			character.
			* This does also apply to numeric values, dates, etc. They
			have to be
			* converted to their binary machine dependent representatio
			n before
			* arithmetic operations can be done. If a value is undefine
			d, i.e.
			* "NULL" is attached to the field in the database, an equiv
			alent NULL
			* pointer is returned.
			*
	* @param pos Position of column in result set		* @param pos Position of column in result set
	* @return Pointer to the data		* @return Pointer to the data
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	*/		*/
	const char* fieldValue( unsigned long pos );		const char* fieldValue( unsigned long pos ) throw( std::exce ption );
	/**		/**
	* Create a large object instance if supported by the databa		* Creates a large object instance if supported by the datab
	se.		ase.
			*
			* Returns a Lob class instance representing a large object
			stored in
			* the database. It references the large object and provided
			methods for
			* accessing and modifying its content.
			*
			* The parameter required by this method must be the value r
			eturned by
			* the fieldValue() method of a large object column.
			*
			* This method must only be used if the underlying driver st
			ates that it
			* supports large objects via the Conn::getCapabilities(). O
			therwise,
			* the content can be retrieved directly by the fieldValue()
			method.
	*		*
	* @param value Pointer to the content of a field returned b y fieldValue()		* @param value Pointer to the content of a field returned b y fieldValue()
	* @return Large object instance		* @return Large object instance
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	* @see Lob		* @see Lob
	*/		*/
	Lob getLob( const char* value );		Lob getLob( const char* value ) throw( std::exception );
	};		};
	/**		/**
	* Statement object.		* Statement object.
			*
			* @author Norbert Sendetzky <norbert@linuxnetworks.de>
			* @version 1.0
	*/		*/
	class Stmt		class Stmt
	{		{
	protected:		friend class Conn;
	/**		/**
	* Private implementation of object.		* Private implementation of object.
	*/		*/
	Stmt_Impl* m_impl;		Stmt_Iface* m_impl;
	/**		/**
	* Reference counter of copies.		* Reference counter of copies.
	*/		*/
	int* m_ref;		int* m_ref;
			protected:
	/**		/**
	* Default constructor.		* Default constructor.
	*		*
			* The default constructor isn't part of the public interfac
			e as the
			* object must not be created manually. Instead, the Conn::c
			reate()
			* method is a factory for instances of the Stmt class.
			*
	* @return Statement instance		* @return Statement instance
	*/		*/
	Stmt();		Stmt() throw() {};
	/**		/**
	* Create statement instance.		* Creates a statement instance.
			*
			* The constructor isn't part of the public interface as the
			object must
			* not be created manually. Instead, the Conn::create() met
			hod is a
			* factory for instances of the Stmt class.
	*		*
	* @param impl Pointer to private implementation		* @param impl Pointer to private implementation
			* @throws std::exception If an error occures
	* @return Statement instance		* @return Statement instance
	*/		*/
	Stmt( Stmt_Impl* impl );		Stmt( Stmt_Iface* impl ) throw( std::exception );
	friend class Conn;
	public:		public:
	/**		/**
	* Statement objects which can be created.		* Statement objects which can be created.
			*
			* Currently, only simple processing of statements is suppor
			ted which
			* means that the statement sent to the database server cons
			ists of the
			* statement and the parameters in text form. Later on, also
			prepared
			* statements will be available which separates parsing and
			execution
			* with different parameters.
	*/		*/
	enum Type { Simple };		enum Type { Simple };
	/**		/**
	* Destroy statement instance if no other references exist.		* Destroys the statement instance if no other references ex
			ist.
			*
			* Each statement object uses a reference counter to remembe
			r if the
			* internal variables are shared with other objects. If this
			isn't the
			* case or if this object is the last one referencing the va
			riables,
			* the object is cleanup up and the allocated memory freed.
			*/
			~Stmt() throw();
			/**
			* Copy constructor.
			*
			* Enables the transfer of the internal state of an object \
			a ref of the same
			* type to this object. Both objects share the same variable
			s
			* and the reference counter afterwards. The reference count
			er is
			* incremented each time an object is copied and will be dec
			remented if
			* it is destroyed.
			*
			* @param ref Original statement object instance
	*/		*/
	~Stmt();		Stmt( const Stmt& ref ) throw();
	/**		/**
	* Assign statement instance to another one.		* Assigns a statement instance to another one.
			*
			* Assigns the internal state of an object \a ref of the sam
			e type to this
			* object. Both objects share the same variables and the
			* reference counter afterwards. The reference counter is in
			cremented
			* each time an object is copied and will be decremented if
			it is
			* destroyed.
	*		*
	* @param ref Stmt instance		* @param ref Stmt instance
	* @return Statement reference of this instance		* @return Statement reference of this instance
	*/		*/
	Stmt& operator=( const Stmt& ref );		Stmt& operator=( const Stmt& ref ) throw();
	/**		/**
	* Execute statement and return Result instance.		* Executes a statement and returns a Result instance.
			*
			* Sends the necessary data to the database server which wil
			l execute
			* the statement and return one or more result sets afterwar
			ds. The
			* result sets can be fetched via the returned Result object
			.
	*		*
	* @return Result instance		* @return Result instance
			* @throws OpenDBX::Exception If the underlying database lib rary returns an error
	* @see Result		* @see Result
	*/		*/
	Result execute();		Result execute() throw( std::exception );
	};		};
	/**		/**
	* Handling a connection to a database.		* Encapsulates a connection to a database.
			*
			* @author Norbert Sendetzky <norbert@linuxnetworks.de>
			* @version 1.0
	*/		*/
	class Conn		class Conn
	{		{
	protected:
	/**		/**
	* Private implementation of object.		* Private implementation of the connection object.
	*/		*/
	Conn_Impl* m_impl;		Conn_Iface* m_impl;
	/**		/**
	* Reference counter of copies.		* Reference counter of copies.
	*/		*/
	int* m_ref;		int* m_ref;
	public:		public:
	/**		/**
	* Default constructor.		* The default constructor for newly created connection obje
			cts without
			* parameters.
	*		*
	* @return Connection instance		* This is method is provided to enable programmers to use c
	*/		onnection
	Conn();		* objects as member variables of other classes. They are in
			itialized
	/**		* at construction time of the encapsulating object when no
	* Build connection object using C string parameters.		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 v
			ia one of
			* the other constructors. Calling one of the member functio
			ns of an
			* instance created by the default constructor isn't possibl
			e and will
			* throw an exception.
			*
			* @return Empty connection instance
			* @see #Conn( const char*, const char*, const char* )
			* @see #Conn( const string&, const string&, const string& )
			*/
			Conn() throw();
			/**
			* Creates a connection object using C style string paramete
			rs.
			*
			* Initializes a new connection using the parameters \a back
			end, \a host and
			* \a port, but doesn't open the connection to the database
			yet. This method
			* allows C style strings as values for all parameters. Anot
			her 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 \a backend is the name of the driver the Op
			enDBX library
			* should use to connect to a database. The name must be one
			of the
			* implemented and available drivers on the system and is ca
			se sensitive.
			* All driver names are in lower case, e.g. "mysql".
			*
			* Depending on the database driver, \a host can have differ
			ent meanings.
			* Normally, it's the name or IP address of the server hosti
			ng the
			* database server application. In case of serverless databa
			se
			* implementations like SQLite it's the directory path where
			the database
			* file is located. The path must contain the platform speci
			fic path
			* separators like slash ("/") on Unix-like systems and back
			slash ("\")
			* on Windows systems. Also the path must end with the path
			separator
			* like "/path/to/file/".
			*
			* Furthermore \a port can be the number or name the databas
			e server
			* application is listening to. If a name instead of the num
			ber is
			* allowed depends on the database client library but the nu
			mber as
			* string does always work. If an empty string is given, the
			default
			* port of the database server application is used by the da
			tabase
			* client library.
	*		*
	* @param backend Name of the backend module to use		* @param backend Name of the backend module to use
	* @param host Name or IP address of the database server		* @param host Name or IP address of the database server
	* @param port Name or number of the port used by the databa se server		* @param port Name or number of the port used by the databa se server
	* @return Connection instance		* @return Connection instance
	*/		* @throws std::invalid_argument If the object was only init
	Conn( const char* backend, const char* host = "", const char		ialized by the default constructor
	* port = "" );		* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	/**		* @see #Conn( const string&, const string&, const string& )
	* Build connection object using C++ string parameters.		*/
			Conn( const char* backend, const char* host = "", const char
			* port = "" ) throw( std::exception );
			/**
			* Creates a connection object using C++ style string parame
			ters.
			*
			* 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. An
			other
			* construtor for C style strings is also available. It retu
			rns a new
			* connection instance, which can be used to query options i
			mplemented
			* by the driver or to create a statement. In case of an err
			or, it throws
			* an OpenDBX exception with error message, code and severit
			y.
			*
			* The parameter \a backend is the name of the driver the Op
			enDBX library
			* should use to connect to a database. The name must be one
			of the
			* implemented and available drivers on the system and is ca
			se sensitive.
			* All driver names are in lower case, e.g. "mysql".
			*
			* Depending on the database driver, \a host can have differ
			ent mearings.
			* Normally, it's the name or IP address of the server hosti
			ng the
			* database server application. In case of serverless databa
			se
			* implementations like SQLite it's the directory path where
			the database
			* file is located. The path must contain the platform speci
			fic path
			* separators like slash ("/") on Unix-like systems and back
			slash ("\")
			* on Windows systems. Also the path must end with the path
			separator
			* like "/path/to/file/".
			*
			* Furthermore \a port can be the number or name the databas
			e server
			* application is listening to. If a name instead of the num
			ber is
			* allowed depends on the database client library but the nu
			mber as
			* string does always work. If an empty string is given, the
			default
			* port of the database server application is used by the da
			tabase
			* client library.
	*		*
	* @param backend Name of the backend module to use		* @param backend Name of the backend module to use
	* @param host Name or IP address of the database server		* @param host Name or IP address of the database server
	* @param port Name or number of the port used by the databa se server		* @param port Name or number of the port used by the databa se server
	* @return Connection instance		* @return Connection instance
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
			* @see #Conn( const char*, const char*, const char* )
	*/		*/
	Conn( const string& backend, const string& host = "", const string& port = "" );		Conn( const string& backend, const string& host = "", const string& port = "" ) throw( std::exception );
	/**		/**
	* Destroy connection instance if no other references exist.		* Destroys the connection instance if no other references e
			xist.
			*
			* Each connection object uses a reference counter to rememb
			er if the
			* connection is shared with other objects. If this isn't th
			e case or
			* if this object is the last one referencing the connection
			, the
			* connection is closed and the allocated memory is freed.
	*/		*/
	~Conn();		~Conn() throw();
	/**		/**
	* Assign connection instance to another one.		* Copy constructor.
			*
			* Enables the transfer of the internal state of an object \
			a ref of the same
			* type to this object. Both objects share the same database
			connection
			* and the reference counter afterwards. The reference count
			er is
			* incremented each time an object is copied and will be dec
			remented if
			* it is destroyed.
			*
			* @param ref Original connection object instance
			*/
			Conn( const Conn& ref ) throw();
			/**
			* Assigns a connection instance to another one.
			*
			* Assigns the internal state of an object \a ref of the sam
			e type to this
			* object. Both objects share the same database connection a
			nd the
			* reference counter afterwards. The reference counter is in
			cremented
			* each time an object is copied and will be decremented if
			it is
			* destroyed.
	*		*
	* @param ref Connection instance		* @param ref Connection instance
	* @return Connection reference of this instance		* @return Connection reference of this instance
	*/		*/
	Conn& operator=( const Conn& ref );		Conn& operator=( const Conn& ref ) throw();
	/**		/**
	* Log into database server and select database using C stri		* Authenticates the user and selects the database using C s
	ng parameters.		tyle string
			* parameters.
			*
			* After initializing the object instance with one of the co
			nstructors
			* 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 connecti
			on 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 use
			d to select
			* the database all further commands are operating on. The d
			atabase is
			* the container for the tables, views, etc., which store th
			e 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 da
			tabase
			* server will allow the user to operate on the selected dat
			abase and
			* its tables provided the user has permissions to read and/
			or modify
			* the content.
			*
			* The \a method parameter can be used to select different m
			ethods of
			* authentication. At the moment, only simple authentication
			* (ODBX_BIND_SIMPLE) with user name and password is availab
			le.
	*		*
	* @param database Name of the database managed by the datab ase server		* @param database Name of the database managed by the datab ase server
	* @param who Name of the user account known by the database server		* @param who Name of the user account known by the database server
	* @param cred Necessary credential which belongs to the use r account		* @param cred Necessary credential which belongs to the use r account
	* @param method Method used for authentication		* @param method Method used for authentication
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	void bind( const char* database, const char* who = "", const char* cred = "", odbxbind method = ODBX_BIND_SIMPLE );		void bind( const char* database, const char* who = "", const char* cred = "", odbxbind method = ODBX_BIND_SIMPLE ) throw( std::exceptio n );
	/**		/**
	* Log into database server and select database using C++ st		* Authenticates the user and selects the database using C++
	ring parameters.		style string
			* parameters.
			*
			* After initializing the object instance with one of the co
			nstructors
			* 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 connecti
			on to the
			* database server. This method accepts C++ style strings fo
			r the
			* database name, the user name and the password.
			*
			* The first parameter, the name of the database will be use
			d to select
			* the database all further commands are operating on. The d
			atabase is
			* the container for the tables, views, etc., which store th
			e 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 da
			tabase
			* server will allow the user to operate on the selected dat
			abase and
			* its tables provided the user has permissions to read and/
			or modify
			* the content.
			*
			* The \a method parameter can be used to select different m
			ethods of
			* authentication. At the moment, only simple authentication
			* (ODBX_BIND_SIMPLE) with user name and password is availab
			le.
	*		*
	* @param database Name of the database managed by the datab ase server		* @param database Name of the database managed by the datab ase server
	* @param who Name of the user account known by the database server		* @param who Name of the user account known by the database server
	* @param cred Necessary credential which belongs to the use r account		* @param cred Necessary credential which belongs to the use r account
	* @param method Method used for authentication		* @param method Method used for authentication
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	void bind( const string& database, const string& who = "", c onst string& cred = "", odbxbind method = ODBX_BIND_SIMPLE );		void bind( const string& database, const string& who = "", c onst string& cred = "", odbxbind method = ODBX_BIND_SIMPLE ) throw( std::ex ception );
	/**		/**
	* Close connection to the database server.		* Releases the connection to the database and resets the au
			thentication
			* status.
			*
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	void unbind();		void unbind() throw( std::exception );
	/**		/**
	* Clean up connection object.		* Cleans up the connection object.
			*
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	void finish();		void finish() throw( std::exception );
	/**		/**
	* Test if the database driver module does understand certai		* Tests if the database driver module does understand certa
	n extensions.		in extensions.
			*
			* The OpenDBX library consists of a basic set of functions
			that must be
			* implemented by all drivers and optional sets for addition
			al
			* functionality. This method allows an application to ask t
			he driver
			* selected by the first parameter of the constructor of thi
			s object if
			* it supports one or more optional sets. The available sets
			and its
			* constants are:
			*
			* - ODBX_CAP_BASIC\n
			* The core function set which have to be implemented by a
			ll backends.
			* It consists of all functions necessary to connect to, s
			end textual
			* queries to and process simple results returned from the
			database
			* server as well as error handling functions.
			* - ODBX_CAP_LO\n
			* The function set for handling large objects whose conte
			nt isn't
			* accessible by the basic function. Currently, Firebird/I
			nterbase
			* and Oracle requires using the LOB functions.
			*
			* The basic set makes sure that all drivers can handle conn
			ections 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 la
			rge objects
			* not via the basic functions. Instead, the Result::fieldVa
			lue() method
			* returns only a handle to the large object and reading or
			modifying
			* the content of this data object requires calling addition
			al methods.
	*		*
	* @param cap Constant of the capability		* @param cap Constant of the capability
	* @return True if supported, false if not		* @return True if supported, false if not
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	bool getCapability( odbxcap cap );		bool getCapability( odbxcap cap ) throw( std::exception );
	/**		/**
	* Get the value of certain options provided by the database		* Gets the value of a certain option provided by the databa
	driver module.		se driver module.
			*
			* It asks the backend module for implemented options and th
			eir 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 t
			he database
			* server is established by calling bind().
			*
			* There are several option values defined as named constant
			s in the
			* opendbx/api.h header file. A few of them are for informat
			ional purpose
			* only while most of the options can also be set to differe
			nt values
			* by setOption() to change the behavior of the backend modu
			le. These
			* options are:
			*
			* - ODBX_OPT_API_VERSION\n
			* The API version implemented by the backend. It returns
			a five digit
			* number representing the API version of the backend modu
			le 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\n
			* If it is safe to use this backend and especially the na
			tive database
			* client library in an application which uses threads whe
			re more than
			* one thread opens database connections via the OpenDBX l
			ibrary.
			* - ODBX_OPT_TLS\n
			* The database client library may support transmitting al
			l data
			* securely by encrypting the network traffic via SSL or T
			LS.
			* - ODBX_OPT_MULTI_STATEMENTS\n
			* The database server may be able to support multiple SQL
			statements
			* in one string sent to the database.
			* - ODBX_OPT_PAGED_RESULTS\n
			* All database servers and client libraries are able to t
			ransfer the
			* records row by row. Some of them can also transfer mult
			iple rows
			* or even all at once to minimize server load, network tr
			affic and
			* latency. The downside of this is an increased memory co
			nsumption.
			* - ODBX_OPT_COMPRESS\n
			* Support of compressed network traffic between database
			client and
			* server. This can lead to higher throughput if the netwo
			rk is the
			* bottleneck.
			* - ODBX_OPT_MODE\n
			* Some database servers support different modes of operat
			ion, e.g.
			* modes for compliance to other SQL implementations or co
			mpletely
			* different query languages.
			*
			* The parameter \a value must be a pointer to an integer va
			riable 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 fo
			r a supported
			* option or ODBX_DISABLE for an option which isn't supporte
			d.
	*		*
	* @param option Constant of the option		* @param option Constant of the option
	* @param value Pointer to memory where the result is stored		* @param value Pointer to memory where the result is stored
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	void getOption( odbxopt option, void* value );		void getOption( odbxopt option, void* value ) throw( std::ex ception );
	/**		/**
	* Set certain options provided by the database driver modul		* Sets a certain option provided by the database driver mod
	e.		ule.
			*
			* Changes the value of the specified option in the backend
			module or
			* the native database library. Before trying to set an opti
			on, it should
			* be tested with getOption() first to ensure that it is sup
			ported by
			* the backend. Almost all options need to be set before con
			necting to
			* the database server using bind() to take any effect.
			*
			* There are several option values defined as named constant
			s in the
			* opendbx/api.h header file. The possible options are:
			*
			* - ODBX_OPT_TLS\n
			* Use encryption to transmit all data securely over the n
			etwork via
			* SSL or TLS. This option can be set to ODBX_TLS_NEVER (t
			he default
			* value) to prevent encrpytion, ODBX_TLS_ALWAYS to enforc
			e encryption
			* and to fail if it can't be used between the client libr
			ary and the
			* server or ODBX_TLS_TRY to use encryption if possible wi
			th the
			* option to fall back to a connection which isn't encrypt
			ed.
			* - ODBX_OPT_MULTI_STATEMENTS\n
			* Enables the database server to accept multiple statemen
			ts 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\n
			* All database servers and client libraries are able to t
			ransfer the
			* records row by row. Some of them can also transfer mult
			iple rows
			* or even all at once to minimize server load, network tr
			affic and
			* latency. The downside of this is an increased memory co
			nsumption.
			* If paged results are supported by the backend, passing
			positive
			* values will fetch the specified number of records at on
			ce from the
			* database server. The value of zero ("0") is special in
			this case
			* because it asks the backend module to retrieve all reco
			rds at once.
			* - ODBX_OPT_COMPRESS\n
			* Enable compressed network traffic between database clie
			nt and
			* server. This can maximize the throughput if the network
			is the
			* bottleneck. Pass an integer variable with ODBX_ENABLE t
			o enable
			* compression or with ODBX_DISABLE to disable it for this
			connection.
			* - ODBX_OPT_MODE\n
			* Some database servers support different modes of operat
			ion, e.g.
			* modes for compliance to other SQL implementations or co
			mpletely
			* different query languages. The value for this option mu
			st point to
			* a zero terminated string.
			*
			* If not stated otherwise, the type of the variable passed
			to the second
			* parameter named \a value must be an integer pointer. Its
			values
			* must be in the range specified by the option being change
			d.
	*		*
	* @param option Constant of the option		* @param option Constant of the option
	* @param value Pointer to memory which contains the new val ue		* @param value Pointer to memory which contains the new val ue
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	void setOption( odbxopt option, void* value );		void setOption( odbxopt option, void* value ) throw( std::ex ception );
	/**		/**
	* Escape potentially dangerous characters in user input usi		* Escapes potentially dangerous characters in user input us
	ng a C++ string parameter.		ing a C style buffer.
			*
			* For preventing SQL injection attacks which can have desas
			terous
			* effects, all text input that will be part of an SQL state
			ment must be
			* escaped. This does also apply to user content that is alr
			eady stored
			* in the database and should be copied to another record or
			stored
			* again as the escaping is removed before the database serv
			er writes
			* the content to disk.
			*
			* The first parameter must contain the character sequence t
			hat 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
			* \a to, which have to be also an C++ style string. After t
			ransforming
			* the input to an escaped string, the result may be more th
			en twice
			* the size of the original input. The additional escape seq
			uences
			* 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 esc
			aped string
			* afterwards is also returned by this method to providing t
			he possibility
			* to write more elegant code.
	*		*
	* @param from Input string with which may contain dangerous characters		* @param from Input string with which may contain dangerous characters
			* @param fromlen Size of the input string to escape in byte s
	* @param to String instance where the escaped characters sh ould be written to		* @param to String instance where the escaped characters sh ould be written to
	* @return Reference to the second parameter containing the escaped characters		* @return Reference to the second parameter containing the escaped characters
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	string& escape( const string& from, string& to );		string& escape( const char* from, unsigned long fromlen, str ing& to ) throw( std::exception );
	/**		/**
	* Escape potentially dangerous characters in user input usi		* Escapes potentially dangerous characters in user input us
	ng a C style buffer.		ing a C++
			* style string parameter.
			*
			* For preventing SQL injection attacks which can have desas
			terous
			* effects, all text input that will be part of an SQL state
			ment must be
			* escaped. This does also apply to user content that is alr
			eady stored
			* in the database and should be copied to another record or
			stored
			* again as the escaping is removed before the database serv
			er writes
			* the content to disk.
			*
			* The first parameter must contain the character sequence t
			hat 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
			* \a to, which have to be also an C++ style string. After t
			ransforming
			* the input to an escaped string, the result may be more th
			en twice
			* the size of the original input. The additional escape seq
			uences
			* 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 esc
			aped string
			* afterwards is also returned by this method to providing t
			he possibility
			* to write more elegant code.
	*		*
	* @param from Input string with which may contain dangerous characters		* @param from Input string with which may contain dangerous characters
	* @param fromlen Size of the input string to escape in byte s
	* @param to String instance where the escaped characters sh ould be written to		* @param to String instance where the escaped characters sh ould be written to
	* @return Reference to the second parameter containing the escaped characters		* @return Reference to the second parameter containing the escaped characters
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	*/		*/
	string& escape( const char* from, unsigned long fromlen, str ing& to );		string& escape( const string& from, string& to ) throw( std: :exception );
	/**		/**
	* Create statement object from SQL text string using a C st		* Creates a statement object from a SQL text string using a
	yle buffer.		C style buffer.
			*
			* This method returns an instance of the Stmt class that co
			ntains 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::exec
			ute(). Later
			* on also prepared statements will be possible which are pa
			rsed by the
			* database server when creating the object and only the par
			ameters
			* will be sent to the database server on execution. This ca
			n speed up
			* processing especially if the statement is executed multip
			le times
			* with different content for the parameters.
			*
			* The parameter named \a sql must contain the SQL text stri
			ng 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 stateme
			nts, please
			* have a look at the documentation of your database server.
			*
			* The length of the statement excluding the trailing "0" by
			te should
			* be given via the second parameter \a 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 thi
			s case, the
			* length of the string is calculated internally by this fun
			ction before
			* the statement is given to the native database library.
			*
			* Via the last parameter it can be selected how the stateme
			nt should
			* be treated internally by the OpenDBX and the native datab
			ase library.
			* Currently, only simple processing is available which send
			s 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 fi
			rst 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.
	*		*
	* @param sql SQL text string containing a valid statement u nderstood by the database server		* @param sql SQL text string containing a valid statement u nderstood by the database server
	* @param size Size of the SQL text string in bytes		* @param size Size of the SQL text string in bytes
	* @param type Type of statements object that should be crea		* @param type Type of statement object that should be creat
	ted		ed
	* @return Statement instance		* @return Statement instance bound to this connection
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	* @see Stmt		* @see Stmt
	*/		*/
	Stmt create( const char* sql, unsigned long size = 0, Stmt:: Type type = Stmt::Simple );		Stmt create( const char* sql, unsigned long size = 0, Stmt:: Type type = Stmt::Simple ) throw( std::exception );
	/**		/**
	* Create statement object from SQL text string using a C++		* Creates a statement object from a SQL text string using a
	string.		C++ string.
			*
			* This method returns an instance of the Stmt class that co
			ntains 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::exec
			ute(). Later
			* on also prepared statements will be possible which are pa
			rsed by the
			* database server when creating the object and only the par
			ameters
			* will be sent to the database server on execution. This ca
			n speed up
			* processing especially if the statement is executed multip
			le times
			* with different content for the parameters.
			*
			* The parameter named \a sql must contain the SQL text stri
			ng 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 stateme
			nts, please
			* have a look at the documentation of your database server.
			*
			* Via the last parameter \a type it can be selected how the
			statement should
			* be treated internally by the OpenDBX and the native datab
			ase library.
			* Currently, only simple processing is available which send
			s 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 fi
			rst 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.
	*		*
	* @param sql SQL text string containing a valid statement u nderstood by the database server		* @param sql SQL text string containing a valid statement u nderstood by the database server
	* @param type Type of statements object that should be crea		* @param type Type of statement object that should be creat
	ted		ed
	* @return Statement instance		* @return Statement instance bound to this connection
			* @throws std::invalid_argument If the object was only init
			ialized by the default constructor
			* @throws OpenDBX::Exception If the underlying database lib
			rary returns an error
	* @see Stmt		* @see Stmt
	*/		*/
	Stmt create( const string& sql, Stmt::Type type = Stmt::Simp le );		Stmt create( const string& sql, Stmt::Type type = Stmt::Simp le ) throw( std::exception );
	};		};
	} // namespace OpenDBX		} // namespace OpenDBX
	} // extern C++		} // extern C++
	#endif		#endif
End of changes. 141 change blocks.
	136 lines changed or deleted		1477 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/