IBPP, a C++ API for Firebird Server Code

///////////////////////////////////////////////////////////////////////////////
//
//	File    : $Id$
//	Subject : IBPP public header file. This is _the_ only file you include in
//			  your application files when developing with IBPP.
//
///////////////////////////////////////////////////////////////////////////////
//
//	(C) Copyright 2000-2009 T.I.P. Group S.A. and the IBPP Team (www.ibpp.org)
//
//	The contents of this file are subject to the IBPP License (the "License");
//	you may not use this file except in compliance with the License.  You may
//	obtain a copy of the License at http://www.ibpp.org or in the 'license.txt'
//	file which must have been distributed along with this file.
//
//	This software, distributed under the License, is distributed on an "AS IS"
//	basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See the
//	License for the specific language governing rights and limitations
//	under the License.
//
//	Contributor(s):
//
//		Olivier Mascia, main coding
//		Matt Hortman, initial linux port
//		Mark Jordan, design contributions
//		Maxim Abrashkin, enhancement patches
//		Torsten Martinsen, enhancement patches
//		Michael Hieke, darwin (OS X) port, enhancement patches
//		Val Samko, enhancement patches and debugging
//		Mike Nordell, invaluable C++ advices
//		Claudio Valderrama, help with not-so-well documented IB/FB features
//		Many others, excellent suggestions, bug finding, and support
//
///////////////////////////////////////////////////////////////////////////////
//
//	COMMENTS
//	Tabulations should be set every four characters when editing this file.
//
//	When compiling a project using IBPP, the following defines should be made
//	on the command-line (or in makefiles) according to the OS platform and
//	compiler used.
//
//	Select the platform:	IBPP_WINDOWS | IBPP_LINUX | IBPP_DARWIN
//
///////////////////////////////////////////////////////////////////////////////

#ifndef __IBPP_H__
#define __IBPP_H__

#if !defined(IBPP_WINDOWS) && !defined(IBPP_LINUX) && !defined(IBPP_DARWIN)
#error Please define IBPP_WINDOWS/IBPP_LINUX/IBPP_DARWIN before compiling !
#endif

#if !defined(__BCPLUSPLUS__) && !defined(__GNUC__) \
	&& !defined(_MSC_VER) && !defined(__DMC__)
#error Your compiler is not recognized.
#endif

#if defined(IBPP_LINUX) || defined(IBPP_DARWIN)
#define IBPP_UNIX	// IBPP_UNIX stands as a common denominator to *NIX flavours
#endif

// IBPP is written for 32 bits systems or higher.
// The standard type 'int' is assumed to be at least 32 bits.
// And the standard type 'short' is assumed to be exactly 16 bits.
// Everywhere possible, where the exact size of an integer does not matter,
// the standard type 'int' is used. And where an exact integer size is required
// the standard exact precision types definitions of C 99 standard are used.

#if defined(_MSC_VER) || defined(__DMC__) || defined(__BCPLUSPLUS__)
// C99 §7.18.1.1 Exact-width integer types (only those used by IBPP)
#if defined(_MSC_VER) && (_MSC_VER < 1300)	// MSVC 6 should be < 1300
	typedef short int16_t;
	typedef int int32_t;
	typedef unsigned int uint32_t;
#else
	typedef __int16 int16_t;
	typedef __int32 int32_t;
	typedef unsigned __int32 uint32_t;
#endif
	typedef __int64 int64_t;
#else
	#include <stdint.h>			// C99 (§7.18) integer types definitions
#endif

#if !defined(_)
#define _(s)	s
#endif

#include <exception>
#include <string>
#include <vector>

namespace IBPP
{
	//	Typically you use this constant in a call IBPP::CheckVersion as in:
	//	if (! IBPP::CheckVersion(IBPP::Version)) { throw .... ; }
	const uint32_t Version = (3<<24) + (0<<16) + (0<8) + 0; // Version == 3.0.0.0

	//	Dates range checking
	const int MinDate = -693594;	//  1 JAN 0001
	const int MaxDate = 2958464;	// 31 DEC 9999

	//	Transaction Access Modes
	enum TAM {amWrite, amRead};

	//	Transaction Isolation Levels
	enum TIL {ilConcurrency, ilReadDirty, ilReadCommitted, ilConsistency};

	//	Transaction Lock Resolution
	enum TLR {lrWait, lrNoWait};

	// Transaction Table Reservation
	enum TTR {trSharedWrite, trSharedRead, trProtectedWrite, trProtectedRead};

	//	Prepared Statement Types
	enum STT {stUnknown, stUnsupported,
		stSelect, stInsert, stUpdate, stDelete,	stDDL, stExecProcedure,
		stSelectUpdate, stSetGenerator, stSavePoint};

