X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/8c6fa3fbaccc22127280bf77a48fab5a3ee0716e..46b0747592074017ff0ea4b33d4a7194235886e5:/libs/ibpp/include/stg/ibpp.h diff --git a/libs/ibpp/include/stg/ibpp.h b/libs/ibpp/include/stg/ibpp.h new file mode 100644 index 00000000..f666b16d --- /dev/null +++ b/libs/ibpp/include/stg/ibpp.h @@ -0,0 +1,929 @@ +/////////////////////////////////////////////////////////////////////////////// +// +// File : $Id: ibpp.h,v 1.3 2007/10/28 11:17:44 nobunaga Exp $ +// Subject : IBPP public header file. This is _the_ only file you include in +// your application files when developing with IBPP. +// +/////////////////////////////////////////////////////////////////////////////// +// +// (C) Copyright 2000-2006 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 // C99 (§7.18) integer types definitions +#endif + +#if !defined(_) +#define _(s) s +#endif + +#include +#include +#include + +namespace IBPP +{ + // Typically you use this constant in a call IBPP::CheckVersion as in: + // if (! IBPP::CheckVersion(IBPP::Version)) { throw .... ; } + const uint32_t Version = (2<<24) + (5<<16) + (3<<8) + 0; // Version == 2.5.3.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 throw() = 0; + virtual const char* ErrorMessage() const throw() = 0; // Deprecated, use what() + virtual const char* what() const throw() = 0; + virtual ~Exception() throw(); + }; + + class LogicException : public Exception + { + public: + virtual ~LogicException() throw(); + }; + + class SQLException : public Exception + { + public: + virtual int SqlCode() const throw() = 0; + virtual int EngineCode() const throw() = 0; + + virtual ~SQLException() throw(); + }; + + class WrongType : public LogicException + { + public: + virtual ~WrongType() throw(); + }; + + /* 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() { 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() { Clear(); } + Time(int tm) { SetTime(tm); } + 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: + void Clear() { Date::Clear(); Time::Clear(); } + void Today() { Date::Today(); Time::Clear(); } + void Now() { Date::Today(); Time::Now(); } + + 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(); } + + Timestamp& operator=(const Timestamp& rv) // Timestamp Assignment operator + { mDate = rv.mDate; mTime = rv.mTime; return *this; } + + Timestamp& operator=(const Date& rv) // Date Assignment operator + { mDate = rv.GetDate(); return *this; } + + Timestamp& operator=(const Time& rv) // Time Assignment operator + { mTime = rv.GetTime(); return *this; } + + bool operator==(const Timestamp& rv) const + { return (mDate == rv.GetDate()) && (mTime == rv.GetTime()); } + + bool operator!=(const Timestamp& rv) const + { return (mDate != rv.GetDate()) || (mTime != rv.GetTime()); } + + bool operator<(const Timestamp& rv) const + { return (mDate < rv.GetDate()) || + (mDate == rv.GetDate() && mTime < rv.GetTime()); } + + 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) { copyfrom(r); return *this; } + User(const User& r) { copyfrom(r); } + User() : userid(0), groupid(0) { } + ~User() { } + }; + + // Interface Wrapper + template + 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) + { + // AddRef _before_ Release gives correct behaviour on self-assigns + 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()) { } + 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 IBlob; typedef Ptr Blob; + class IArray; typedef Ptr Array; + class IService; typedef Ptr Service; + class IDatabase; typedef Ptr Database; + class ITransaction; typedef Ptr Transaction; + class IStatement; typedef Ptr Statement; + class IEvents; typedef Ptr Events; + class IRow; typedef Ptr 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: + 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: + 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() { } + }; + + /* 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: + 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&) = 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 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: + 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) = 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& 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 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: + 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 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: + 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: + 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; // c-string + virtual void Set(int, const std::string&) = 0; + virtual void Set(int, int16_t value) = 0; + virtual void Set(int, int32_t 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 + 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& 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 + 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& 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 IStatement* AddRef() = 0; + virtual void Release() = 0; + + virtual ~IStatement() { } + + // DEPRECATED METHODS (WON'T BE AVAILABLE IN VERSIONS 3.x) + virtual bool Get(int, char*) = 0; // DEPRECATED + virtual bool Get(const std::string&, char*) = 0; // DEPRECATED + virtual bool Get(int, bool*) = 0; // DEPRECATED + virtual bool Get(const std::string&, bool*) = 0; // DEPRECATED + virtual bool Get(int, int16_t*) = 0; // DEPRECATED + virtual bool Get(const std::string&, int16_t*) = 0; // DEPRECATED + virtual bool Get(int, int32_t*) = 0; // DEPRECATED + virtual bool Get(const std::string&, int32_t*) = 0; // DEPRECATED + virtual bool Get(int, int64_t*) = 0; // DEPRECATED + virtual bool Get(const std::string&, int64_t*) = 0; // DEPRECATED + virtual bool Get(int, float*) = 0; // DEPRECATED + virtual bool Get(const std::string&, float*) = 0; // DEPRECATED + virtual bool Get(int, double*) = 0; // DEPRECATED + virtual bool Get(const std::string&, double*) = 0; // DEPRECATED + }; + + class IEvents + { + public: + virtual void Add(const std::string&, EventInterface*) = 0; + virtual void Drop(const std::string&) = 0; + virtual void List(std::vector&) = 0; + virtual void Clear() = 0; // Drop all events + virtual void Dispatch() = 0; // Dispatch events (calls handlers) + + virtual Database DatabasePtr() 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() { } + }; + + // --- Factories --- + // These methods are the only way to get one of the above + // Interfaces. They are at the heart of how you program using IBPP. For + // instance, to get access to a database, you'll write code similar to this: + // { + // Database db = DatabaseFactory("server", "databasename", + // "user", "password"); + // db->Connect(); + // ... + // db->Disconnect(); + // } + + Service ServiceFactory(const std::string& ServerName, + const std::string& UserName, const std::string& UserPassword); + + 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); + + inline Database DatabaseFactory(const std::string& ServerName, + const std::string& DatabaseName, const std::string& UserName, + const std::string& UserPassword) + { return DatabaseFactory(ServerName, DatabaseName, UserName, UserPassword, "", "", ""); } + + Transaction TransactionFactory(Database db, TAM am = amWrite, + TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0)); + + Statement StatementFactory(Database db, Transaction tr, + const std::string& sql); + + inline Statement StatementFactory(Database db, Transaction tr) + { return StatementFactory(db, tr, ""); } + + Blob BlobFactory(Database db, Transaction tr); + + Array ArrayFactory(Database db, Transaction tr); + + Events EventsFactory(Database db); + + /* 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); + int GDSVersion(); + + /* On Win32 platform, ClientLibSearchPaths() allows to setup + * one or multiple additional paths (separated with a ';') where IBPP + * will look for the client library (before the default implicit search + * locations). This is usefull for applications distributed with a 'private' + * copy of Firebird, when the registry is useless to identify the location + * from where to attempt loading the fbclient.dll / gds32.dll. + * If called, this function must be called *early* by the application, + * before *any* other function or object methods of IBPP. + * Currently, this is a NO-OP on platforms other than Win32. */ + + void ClientLibSearchPaths(const std::string&); + + /* 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 +//