	//	SQL Data Types
	enum SDT {sdArray, sdBlob, sdDate, sdTime, sdTimestamp, sdString,
		sdSmallint, sdInteger, sdLargeint, sdFloat, sdDouble};

	//	Array Data Types
	enum ADT {adDate, adTime, adTimestamp, adString,
		adBool, adInt16, adInt32, adInt64, adFloat, adDouble};

	// Database::Shutdown Modes
	enum DSM {dsForce, dsDenyTrans, dsDenyAttach};

	// Service::StartBackup && Service::StartRestore Flags
	enum BRF {
		brVerbose = 0x1,
		// Backup flags
		brIgnoreChecksums = 0x100, brIgnoreLimbo = 0x200,
		brMetadataOnly = 0x400, brNoGarbageCollect = 0x800,
		brNonTransportable = 0x1000, brConvertExtTables = 0x2000,
		// Restore flags
		brReplace = 0x10000, brDeactivateIdx = 0x20000,
		brNoShadow = 0x40000, brNoValidity = 0x80000,
		brPerTableCommit = 0x100000, brUseAllSpace = 0x200000
	};

	// Service::Repair Flags
	enum RPF
	{
		// Mandatory and mutually exclusives
		rpMendRecords = 0x1, rpValidatePages = 0x2, rpValidateFull = 0x4,
		// Options
		rpReadOnly = 0x100, rpIgnoreChecksums = 0x200, rpKillShadows = 0x400
	};

	// TransactionFactory Flags
	enum TFF {tfIgnoreLimbo = 0x1, tfAutoCommit = 0x2, tfNoAutoUndo = 0x4};

	/* IBPP never return any error codes. It throws exceptions.
	 * On database engine reported errors, an IBPP::SQLException is thrown.
	 * In all other cases, IBPP throws IBPP::LogicException.
	 * Also note that the runtime and the language might also throw exceptions
	 * while executing some IBPP methods. A failing new operator will throw
	 * std::bad_alloc, IBPP does nothing to alter the standard behaviour.
	 *
	 *                    std::exception
	 *                           |
	 *                   IBPP::Exception
	 *                 /                 \
	 *    IBPP::LogicException    IBPP::SQLException
	 *             |
	 *      IBPP::WrongType
	 */

	class Exception : public std::exception
	{
	public:
		virtual const char* Origin() const = 0;
		virtual const char* what() const = 0;
		virtual ~Exception();
	};

	class LogicException : public Exception
	{
	public:
		virtual ~LogicException();
	};

	class SQLException : public Exception
	{
	public:
		virtual int SqlCode() const = 0;
		virtual int EngineCode() const = 0;

		virtual ~SQLException();
	};

	class WrongType : public LogicException
	{
	public:
		virtual ~WrongType();
	};

	/* Classes Date, Time, Timestamp and DBKey are 'helper' classes.  They help
	 * in retrieving or setting some special SQL types. Dates, times and dbkeys
	 * are often read and written as strings in SQL scripts. When programming
	 * with IBPP, we handle those data with these specific classes, which
	 * enhance their usefullness and free us of format problems (M/D/Y, D/M/Y,
	 * Y-M-D ?, and so on...). */

	/* Class Date represent purely a Date (no time part specified). It is
	 * usefull in interactions with the SQL DATE type of Interbase.  You can add
	 * or substract a number from a Date, that will modify it to represent the
	 * correct date, X days later or sooner. All the Y2K details taken into
	 * account.
	 * The full range goes from integer values IBPP::MinDate to IBPP::MaxDate
	 * which means from 01 Jan 0001 to 31 Dec 9999. ( Which is inherently
	 * incorrect as this assumes Gregorian calendar. ) */

	class Timestamp;	// Cross-reference between Timestamp, Date and Time

	class Date
	{
	protected:
		int mDate;	// The date : 1 == 1 Jan 1900

	public:
		void Clear()	{ mDate = MinDate - 1; };
		void Today();
		void SetDate(int year, int month, int day);
		void SetDate(int dt);
		void GetDate(int& year, int& month, int& day) const;
		int GetDate() const	{ return mDate; }
		int Year() const;
		int Month() const;
		int Day() const;
		void Add(int days);
		void StartOfMonth();
		void EndOfMonth();

		Date()			{ Date::Clear(); };
		Date(int dt)	{ SetDate(dt); }
		Date(int year, int month, int day);
		Date(const Date&);							// Copy Constructor
		Date& operator=(const Timestamp&);			// Timestamp Assignment operator
		Date& operator=(const Date&);				// Date Assignment operator

		bool operator==(const Date& rv)	const { return mDate == rv.GetDate(); }
		bool operator!=(const Date& rv)	const { return mDate != rv.GetDate(); }
		bool operator<(const Date& rv) const { return mDate < rv.GetDate(); }
		bool operator>(const Date& rv) const { return mDate > rv.GetDate(); }

		virtual ~Date() { };
	};

	/* Class Time represent purely a Time. It is usefull in interactions
	 * with the SQL TIME type of Interbase. */

	class Time
	{
	protected:
		int mTime;	// The time, in ten-thousandths of seconds since midnight

	public:
		void Clear()	{ mTime = 0; }
		void Now();
		void SetTime(int hour, int minute, int second, int tenthousandths = 0);
		void SetTime(int tm);
		void GetTime(int& hour, int& minute, int& second) const;
		void GetTime(int& hour, int& minute, int& second, int& tenthousandths) const;
		int GetTime() const	{ return mTime; }
		int Hours() const;
		int Minutes() const;
		int Seconds() const;
		int SubSeconds() const;		// Actually tenthousandths of seconds
		Time()			{ Time::Clear(); }
		Time(int t)		{ SetTime(t); }
		Time(int hour, int minute, int second, int tenthousandths = 0);
		Time(const Time&);							// Copy Constructor
		Time& operator=(const Timestamp&);			// Timestamp Assignment operator
		Time& operator=(const Time&);				// Time Assignment operator

		bool operator==(const Time& rv)	const { return mTime == rv.GetTime(); }
		bool operator!=(const Time& rv)	const { return mTime != rv.GetTime(); }
		bool operator<(const Time& rv) const { return mTime < rv.GetTime(); }
		bool operator>(const Time& rv) const { return mTime > rv.GetTime(); }

		virtual ~Time() { };
	};

	/* Class Timestamp represent a date AND a time. It is usefull in
	 * interactions with the SQL TIMESTAMP type of Interbase. This class
	 * inherits from Date and Time and completely inline implements its small
	 * specific details. */

	class Timestamp : public Date, public Time
	{
	public:
		//lint -e1511 member hides non-virtual member: expected
		void Clear()	{ Date::Clear(); Time::Clear(); }
		void Today()	{ Date::Today(); Time::Clear(); }
		void Now()		{ Date::Today(); Time::Now(); }
		//lint +e1511

		Timestamp()		{ Timestamp::Clear(); }

	  	Timestamp(int y, int m, int d)
	  		{ Date::SetDate(y, m, d); Time::Clear(); }

		Timestamp(int y, int mo, int d, int h, int mi, int s, int t = 0)
	  		{ Date::SetDate(y, mo, d); Time::SetTime(h, mi, s, t); }

		Timestamp(const Timestamp& rv)
			: Date(rv.mDate), Time(rv.mTime) {}	// Copy Constructor

		Timestamp(const Date& rv)
			{ mDate = rv.GetDate(); mTime = 0; }

		Timestamp(const Time& rv)
			{ mDate = 0; mTime = rv.GetTime(); }

		//lint -e{1529} not first checking for assignment to this (no need to)
		Timestamp& operator=(const Timestamp& rv)	// Timestamp Assignment operator
			{ mDate = rv.mDate; mTime = rv.mTime; return *this; }

		//lint -e{1539} member mTime not assigned by assignment operator
		Timestamp& operator=(const Date& rv)		// Date Assignment operator
			{ mDate = rv.GetDate(); return *this; }

		//lint -e{1539} member mDate not assigned by assignment operator
		Timestamp& operator=(const Time& rv)		// Time Assignment operator
			{ mTime = rv.GetTime(); return *this; }

		//lint -e{1511} member hides non-virtual member: expected
		bool operator==(const Timestamp& rv) const
			{ return (mDate == rv.GetDate()) && (mTime == rv.GetTime()); }

		//lint -e{1511} member hides non-virtual member: expected
		bool operator!=(const Timestamp& rv) const
			{ return (mDate != rv.GetDate()) || (mTime != rv.GetTime()); }

		//lint -e{1511} member hides non-virtual member: expected
		bool operator<(const Timestamp& rv) const
			{ return (mDate < rv.GetDate()) ||
				(mDate == rv.GetDate() && mTime < rv.GetTime()); }

		//lint -e{1511} member hides non-virtual member: expected
		bool operator>(const Timestamp& rv) const
			{ return (mDate > rv.GetDate()) ||
				(mDate == rv.GetDate() && mTime > rv.GetTime()); }

		~Timestamp() { }
	};

	/* Class DBKey can store a DBKEY, that special value which the hidden
	 * RDB$DBKEY can give you from a select statement. A DBKey is nothing
	 * specific to IBPP. It's a feature of the Firebird database engine. See its
	 * documentation for more information. */

	class DBKey
	{
	private:
		std::string mDBKey;			// Stores the binary DBKey
		mutable std::string mString;// String (temporary) representation of it

	public:
		void Clear();
		int Size() const	{ return (int)mDBKey.size(); }
		void SetKey(const void*, int size);
		void GetKey(void*, int size) const;
		const char* AsString() const;

		DBKey& operator=(const DBKey&);	// Assignment operator
		DBKey(const DBKey&);			// Copy Constructor
		DBKey() { }
		~DBKey() { }
	};

	/* Class User wraps all the information about a user that the engine can manage. */

	class User
	{
	public:
		std::string username;
		std::string password;
		std::string firstname;
		std::string middlename;
		std::string lastname;
		uint32_t userid;		// Only relevant on unixes
		uint32_t groupid;		// Only relevant on unixes

	private:
		void copyfrom(const User& r);

	public:
		void clear();
		User& operator=(const User& r)	{ if (&r == this) return *this; copyfrom(r); return *this; }
		User(const User& r)				{ copyfrom(r); }
		User() : userid(0), groupid(0)	{ }
		~User() { };
	};

	//	Interface Wrapper
	template <class T>
	class Ptr
	{
	private:
		T* mObject;

	public:
		void clear()
		{
			if (mObject != 0) { mObject->Release(); mObject = 0; }
		}

		T* intf() const						{ return mObject; }
		T* operator->() const				{ return mObject; }

		bool operator==(const T* p) const	{ return mObject == p; }
		bool operator==(const Ptr& r) const	{ return mObject == r.mObject; }
		bool operator!=(const T* p) const	{ return mObject != p; }
		bool operator!=(const Ptr& r) const	{ return mObject != r.mObject; }

		Ptr& operator=(T* p)
		{
			// AddRef _before_ Release gives correct behaviour on self-assigns
			T* tmp = (p == 0 ? 0 : p->AddRef());	// Take care of 0
			if (mObject != 0) mObject->Release();
			mObject = tmp; return *this;
		}

		Ptr& operator=(const Ptr& r)
		{
			if (&r != this)
			{
				//lint -e{613} Lint does not see that r-> is valid if r.intf() != 0
				T* tmp = (r.intf() == 0 ? 0 : r->AddRef());// Take care of 0
				if (mObject != 0) mObject->Release();
				mObject = tmp;
			}
			return *this;
		}

		Ptr(T* p) : mObject(p == 0 ? 0 : p->AddRef()) { }

		//lint -e{613} Lint does not see that r-> is valid if r.intf() != 0
		Ptr(const Ptr& r) : mObject(r.intf() == 0 ? 0 : r->AddRef()) {  }

		Ptr() : mObject(0) { }
		~Ptr() { clear(); }
	};

	//	--- Interface Classes --- //

	/* Interfaces IBlob, IArray, IService, IDatabase, ITransaction and
	 * IStatement are at the core of IBPP. Though it is possible to program your
	 * applications by using theses interfaces directly (as was the case with
	 * IBPP 1.x), you should refrain from using them and prefer the new IBPP
	 * Objects Blob, Array, ... (without the I in front). Those new objects are
	 * typedef'd right after each interface class definition as you can read
	 * below. If you program using the Blob (instead of the IBlob interface
	 * itself), you'll never have to care about AddRef/Release and you'll never
	 * have to care about deleting your objects. */

	class IInterface
	{
	public:
		virtual ~IInterface() { };
	};

	class IBlob;			typedef Ptr<IBlob> Blob;
	class IArray;			typedef Ptr<IArray> Array;
	class IDriver;			typedef Ptr<IDriver> Driver;
	class IService;			typedef Ptr<IService> Service;
	class IDatabase;		typedef Ptr<IDatabase> Database;
	class ITransaction;		typedef Ptr<ITransaction> Transaction;
	class IStatement;		typedef Ptr<IStatement> Statement;
	class IEvents;			typedef Ptr<IEvents> Events;
	//class IRow;				typedef Ptr<IRow> Row;

	/* IBlob is the interface to the blob capabilities of IBPP. Blob is the
	 * object class you actually use in your programming. In Firebird, at the
	 * row level, a blob is merely a handle to a blob, stored elsewhere in the
	 * database. Blob allows you to retrieve such a handle and then read from or
	 * write to the blob, much in the same manner than you would do with a file. */

	class IBlob : public IInterface
	{
	public:
		virtual void Create() = 0;
		virtual void Open() = 0;
		virtual void Close() = 0;
		virtual void Cancel() = 0;
		virtual int Read(void*, int size) = 0;
		virtual void Write(const void*, int size) = 0;
		virtual void Info(int* Size, int* Largest, int* Segments) = 0;

		virtual void Save(const std::string& data) = 0;
		virtual void Load(std::string& data) = 0;

		virtual Database DatabasePtr() const = 0;
		virtual Transaction TransactionPtr() const = 0;

		virtual IBlob* AddRef() = 0;
		virtual void Release() = 0;

		virtual ~IBlob() { };
	};

	/*	IArray is the interface to the array capabilities of IBPP. Array is the
	* object class you actually use in your programming. With an Array object, you
	* can create, read and write Interbase Arrays, as a whole or in slices. */

	class IArray : public IInterface
	{
	public:
		virtual void Describe(const std::string& table, const std::string& column) = 0;
		virtual void ReadTo(ADT, void* buffer, int elemcount) = 0;
		virtual void WriteFrom(ADT, const void* buffer, int elemcount) = 0;
		virtual SDT ElementType() = 0;
		virtual int ElementSize() = 0;
		virtual int ElementScale() = 0;
		virtual int Dimensions() = 0;
		virtual void Bounds(int dim, int* low, int* high) = 0;
		virtual void SetBounds(int dim, int low, int high) = 0;

		virtual Database DatabasePtr() const = 0;
		virtual Transaction TransactionPtr() const = 0;

		virtual IArray* AddRef() = 0;
		virtual void Release() = 0;

		virtual ~IArray() { };
	};

	/* IDriver is the basic building block interface of IBPP. It is responsible for
	 * loading a interface to a database engine and to factory the other interfaces
	 * instances. */

	class IDriver : public IInterface
	{
	public:
		virtual void Load(const std::string& paths) = 0;
		virtual void Load() = 0;
		virtual bool Loaded() const = 0;
		virtual void Unload() = 0;

		virtual void GetVersion(std::string& version) = 0;

		virtual Service ServiceFactory(const std::string& ServerName,
							const std::string& UserName, const std::string& UserPassword) = 0;

		virtual Database DatabaseFactory(const std::string& ServerName,
							const std::string& DatabaseName, const std::string& UserName,
								const std::string& UserPassword, const std::string& RoleName,
									const std::string& CharSet, const std::string& CreateParams) = 0;

		virtual Database DatabaseFactory(const std::string& ServerName,
							const std::string& DatabaseName, const std::string& UserName,
								const std::string& UserPassword) = 0;
		/*
		{ return DatabaseFactory(ServerName, DatabaseName, UserName, UserPassword, "", "", ""); }
		*/

		virtual Transaction TransactionFactory(Database db, TAM am = amWrite,
								TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0)) = 0;

		virtual Statement StatementFactory(Database db, Transaction tr,
							const std::string& sql) = 0;

		virtual Statement StatementFactory(Database db, Transaction tr) = 0;
		/*
		{ return StatementFactory(db, tr, ""); }
		*/

		virtual Blob BlobFactory(Database db, Transaction tr) = 0;
		virtual Array ArrayFactory(Database db, Transaction tr) = 0;
		virtual Events EventsFactory(Database db) = 0;

		virtual IDriver* AddRef() = 0;
		virtual void Release() = 0;

		virtual ~IDriver() { };
	};

	Driver DriverFactory();		// Used to get an instance of a Driver interface

	/* IService is the interface to the service capabilities of IBPP. Service is
	 * the object class you actually use in your programming. With a Service
	 * object, you can do some maintenance work of databases and servers
	 * (backup, restore, create/update users, ...) */

	class IService : public IInterface
	{
	public:
	    virtual void Connect() = 0;
		virtual bool Connected() = 0;
		virtual void Disconnect() = 0;

		virtual void GetVersion(std::string& version) = 0;

		virtual void AddUser(const User&) = 0;
		virtual void GetUser(User&) = 0;
		virtual void GetUsers(std::vector<User>&) = 0;
		virtual void ModifyUser(const User&) = 0;
		virtual void RemoveUser(const std::string& username) = 0;

		virtual void SetPageBuffers(const std::string& dbfile, int buffers) = 0;
		virtual void SetSweepInterval(const std::string& dbfile, int sweep) = 0;
		virtual void SetSyncWrite(const std::string& dbfile, bool) = 0;
		virtual void SetReadOnly(const std::string& dbfile, bool) = 0;
		virtual void SetReserveSpace(const std::string& dbfile, bool) = 0;

		virtual void Shutdown(const std::string& dbfile, DSM mode, int sectimeout) = 0;
		virtual void Restart(const std::string& dbfile) = 0;
		virtual void Sweep(const std::string& dbfile) = 0;
		virtual void Repair(const std::string& dbfile, RPF flags) = 0;

		virtual void StartBackup(const std::string& dbfile,
			const std::string& bkfile, BRF flags = BRF(0)) = 0;
		virtual void StartRestore(const std::string& bkfile, const std::string& dbfile,
			int pagesize = 0, BRF flags = BRF(0)) = 0;

		virtual const char* WaitMsg() = 0;	// With reporting (does not block)
		virtual void Wait() = 0;			// Without reporting (does block)

		virtual	Driver DriverPtr() const = 0;

		virtual IService* AddRef() = 0;
		virtual void Release() = 0;

		virtual ~IService() { };
	};

	/*	IDatabase is the interface to the database connections in IBPP. Database
	 * is the object class you actually use in your programming. With a Database
	 * object, you can create/drop/connect databases. */

	class EventInterface;	// Cross-reference between EventInterface and IDatabase

	class IDatabase : public IInterface
	{
	public:
		virtual const char* ServerName() const = 0;
		virtual const char* DatabaseName() const = 0;
		virtual const char* Username() const = 0;
		virtual const char* UserPassword() const = 0;
		virtual const char* RoleName() const = 0;
		virtual const char* CharSet() const = 0;
		virtual const char* CreateParams() const = 0;

		virtual void Info(int* ODS, int* ODSMinor, int* PageSize,
			int* Pages,	int* Buffers, int* Sweep, bool* Sync,
			bool* Reserve, bool* ReadOnly = 0) = 0;
		virtual void Statistics(int* Fetches, int* Marks,
			int* Reads, int* Writes) = 0;
		virtual void Counts(int* Insert, int* Update, int* Delete,
			int* ReadIdx, int* ReadSeq) = 0;
		virtual void Users(std::vector<std::string>& users) = 0;
		virtual int Dialect() = 0;

		virtual void Create(int dialect) = 0;
		virtual void Connect() = 0;
		virtual bool Connected() = 0;
		virtual void Inactivate() = 0;
		virtual void Disconnect() = 0;
		virtual void Drop() = 0;

		virtual	Driver DriverPtr() const = 0;

		virtual IDatabase* AddRef() = 0;
		virtual void Release() = 0;

	    virtual ~IDatabase() { };
	};

	/* ITransaction is the interface to the transaction connections in IBPP.
	 * Transaction is the object class you actually use in your programming. A
	 * Transaction object can be associated with more than one Database,
	 * allowing for distributed transactions spanning multiple databases,
	 * possibly located on different servers. IBPP is one among the few
	 * programming interfaces to Firebird that allows you to support distributed
	 * transactions. */

	class ITransaction : public IInterface
	{
	public:
	    virtual void AttachDatabase(Database db, TAM am = amWrite,
			TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0)) = 0;
	    virtual void DetachDatabase(Database db) = 0;
	 	virtual void AddReservation(Database db,
	 			const std::string& table, TTR tr) = 0;

		virtual void Start() = 0;
		virtual bool Started() = 0;
	    virtual void Commit() = 0;
	    virtual void Rollback() = 0;
	    virtual void CommitRetain() = 0;
		virtual void RollbackRetain() = 0;

		virtual	Driver DriverPtr() const = 0;

		virtual ITransaction* AddRef() = 0;
		virtual void Release() = 0;

	    virtual ~ITransaction() { };
	};

	/*
	 *	Class Row can hold all the values of a row (from a SELECT for instance).
	 */

	/*
	class IRow : public IInterface
	{
	public:
		virtual void SetNull(int) = 0;
		virtual void Set(int, bool) = 0;
		virtual void Set(int, const void*, int) = 0;		// byte buffers
		virtual void Set(int, const char*) = 0;				// c-string
		virtual void Set(int, const std::string&) = 0;
		virtual void Set(int, int16_t) = 0;
		virtual void Set(int, int32_t) = 0;
		virtual void Set(int, int64_t) = 0;
		virtual void Set(int, float) = 0;
		virtual void Set(int, double) = 0;
		virtual void Set(int, const Timestamp&) = 0;
		virtual void Set(int, const Date&) = 0;
		virtual void Set(int, const Time&) = 0;
		virtual void Set(int, const DBKey&) = 0;
		virtual void Set(int, const Blob&) = 0;
		virtual void Set(int, const Array&) = 0;

		virtual bool IsNull(int) = 0;
		virtual bool Get(int, bool&) = 0;
		virtual bool Get(int, void*, int&) = 0;	// byte buffers
		virtual bool Get(int, std::string&) = 0;
		virtual bool Get(int, int16_t&) = 0;
		virtual bool Get(int, int32_t&) = 0;
		virtual bool Get(int, int64_t&) = 0;
		virtual bool Get(int, float&) = 0;
		virtual bool Get(int, double&) = 0;
		virtual bool Get(int, Timestamp&) = 0;
		virtual bool Get(int, Date&) = 0;
		virtual bool Get(int, Time&) = 0;
		virtual bool Get(int, DBKey&) = 0;
		virtual bool Get(int, Blob&) = 0;
		virtual bool Get(int, Array&) = 0;

		virtual bool IsNull(const std::string&) = 0;
		virtual bool Get(const std::string&, bool&) = 0;
		virtual bool Get(const std::string&, void*, int&) = 0;	// byte buffers
		virtual bool Get(const std::string&, std::string&) = 0;
		virtual bool Get(const std::string&, int16_t&) = 0;
		virtual bool Get(const std::string&, int32_t&) = 0;
		virtual bool Get(const std::string&, int64_t&) = 0;
		virtual bool Get(const std::string&, float&) = 0;
		virtual bool Get(const std::string&, double&) = 0;
		virtual bool Get(const std::string&, Timestamp&) = 0;
		virtual bool Get(const std::string&, Date&) = 0;
		virtual bool Get(const std::string&, Time&) = 0;
		virtual bool Get(const std::string&, DBKey&) = 0;
		virtual bool Get(const std::string&, Blob&) = 0;
		virtual bool Get(const std::string&, Array&) = 0;

		virtual int ColumnNum(const std::string&) = 0;
		virtual const char* ColumnName(int) = 0;
		virtual const char* ColumnAlias(int) = 0;
		virtual const char* ColumnTable(int) = 0;
		virtual SDT ColumnType(int) = 0;
		virtual int ColumnSubtype(int) = 0;
		virtual int ColumnSize(int) = 0;
		virtual int ColumnScale(int) = 0;
		virtual int Columns() = 0;

		virtual bool ColumnUpdated(int) = 0;
		virtual bool Updated() = 0;

		virtual	Database DatabasePtr() const = 0;
		virtual Transaction TransactionPtr() const = 0;

		virtual IRow* Clone() = 0;
		virtual IRow* AddRef() = 0;
		virtual void Release() = 0;

	    virtual ~IRow() {};
	};
	*/

	/* IStatement is the interface to the statements execution in IBPP.
	 * Statement is the object class you actually use in your programming. A
	 * Statement object is the work horse of IBPP. All your data manipulation
	 * statements will be done through it. It is also used to access the result
	 * set of a query (when the statement is such), one row at a time and in
	 * strict forward direction. */

	class IStatement : public IInterface
	{
	public:
		virtual void Prepare(const std::string&) = 0;
		virtual void Execute() = 0;
		virtual void Execute(const std::string&) = 0;
		virtual void ExecuteImmediate(const std::string&) = 0;
		virtual void CursorExecute(const std::string& cursor) = 0;
		virtual void CursorExecute(const std::string& cursor, const std::string&) = 0;
		virtual bool Fetch() = 0;
		//virtual bool Fetch(Row&) = 0;
		virtual int AffectedRows() = 0;
		virtual void Close() = 0;
		virtual std::string Sql() = 0;
		virtual STT Type() = 0;

		virtual void SetNull(int) = 0;
		virtual void Set(int, bool) = 0;
		virtual void Set(int, const void*, int) = 0;		// byte buffers
		virtual void Set(int, const char*) = 0;				// pointer to c-string

		// char buffers use this template wrapper to automatically check limits
		template <const size_t n> void Set(int p, const char (&s)[n])
		{
			int count = 0;
			while (count < n && s[count] != '\0') count++;
			return Set(p, s, count);
		}

		virtual void Set(int, const std::string&) = 0;
		virtual void Set(int, int16_t value) = 0;
		virtual void Set(int, int value) = 0;
		virtual void Set(int, int64_t value) = 0;
		virtual void Set(int, float value) = 0;
		virtual void Set(int, double value) = 0;
		virtual void Set(int, const Timestamp& value) = 0;
		virtual void Set(int, const Date& value) = 0;
		virtual void Set(int, const Time& value) = 0;
		virtual void Set(int, const DBKey& value) = 0;
		virtual void Set(int, const Blob& value) = 0;
		virtual void Set(int, const Array& value) = 0;

		virtual bool IsNull(int) = 0;
		virtual bool Get(int, bool&) = 0;
		virtual bool Get(int, void*, int&) = 0;	// byte buffers

		// char buffers use this template wrapper to automatically enforce terminating '\0'
		template <const size_t n> bool Get(int p, char (&s)[n])
		{
			int i = n-1;
			bool ret = Get(p, s, i);
			s[i] = '\0';
			return ret;
		}

		virtual bool Get(int, std::string&) = 0;
		virtual bool Get(int, int16_t&) = 0;
		virtual bool Get(int, int&) = 0;
		virtual bool Get(int, int64_t&) = 0;
		virtual bool Get(int, float&) = 0;
		virtual bool Get(int, double&) = 0;
		virtual bool Get(int, Timestamp& value) = 0;
		virtual bool Get(int, Date& value) = 0;
		virtual bool Get(int, Time& value) = 0;
		virtual bool Get(int, DBKey& value) = 0;
		virtual bool Get(int, Blob& value) = 0;
		virtual bool Get(int, Array& value) = 0;

		virtual bool IsNull(const std::string&) = 0;
		virtual bool Get(const std::string&, bool&) = 0;
		virtual bool Get(const std::string&, void*, int&) = 0;	// byte buffers

		// char buffers use this template wrapper to automatically enforce terminating '\0'
		template <const size_t n> bool Get(const std::string& p, char (&s)[n])
		{
			int i = n-1;
			bool ret = Get(p, s, i);
			s[i] = '\0';
			return ret;
		}

		virtual bool Get(const std::string&, std::string&) = 0;
		virtual bool Get(const std::string&, int16_t&) = 0;
		virtual bool Get(const std::string&, int&) = 0;
		virtual bool Get(const std::string&, int64_t&) = 0;
		virtual bool Get(const std::string&, float&) = 0;
		virtual bool Get(const std::string&, double&) = 0;
		virtual bool Get(const std::string&, Timestamp& value) = 0;
		virtual bool Get(const std::string&, Date& value) = 0;
		virtual bool Get(const std::string&, Time& value) = 0;
		virtual bool Get(const std::string&, DBKey& value) = 0;
		virtual bool Get(const std::string&, Blob& value) = 0;
		virtual bool Get(const std::string&, Array& value) = 0;

		virtual int ColumnNum(const std::string&) = 0;
		virtual const char* ColumnName(int) = 0;
		virtual const char* ColumnAlias(int) = 0;
		virtual const char* ColumnTable(int) = 0;
		virtual SDT ColumnType(int) = 0;
		virtual int ColumnSubtype(int) = 0;
		virtual int ColumnSize(int) = 0;
		virtual int ColumnScale(int) = 0;
		virtual int Columns() = 0;

		virtual SDT ParameterType(int) = 0;
		virtual int ParameterSubtype(int) = 0;
		virtual int ParameterSize(int) = 0;
		virtual int ParameterScale(int) = 0;
		virtual int Parameters() = 0;

		virtual void Plan(std::string&) = 0;

		virtual	Database DatabasePtr() const = 0;
		virtual Transaction TransactionPtr() const = 0;
		virtual	Driver DriverPtr() const = 0;

		virtual IStatement* AddRef() = 0;
		virtual void Release() = 0;

	    virtual ~IStatement() { };
	};

	class IEvents : public IInterface
	{
	public:
		virtual void Add(const std::string&, EventInterface*) = 0;
		virtual void Drop(const std::string&) = 0;
		virtual void List(std::vector<std::string>&) = 0;
		virtual void Clear() = 0;				// Drop all events
		virtual void Dispatch() = 0;			// Dispatch events (calls handlers)

		virtual	Database DatabasePtr() const = 0;
		virtual	Driver DriverPtr() const = 0;

		virtual IEvents* AddRef() = 0;
		virtual void Release() = 0;

	    virtual ~IEvents() { };
	};

	/* Class EventInterface is merely a pure interface.
	 * It is _not_ implemented by IBPP. It is only a base class definition from
	 * which your own event interface classes have to derive from.
	 * Please read the reference guide at http://www.ibpp.org for more info. */

	class EventInterface
	{
	public:
		virtual void ibppEventHandler(Events, const std::string&, int) = 0;
		virtual ~EventInterface() { };
	};

	/* IBPP uses a self initialization system. Each time an object that may
	 * require the usage of the Interbase client C-API library is used, the
	 * library internal handling details are automatically initialized, if not
	 * already done. You can kick this initialization at the start of an
	 * application by calling IBPP::CheckVersion(). This is recommended, because
	 * IBPP::CheckVersion will assure you that YOUR code has been compiled
	 * against a compatible version of the library. */

	bool CheckVersion(uint32_t);

	/* Finally, here are some date and time conversion routines used by IBPP and
	 * that may be helpful at the application level. They do not depend on
	 * anything related to Firebird/Interbase. Just a bonus. dtoi and itod
	 * return false on invalid parameters or out of range conversions. */

	bool dtoi(int date, int* py, int* pm, int* pd);
	bool itod(int* pdate, int year, int month, int day);
	void ttoi(int itime, int* phour, int* pminute, int* psecond, int* ptt);
	void itot(int* ptime, int hour, int minute, int second = 0, int tenthousandths = 0);

}

#endif

//
//	EOF
//