]> git.stg.codes - stg.git/blob - stglibs/ibpp.lib/include/stg/ibpp.h
Moved all sync/async boundary code into the client.
[stg.git] / stglibs / ibpp.lib / include / stg / ibpp.h
1 ///////////////////////////////////////////////////////////////////////////////\r
2 //\r
3 //      File    : $Id: ibpp.h,v 1.3 2007/10/28 11:17:44 nobunaga Exp $\r
4 //      Subject : IBPP public header file. This is _the_ only file you include in\r
5 //                        your application files when developing with IBPP.\r
6 //\r
7 ///////////////////////////////////////////////////////////////////////////////\r
8 //\r
9 //      (C) Copyright 2000-2006 T.I.P. Group S.A. and the IBPP Team (www.ibpp.org)\r
10 //\r
11 //      The contents of this file are subject to the IBPP License (the "License");\r
12 //      you may not use this file except in compliance with the License.  You may\r
13 //      obtain a copy of the License at http://www.ibpp.org or in the 'license.txt'\r
14 //      file which must have been distributed along with this file.\r
15 //\r
16 //      This software, distributed under the License, is distributed on an "AS IS"\r
17 //      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See the\r
18 //      License for the specific language governing rights and limitations\r
19 //      under the License.\r
20 //\r
21 //      Contributor(s):\r
22 //\r
23 //              Olivier Mascia, main coding\r
24 //              Matt Hortman, initial linux port\r
25 //              Mark Jordan, design contributions\r
26 //              Maxim Abrashkin, enhancement patches\r
27 //              Torsten Martinsen, enhancement patches\r
28 //              Michael Hieke, darwin (OS X) port, enhancement patches\r
29 //              Val Samko, enhancement patches and debugging\r
30 //              Mike Nordell, invaluable C++ advices\r
31 //              Claudio Valderrama, help with not-so-well documented IB/FB features\r
32 //              Many others, excellent suggestions, bug finding, and support\r
33 //\r
34 ///////////////////////////////////////////////////////////////////////////////\r
35 //\r
36 //      COMMENTS\r
37 //      Tabulations should be set every four characters when editing this file.\r
38 //\r
39 //      When compiling a project using IBPP, the following defines should be made\r
40 //      on the command-line (or in makefiles) according to the OS platform and\r
41 //      compiler used.\r
42 //\r
43 //      Select the platform:    IBPP_WINDOWS | IBPP_LINUX | IBPP_DARWIN\r
44 //\r
45 ///////////////////////////////////////////////////////////////////////////////\r
46 \r
47 #ifndef __IBPP_H__\r
48 #define __IBPP_H__\r
49 \r
50 #if !defined(IBPP_WINDOWS) && !defined(IBPP_LINUX) && !defined(IBPP_DARWIN)\r
51 #error Please define IBPP_WINDOWS/IBPP_LINUX/IBPP_DARWIN before compiling !\r
52 #endif\r
53 \r
54 #if !defined(__BCPLUSPLUS__) && !defined(__GNUC__) && !defined(_MSC_VER) && !defined(__DMC__)
55 #error Your compiler is not recognized.\r
56 #endif\r
57 \r
58 #if defined(IBPP_LINUX) || defined(IBPP_DARWIN)\r
59 #define IBPP_UNIX       // IBPP_UNIX stands as a common denominator to *NIX flavours\r
60 #endif\r
61 \r
62 // IBPP is written for 32 bits systems or higher.\r
63 // The standard type 'int' is assumed to be at least 32 bits.\r
64 // And the standard type 'short' is assumed to be exactly 16 bits.\r
65 // Everywhere possible, where the exact size of an integer does not matter,\r
66 // the standard type 'int' is used. And where an exact integer size is required\r
67 // the standard exact precision types definitions of C 99 standard are used.\r
68 \r
69 #if defined(_MSC_VER) || defined(__DMC__) || defined(__BCPLUSPLUS__)\r
70 // C99 §7.18.1.1 Exact-width integer types (only those used by IBPP)\r
71 #if defined(_MSC_VER) && (_MSC_VER < 1300)      // MSVC 6 should be < 1300\r
72         typedef short int16_t;\r
73         typedef int int32_t;\r
74         typedef unsigned int uint32_t;\r
75 #else\r
76         typedef __int16 int16_t;\r
77         typedef __int32 int32_t;\r
78         typedef unsigned __int32 uint32_t;\r
79 #endif\r
80         typedef __int64 int64_t;\r
81 #else\r
82         #include <stg/os_int.h>                 // C99 (§7.18) integer types definitions\r
83 #endif\r
84 \r
85 #if !defined(_)\r
86 #define _(s)    s\r
87 #endif\r
88 \r
89 #include <exception>\r
90 #include <string>\r
91 #include <vector>\r
92 \r
93 namespace IBPP\r
94 {\r
95         //      Typically you use this constant in a call IBPP::CheckVersion as in:\r
96         //      if (! IBPP::CheckVersion(IBPP::Version)) { throw .... ; }\r
97         const uint32_t Version = (2<<24) + (5<<16) + (3<<8) + 0; // Version == 2.5.3.0\r
98 \r
99         //      Dates range checking\r
100         const int MinDate = -693594;    //  1 JAN 0001\r
101         const int MaxDate = 2958464;    // 31 DEC 9999\r
102         \r
103         //      Transaction Access Modes\r
104         enum TAM {amWrite, amRead};\r
105 \r
106         //      Transaction Isolation Levels\r
107         enum TIL {ilConcurrency, ilReadDirty, ilReadCommitted, ilConsistency};\r
108 \r
109         //      Transaction Lock Resolution\r
110         enum TLR {lrWait, lrNoWait};\r
111 \r
112         // Transaction Table Reservation\r
113         enum TTR {trSharedWrite, trSharedRead, trProtectedWrite, trProtectedRead};\r
114 \r
115         //      Prepared Statement Types\r
116         enum STT {stUnknown, stUnsupported,\r
117                 stSelect, stInsert, stUpdate, stDelete, stDDL, stExecProcedure,\r
118                 stSelectUpdate, stSetGenerator, stSavePoint};\r
119 \r
120         //      SQL Data Types\r
121         enum SDT {sdArray, sdBlob, sdDate, sdTime, sdTimestamp, sdString,\r
122                 sdSmallint, sdInteger, sdLargeint, sdFloat, sdDouble};\r
123 \r
124         //      Array Data Types\r
125         enum ADT {adDate, adTime, adTimestamp, adString,\r
126                 adBool, adInt16, adInt32, adInt64, adFloat, adDouble};\r
127 \r
128         // Database::Shutdown Modes\r
129         enum DSM {dsForce, dsDenyTrans, dsDenyAttach};\r
130 \r
131         // Service::StartBackup && Service::StartRestore Flags\r
132         enum BRF {\r
133                 brVerbose = 0x1,\r
134                 // Backup flags\r
135                 brIgnoreChecksums = 0x100, brIgnoreLimbo = 0x200,\r
136                 brMetadataOnly = 0x400, brNoGarbageCollect = 0x800,\r
137                 brNonTransportable = 0x1000, brConvertExtTables = 0x2000,\r
138                 // Restore flags\r
139                 brReplace = 0x10000, brDeactivateIdx = 0x20000,\r
140                 brNoShadow = 0x40000, brNoValidity = 0x80000,\r
141                 brPerTableCommit = 0x100000, brUseAllSpace = 0x200000\r
142         };\r
143 \r
144         // Service::Repair Flags\r
145         enum RPF\r
146         {\r
147                 // Mandatory and mutually exclusives\r
148                 rpMendRecords = 0x1, rpValidatePages = 0x2, rpValidateFull = 0x4,\r
149                 // Options\r
150                 rpReadOnly = 0x100, rpIgnoreChecksums = 0x200, rpKillShadows = 0x400\r
151         };\r
152 \r
153         // TransactionFactory Flags\r
154         enum TFF {tfIgnoreLimbo = 0x1, tfAutoCommit = 0x2, tfNoAutoUndo = 0x4};\r
155 \r
156         /* IBPP never return any error codes. It throws exceptions.\r
157          * On database engine reported errors, an IBPP::SQLException is thrown.\r
158          * In all other cases, IBPP throws IBPP::LogicException.\r
159          * Also note that the runtime and the language might also throw exceptions\r
160          * while executing some IBPP methods. A failing new operator will throw\r
161          * std::bad_alloc, IBPP does nothing to alter the standard behaviour.\r
162          *\r
163          *                    std::exception\r
164          *                           |\r
165          *                   IBPP::Exception\r
166          *                 /                 \\r
167          *    IBPP::LogicException    IBPP::SQLException\r
168          *             |\r
169          *      IBPP::WrongType\r
170          */\r
171 \r
172         class Exception : public std::exception\r
173         {\r
174         public:\r
175                 virtual const char* Origin() const throw() = 0;\r
176                 virtual const char* ErrorMessage() const throw() = 0;   // Deprecated, use what()\r
177                 virtual const char* what() const throw() = 0;\r
178                 virtual ~Exception() throw();\r
179         };\r
180 \r
181         class LogicException : public Exception\r
182         {\r
183         public:\r
184                 virtual ~LogicException() throw();\r
185         };\r
186 \r
187         class SQLException : public Exception\r
188         {\r
189         public:\r
190                 virtual int SqlCode() const throw() = 0;\r
191                 virtual int EngineCode() const throw() = 0;\r
192                 \r
193                 virtual ~SQLException() throw();\r
194         };\r
195 \r
196         class WrongType : public LogicException\r
197         {\r
198         public:\r
199                 virtual ~WrongType() throw();\r
200         };\r
201         \r
202         /* Classes Date, Time, Timestamp and DBKey are 'helper' classes.  They help\r
203          * in retrieving or setting some special SQL types. Dates, times and dbkeys\r
204          * are often read and written as strings in SQL scripts. When programming\r
205          * with IBPP, we handle those data with these specific classes, which\r
206          * enhance their usefullness and free us of format problems (M/D/Y, D/M/Y,\r
207          * Y-M-D ?, and so on...). */\r
208 \r
209         /* Class Date represent purely a Date (no time part specified). It is\r
210          * usefull in interactions with the SQL DATE type of Interbase.  You can add\r
211          * or substract a number from a Date, that will modify it to represent the\r
212          * correct date, X days later or sooner. All the Y2K details taken into\r
213          * account.\r
214          * The full range goes from integer values IBPP::MinDate to IBPP::MaxDate\r
215          * which means from 01 Jan 0001 to 31 Dec 9999. ( Which is inherently\r
216          * incorrect as this assumes Gregorian calendar. ) */\r
217         \r
218         class Timestamp;        // Cross-reference between Timestamp, Date and Time\r
219         \r
220         class Date\r
221         {\r
222         protected:\r
223                 int mDate;      // The date : 1 == 1 Jan 1900\r
224 \r
225         public:\r
226                 void Clear()    { mDate = MinDate - 1; }\r
227                 void Today();\r
228                 void SetDate(int year, int month, int day);\r
229                 void SetDate(int dt);\r
230                 void GetDate(int& year, int& month, int& day) const;\r
231                 int GetDate() const     { return mDate; }\r
232                 int Year() const;\r
233                 int Month() const;\r
234                 int Day() const;\r
235                 void Add(int days);\r
236                 void StartOfMonth();\r
237                 void EndOfMonth();\r
238         \r
239                 Date()                  { Clear(); }\r
240                 Date(int dt)    { SetDate(dt); }\r
241                 Date(int year, int month, int day);\r
242                 Date(const Date&);                                                      // Copy Constructor\r
243                 Date& operator=(const Timestamp&);                      // Timestamp Assignment operator\r
244                 Date& operator=(const Date&);                           // Date Assignment operator\r
245 \r
246                 bool operator==(const Date& rv) const { return mDate == rv.GetDate(); }\r
247                 bool operator!=(const Date& rv) const { return mDate != rv.GetDate(); }\r
248                 bool operator<(const Date& rv) const { return mDate < rv.GetDate(); }\r
249                 bool operator>(const Date& rv) const { return mDate > rv.GetDate(); }\r
250 \r
251                 virtual ~Date() { }\r
252         };\r
253 \r
254         /* Class Time represent purely a Time. It is usefull in interactions\r
255          * with the SQL TIME type of Interbase. */\r
256 \r
257         class Time\r
258         {\r
259         protected:\r
260                 int mTime;      // The time, in ten-thousandths of seconds since midnight\r
261 \r
262         public:\r
263                 void Clear()    { mTime = 0; }\r
264                 void Now();\r
265                 void SetTime(int hour, int minute, int second, int tenthousandths = 0);\r
266                 void SetTime(int tm);\r
267                 void GetTime(int& hour, int& minute, int& second) const;\r
268                 void GetTime(int& hour, int& minute, int& second, int& tenthousandths) const;\r
269                 int GetTime() const     { return mTime; }\r
270                 int Hours() const;\r
271                 int Minutes() const;\r
272                 int Seconds() const;\r
273                 int SubSeconds() const;         // Actually tenthousandths of seconds\r
274                 Time()                  { Clear(); }\r
275                 Time(int tm)    { SetTime(tm); }\r
276                 Time(int hour, int minute, int second, int tenthousandths = 0);\r
277                 Time(const Time&);                                                      // Copy Constructor\r
278                 Time& operator=(const Timestamp&);                      // Timestamp Assignment operator\r
279                 Time& operator=(const Time&);                           // Time Assignment operator\r
280 \r
281                 bool operator==(const Time& rv) const { return mTime == rv.GetTime(); }\r
282                 bool operator!=(const Time& rv) const { return mTime != rv.GetTime(); }\r
283                 bool operator<(const Time& rv) const { return mTime < rv.GetTime(); }\r
284                 bool operator>(const Time& rv) const { return mTime > rv.GetTime(); }\r
285 \r
286                 virtual ~Time() { }\r
287         };\r
288 \r
289         /* Class Timestamp represent a date AND a time. It is usefull in\r
290          * interactions with the SQL TIMESTAMP type of Interbase. This class\r
291          * inherits from Date and Time and completely inline implements its small\r
292          * specific details. */\r
293 \r
294         class Timestamp : public Date, public Time\r
295         {\r
296         public:\r
297                 void Clear()    { Date::Clear(); Time::Clear(); }\r
298                 void Today()    { Date::Today(); Time::Clear(); }\r
299                 void Now()              { Date::Today(); Time::Now(); }\r
300 \r
301                 Timestamp()             { Clear(); }\r
302 \r
303                 Timestamp(int y, int m, int d)\r
304                         { Date::SetDate(y, m, d); Time::Clear(); }\r
305 \r
306                 Timestamp(int y, int mo, int d, int h, int mi, int s, int t = 0)\r
307                         { Date::SetDate(y, mo, d); Time::SetTime(h, mi, s, t); }\r
308 \r
309                 Timestamp(const Timestamp& rv)\r
310                         : Date(rv.mDate), Time(rv.mTime) {}     // Copy Constructor\r
311 \r
312                 Timestamp(const Date& rv)\r
313                         { mDate = rv.GetDate(); mTime = 0; }\r
314 \r
315                 Timestamp(const Time& rv)\r
316                         { mDate = 0; mTime = rv.GetTime(); }\r
317 \r
318                 Timestamp& operator=(const Timestamp& rv)       // Timestamp Assignment operator\r
319                         { mDate = rv.mDate; mTime = rv.mTime; return *this; }\r
320 \r
321                 Timestamp& operator=(const Date& rv)            // Date Assignment operator\r
322                         { mDate = rv.GetDate(); return *this; }\r
323 \r
324                 Timestamp& operator=(const Time& rv)            // Time Assignment operator\r
325                         { mTime = rv.GetTime(); return *this; }\r
326 \r
327                 bool operator==(const Timestamp& rv) const\r
328                         { return (mDate == rv.GetDate()) && (mTime == rv.GetTime()); }\r
329 \r
330                 bool operator!=(const Timestamp& rv) const\r
331                         { return (mDate != rv.GetDate()) || (mTime != rv.GetTime()); }\r
332 \r
333                 bool operator<(const Timestamp& rv) const\r
334                         { return (mDate < rv.GetDate()) ||\r
335                                 (mDate == rv.GetDate() && mTime < rv.GetTime()); }\r
336 \r
337                 bool operator>(const Timestamp& rv) const\r
338                         { return (mDate > rv.GetDate()) ||\r
339                                 (mDate == rv.GetDate() && mTime > rv.GetTime()); }\r
340 \r
341                 ~Timestamp() { }\r
342         };\r
343 \r
344         /* Class DBKey can store a DBKEY, that special value which the hidden\r
345          * RDB$DBKEY can give you from a select statement. A DBKey is nothing\r
346          * specific to IBPP. It's a feature of the Firebird database engine. See its\r
347          * documentation for more information. */\r
348 \r
349         class DBKey\r
350         {\r
351         private:\r
352                 std::string mDBKey;                     // Stores the binary DBKey\r
353                 mutable std::string mString;// String (temporary) representation of it\r
354 \r
355         public:\r
356                 void Clear();\r
357                 int Size() const        { return (int)mDBKey.size(); }\r
358                 void SetKey(const void*, int size);\r
359                 void GetKey(void*, int size) const;\r
360                 const char* AsString() const;\r
361 \r
362                 DBKey& operator=(const DBKey&); // Assignment operator\r
363                 DBKey(const DBKey&);                    // Copy Constructor\r
364                 DBKey() { }\r
365                 ~DBKey() { }\r
366         };\r
367 \r
368         /* Class User wraps all the information about a user that the engine can manage. */\r
369 \r
370         class User\r
371         {\r
372         public:\r
373                 std::string username;\r
374                 std::string password;\r
375                 std::string firstname;\r
376                 std::string middlename;\r
377                 std::string lastname;\r
378                 uint32_t userid;                // Only relevant on unixes\r
379                 uint32_t groupid;               // Only relevant on unixes\r
380 \r
381         private:\r
382                 void copyfrom(const User& r);\r
383 \r
384         public:\r
385                 void clear();\r
386                 User& operator=(const User& r)  { copyfrom(r); return *this; }\r
387                 User(const User& r)                             { copyfrom(r); }\r
388                 User() : userid(0), groupid(0)  { }\r
389                 ~User() { }\r
390         };\r
391 \r
392         //      Interface Wrapper\r
393         template <class T>\r
394         class Ptr\r
395         {\r
396         private:\r
397                 T* mObject;\r
398 \r
399         public:\r
400                 void clear()\r
401                 {\r
402                         if (mObject != 0) { mObject->Release(); mObject = 0; }\r
403                 }\r
404 \r
405                 T* intf() const                                         { return mObject; }\r
406                 T* operator->() const                           { return mObject; }\r
407 \r
408                 bool operator==(const T* p) const       { return mObject == p; }\r
409                 bool operator==(const Ptr& r) const     { return mObject == r.mObject; }\r
410                 bool operator!=(const T* p) const       { return mObject != p; }\r
411                 bool operator!=(const Ptr& r) const     { return mObject != r.mObject; }\r
412 \r
413                 Ptr& operator=(T* p)\r
414                 {\r
415                         // AddRef _before_ Release gives correct behaviour on self-assigns\r
416                         T* tmp = (p == 0 ? 0 : p->AddRef());    // Take care of 0\r
417                         if (mObject != 0) mObject->Release();\r
418                         mObject = tmp; return *this;\r
419                 }\r
420 \r
421                 Ptr& operator=(const Ptr& r)\r
422                 {\r
423                         // AddRef _before_ Release gives correct behaviour on self-assigns\r
424                         T* tmp = (r.intf() == 0 ? 0 : r->AddRef());// Take care of 0\r
425                         if (mObject != 0) mObject->Release();\r
426                         mObject = tmp; return *this;\r
427                 }\r
428 \r
429                 Ptr(T* p) : mObject(p == 0 ? 0 : p->AddRef()) { }\r
430                 Ptr(const Ptr& r) : mObject(r.intf() == 0 ? 0 : r->AddRef()) {  }\r
431 \r
432                 Ptr() : mObject(0) { }\r
433                 ~Ptr() { clear(); }\r
434         };\r
435 \r
436         //      --- Interface Classes --- //\r
437 \r
438         /* Interfaces IBlob, IArray, IService, IDatabase, ITransaction and\r
439          * IStatement are at the core of IBPP. Though it is possible to program your\r
440          * applications by using theses interfaces directly (as was the case with\r
441          * IBPP 1.x), you should refrain from using them and prefer the new IBPP\r
442          * Objects Blob, Array, ... (without the I in front). Those new objects are\r
443          * typedef'd right after each interface class definition as you can read\r
444          * below. If you program using the Blob (instead of the IBlob interface\r
445          * itself), you'll never have to care about AddRef/Release and you'll never\r
446          * have to care about deleting your objects. */\r
447 \r
448         class IBlob;                    typedef Ptr<IBlob> Blob;\r
449         class IArray;                   typedef Ptr<IArray> Array;\r
450         class IService;                 typedef Ptr<IService> Service;\r
451         class IDatabase;                typedef Ptr<IDatabase> Database;\r
452         class ITransaction;             typedef Ptr<ITransaction> Transaction;\r
453         class IStatement;               typedef Ptr<IStatement> Statement;\r
454         class IEvents;                  typedef Ptr<IEvents> Events;\r
455         class IRow;                             typedef Ptr<IRow> Row;\r
456 \r
457         /* IBlob is the interface to the blob capabilities of IBPP. Blob is the\r
458          * object class you actually use in your programming. In Firebird, at the\r
459          * row level, a blob is merely a handle to a blob, stored elsewhere in the\r
460          * database. Blob allows you to retrieve such a handle and then read from or\r
461          * write to the blob, much in the same manner than you would do with a file. */\r
462 \r
463         class IBlob\r
464         {\r
465         public:\r
466                 virtual void Create() = 0;\r
467                 virtual void Open() = 0;\r
468                 virtual void Close() = 0;\r
469                 virtual void Cancel() = 0;\r
470                 virtual int Read(void*, int size) = 0;\r
471                 virtual void Write(const void*, int size) = 0;\r
472                 virtual void Info(int* Size, int* Largest, int* Segments) = 0;\r
473         \r
474                 virtual void Save(const std::string& data) = 0;\r
475                 virtual void Load(std::string& data) = 0;\r
476 \r
477                 virtual Database DatabasePtr() const = 0;\r
478                 virtual Transaction TransactionPtr() const = 0;\r
479 \r
480                 virtual IBlob* AddRef() = 0;\r
481                 virtual void Release() = 0;\r
482 \r
483                 virtual ~IBlob() { }\r
484         };\r
485 \r
486         /*      IArray is the interface to the array capabilities of IBPP. Array is the\r
487         * object class you actually use in your programming. With an Array object, you\r
488         * can create, read and write Interbase Arrays, as a whole or in slices. */\r
489 \r
490         class IArray\r
491         {\r
492         public:\r
493                 virtual void Describe(const std::string& table, const std::string& column) = 0;\r
494                 virtual void ReadTo(ADT, void* buffer, int elemcount) = 0;\r
495                 virtual void WriteFrom(ADT, const void* buffer, int elemcount) = 0;\r
496                 virtual SDT ElementType() = 0;\r
497                 virtual int ElementSize() = 0;\r
498                 virtual int ElementScale() = 0;\r
499                 virtual int Dimensions() = 0;\r
500                 virtual void Bounds(int dim, int* low, int* high) = 0;\r
501                 virtual void SetBounds(int dim, int low, int high) = 0;\r
502 \r
503                 virtual Database DatabasePtr() const = 0;\r
504                 virtual Transaction TransactionPtr() const = 0;\r
505 \r
506                 virtual IArray* AddRef() = 0;\r
507                 virtual void Release() = 0;\r
508 \r
509                 virtual ~IArray() { }\r
510         };\r
511 \r
512         /* IService is the interface to the service capabilities of IBPP. Service is\r
513          * the object class you actually use in your programming. With a Service\r
514          * object, you can do some maintenance work of databases and servers\r
515          * (backup, restore, create/update users, ...) */\r
516 \r
517         class IService\r
518         {\r
519         public:\r
520             virtual void Connect() = 0;\r
521                 virtual bool Connected() = 0;\r
522                 virtual void Disconnect() = 0;\r
523 \r
524                 virtual void GetVersion(std::string& version) = 0;\r
525 \r
526                 virtual void AddUser(const User&) = 0;\r
527                 virtual void GetUser(User&) = 0;\r
528                 virtual void GetUsers(std::vector<User>&) = 0;\r
529                 virtual void ModifyUser(const User&) = 0;\r
530                 virtual void RemoveUser(const std::string& username) = 0;\r
531 \r
532                 virtual void SetPageBuffers(const std::string& dbfile, int buffers) = 0;\r
533                 virtual void SetSweepInterval(const std::string& dbfile, int sweep) = 0;\r
534                 virtual void SetSyncWrite(const std::string& dbfile, bool) = 0;\r
535                 virtual void SetReadOnly(const std::string& dbfile, bool) = 0;\r
536                 virtual void SetReserveSpace(const std::string& dbfile, bool) = 0;\r
537 \r
538                 virtual void Shutdown(const std::string& dbfile, DSM mode, int sectimeout) = 0;\r
539                 virtual void Restart(const std::string& dbfile) = 0;\r
540                 virtual void Sweep(const std::string& dbfile) = 0;\r
541                 virtual void Repair(const std::string& dbfile, RPF flags) = 0;\r
542 \r
543                 virtual void StartBackup(const std::string& dbfile,\r
544                         const std::string& bkfile, BRF flags = BRF(0)) = 0;\r
545                 virtual void StartRestore(const std::string& bkfile, const std::string& dbfile,\r
546                         int pagesize = 0, BRF flags = BRF(0)) = 0;\r
547 \r
548                 virtual const char* WaitMsg() = 0;      // With reporting (does not block)\r
549                 virtual void Wait() = 0;                        // Without reporting (does block)\r
550 \r
551                 virtual IService* AddRef() = 0;\r
552                 virtual void Release() = 0;\r
553 \r
554                 virtual ~IService() { }\r
555         };\r
556 \r
557         /*      IDatabase is the interface to the database connections in IBPP. Database\r
558          * is the object class you actually use in your programming. With a Database\r
559          * object, you can create/drop/connect databases. */\r
560 \r
561         class EventInterface;   // Cross-reference between EventInterface and IDatabase\r
562         \r
563         class IDatabase\r
564         {\r
565         public:\r
566                 virtual const char* ServerName() const = 0;\r
567                 virtual const char* DatabaseName() const = 0;\r
568                 virtual const char* Username() const = 0;\r
569                 virtual const char* UserPassword() const = 0;\r
570                 virtual const char* RoleName() const = 0;\r
571                 virtual const char* CharSet() const = 0;\r
572                 virtual const char* CreateParams() const = 0;\r
573 \r
574                 virtual void Info(int* ODS, int* ODSMinor, int* PageSize,\r
575                         int* Pages,     int* Buffers, int* Sweep, bool* Sync,\r
576                         bool* Reserve) = 0;\r
577                 virtual void Statistics(int* Fetches, int* Marks,\r
578                         int* Reads, int* Writes) = 0;\r
579                 virtual void Counts(int* Insert, int* Update, int* Delete, \r
580                         int* ReadIdx, int* ReadSeq) = 0;\r
581                 virtual void Users(std::vector<std::string>& users) = 0;\r
582                 virtual int Dialect() = 0;\r
583 \r
584                 virtual void Create(int dialect) = 0;\r
585                 virtual void Connect() = 0;\r
586                 virtual bool Connected() = 0;\r
587                 virtual void Inactivate() = 0;\r
588                 virtual void Disconnect() = 0;\r
589                 virtual void Drop() = 0;\r
590 \r
591                 virtual IDatabase* AddRef() = 0;\r
592                 virtual void Release() = 0;\r
593 \r
594             virtual ~IDatabase() { }\r
595         };\r
596 \r
597         /* ITransaction is the interface to the transaction connections in IBPP.\r
598          * Transaction is the object class you actually use in your programming. A\r
599          * Transaction object can be associated with more than one Database,\r
600          * allowing for distributed transactions spanning multiple databases,\r
601          * possibly located on different servers. IBPP is one among the few\r
602          * programming interfaces to Firebird that allows you to support distributed\r
603          * transactions. */\r
604 \r
605         class ITransaction\r
606         {\r
607         public:\r
608             virtual void AttachDatabase(Database db, TAM am = amWrite,\r
609                         TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0)) = 0;\r
610             virtual void DetachDatabase(Database db) = 0;\r
611                 virtual void AddReservation(Database db,\r
612                                 const std::string& table, TTR tr) = 0;\r
613 \r
614                 virtual void Start() = 0;\r
615                 virtual bool Started() = 0;\r
616             virtual void Commit() = 0;\r
617             virtual void Rollback() = 0;\r
618             virtual void CommitRetain() = 0;\r
619                 virtual void RollbackRetain() = 0;\r
620 \r
621                 virtual ITransaction* AddRef() = 0;\r
622                 virtual void Release() = 0;\r
623 \r
624             virtual ~ITransaction() { }\r
625         };\r
626 \r
627         /*\r
628          *      Class Row can hold all the values of a row (from a SELECT for instance).\r
629          */\r
630 \r
631         class IRow\r
632         {\r
633         public:\r
634                 virtual void SetNull(int) = 0;\r
635                 virtual void Set(int, bool) = 0;\r
636                 virtual void Set(int, const void*, int) = 0;            // byte buffers\r
637                 virtual void Set(int, const char*) = 0;                         // c-string\r
638                 virtual void Set(int, const std::string&) = 0;\r
639                 virtual void Set(int, int16_t) = 0;\r
640                 virtual void Set(int, int32_t) = 0;\r
641                 virtual void Set(int, int64_t) = 0;\r
642                 virtual void Set(int, float) = 0;\r
643                 virtual void Set(int, double) = 0;\r
644                 virtual void Set(int, const Timestamp&) = 0;\r
645                 virtual void Set(int, const Date&) = 0;\r
646                 virtual void Set(int, const Time&) = 0;\r
647                 virtual void Set(int, const DBKey&) = 0;\r
648                 virtual void Set(int, const Blob&) = 0;\r
649                 virtual void Set(int, const Array&) = 0;\r
650 \r
651                 virtual bool IsNull(int) = 0;\r
652                 virtual bool Get(int, bool&) = 0;\r
653                 virtual bool Get(int, void*, int&) = 0; // byte buffers\r
654                 virtual bool Get(int, std::string&) = 0;\r
655                 virtual bool Get(int, int16_t&) = 0;\r
656                 virtual bool Get(int, int32_t&) = 0;\r
657                 virtual bool Get(int, int64_t&) = 0;\r
658                 virtual bool Get(int, float&) = 0;\r
659                 virtual bool Get(int, double&) = 0;\r
660                 virtual bool Get(int, Timestamp&) = 0;\r
661                 virtual bool Get(int, Date&) = 0;\r
662                 virtual bool Get(int, Time&) = 0;\r
663                 virtual bool Get(int, DBKey&) = 0;\r
664                 virtual bool Get(int, Blob&) = 0;\r
665                 virtual bool Get(int, Array&) = 0;\r
666 \r
667                 virtual bool IsNull(const std::string&) = 0;\r
668                 virtual bool Get(const std::string&, bool&) = 0;\r
669                 virtual bool Get(const std::string&, void*, int&) = 0;  // byte buffers\r
670                 virtual bool Get(const std::string&, std::string&) = 0;\r
671                 virtual bool Get(const std::string&, int16_t&) = 0;\r
672                 virtual bool Get(const std::string&, int32_t&) = 0;\r
673                 virtual bool Get(const std::string&, int64_t&) = 0;\r
674                 virtual bool Get(const std::string&, float&) = 0;\r
675                 virtual bool Get(const std::string&, double&) = 0;\r
676                 virtual bool Get(const std::string&, Timestamp&) = 0;\r
677                 virtual bool Get(const std::string&, Date&) = 0;\r
678                 virtual bool Get(const std::string&, Time&) = 0;\r
679                 virtual bool Get(const std::string&, DBKey&) = 0;\r
680                 virtual bool Get(const std::string&, Blob&) = 0;\r
681                 virtual bool Get(const std::string&, Array&) = 0;\r
682 \r
683                 virtual int ColumnNum(const std::string&) = 0;\r
684                 virtual const char* ColumnName(int) = 0;\r
685                 virtual const char* ColumnAlias(int) = 0;\r
686                 virtual const char* ColumnTable(int) = 0;\r
687                 virtual SDT ColumnType(int) = 0;\r
688                 virtual int ColumnSubtype(int) = 0;\r
689                 virtual int ColumnSize(int) = 0;\r
690                 virtual int ColumnScale(int) = 0;\r
691                 virtual int Columns() = 0;\r
692                 \r
693                 virtual bool ColumnUpdated(int) = 0;\r
694                 virtual bool Updated() = 0;\r
695 \r
696                 virtual Database DatabasePtr() const = 0;\r
697                 virtual Transaction TransactionPtr() const = 0;\r
698 \r
699                 virtual IRow* Clone() = 0;\r
700                 virtual IRow* AddRef() = 0;\r
701                 virtual void Release() = 0;\r
702 \r
703             virtual ~IRow() {}\r
704         };\r
705 \r
706         /* IStatement is the interface to the statements execution in IBPP.\r
707          * Statement is the object class you actually use in your programming. A\r
708          * Statement object is the work horse of IBPP. All your data manipulation\r
709          * statements will be done through it. It is also used to access the result\r
710          * set of a query (when the statement is such), one row at a time and in\r
711          * strict forward direction. */\r
712 \r
713         class IStatement\r
714         {\r
715         public:\r
716                 virtual void Prepare(const std::string&) = 0;\r
717                 virtual void Execute() = 0;\r
718                 virtual void Execute(const std::string&) = 0;\r
719                 virtual void ExecuteImmediate(const std::string&) = 0;\r
720                 virtual void CursorExecute(const std::string& cursor) = 0;\r
721                 virtual void CursorExecute(const std::string& cursor, const std::string&) = 0;\r
722                 virtual bool Fetch() = 0;\r
723                 virtual bool Fetch(Row&) = 0;\r
724                 virtual int AffectedRows() = 0;\r
725                 virtual void Close() = 0;\r
726                 virtual std::string& Sql() = 0;\r
727                 virtual STT Type() = 0;\r
728 \r
729                 virtual void SetNull(int) = 0;\r
730                 virtual void Set(int, bool) = 0;\r
731                 virtual void Set(int, const void*, int) = 0;            // byte buffers\r
732                 virtual void Set(int, const char*) = 0;                         // c-string\r
733                 virtual void Set(int, const std::string&) = 0;\r
734                 virtual void Set(int, int16_t value) = 0;\r
735                 virtual void Set(int, int32_t value) = 0;\r
736                 virtual void Set(int, int64_t value) = 0;\r
737                 virtual void Set(int, float value) = 0;\r
738                 virtual void Set(int, double value) = 0;\r
739                 virtual void Set(int, const Timestamp& value) = 0;\r
740                 virtual void Set(int, const Date& value) = 0;\r
741                 virtual void Set(int, const Time& value) = 0;\r
742                 virtual void Set(int, const DBKey& value) = 0;\r
743                 virtual void Set(int, const Blob& value) = 0;\r
744                 virtual void Set(int, const Array& value) = 0;\r
745 \r
746                 virtual bool IsNull(int) = 0;\r
747                 virtual bool Get(int, bool&) = 0;\r
748                 virtual bool Get(int, void*, int&) = 0; // byte buffers\r
749                 virtual bool Get(int, std::string&) = 0;\r
750                 virtual bool Get(int, int16_t&) = 0;\r
751                 virtual bool Get(int, int32_t&) = 0;\r
752                 virtual bool Get(int, int64_t&) = 0;\r
753                 virtual bool Get(int, float&) = 0;\r
754                 virtual bool Get(int, double&) = 0;\r
755                 virtual bool Get(int, Timestamp& value) = 0;\r
756                 virtual bool Get(int, Date& value) = 0;\r
757                 virtual bool Get(int, Time& value) = 0;\r
758                 virtual bool Get(int, DBKey& value) = 0;\r
759                 virtual bool Get(int, Blob& value) = 0;\r
760                 virtual bool Get(int, Array& value) = 0;\r
761 \r
762                 virtual bool IsNull(const std::string&) = 0;\r
763                 virtual bool Get(const std::string&, bool&) = 0;\r
764                 virtual bool Get(const std::string&, void*, int&) = 0;  // byte buffers\r
765                 virtual bool Get(const std::string&, std::string&) = 0;\r
766                 virtual bool Get(const std::string&, int16_t&) = 0;\r
767                 virtual bool Get(const std::string&, int32_t&) = 0;\r
768                 virtual bool Get(const std::string&, int64_t&) = 0;\r
769                 virtual bool Get(const std::string&, float&) = 0;\r
770                 virtual bool Get(const std::string&, double&) = 0;\r
771                 virtual bool Get(const std::string&, Timestamp& value) = 0;\r
772                 virtual bool Get(const std::string&, Date& value) = 0;\r
773                 virtual bool Get(const std::string&, Time& value) = 0;\r
774                 virtual bool Get(const std::string&, DBKey& value) = 0;\r
775                 virtual bool Get(const std::string&, Blob& value) = 0;\r
776                 virtual bool Get(const std::string&, Array& value) = 0;\r
777 \r
778                 virtual int ColumnNum(const std::string&) = 0;\r
779                 virtual const char* ColumnName(int) = 0;\r
780                 virtual const char* ColumnAlias(int) = 0;\r
781                 virtual const char* ColumnTable(int) = 0;\r
782                 virtual SDT ColumnType(int) = 0;\r
783                 virtual int ColumnSubtype(int) = 0;\r
784                 virtual int ColumnSize(int) = 0;\r
785                 virtual int ColumnScale(int) = 0;\r
786                 virtual int Columns() = 0;\r
787 \r
788                 virtual SDT ParameterType(int) = 0;\r
789                 virtual int ParameterSubtype(int) = 0;\r
790                 virtual int ParameterSize(int) = 0;\r
791                 virtual int ParameterScale(int) = 0;\r
792                 virtual int Parameters() = 0;\r
793 \r
794                 virtual void Plan(std::string&) = 0;\r
795 \r
796                 virtual Database DatabasePtr() const = 0;\r
797                 virtual Transaction TransactionPtr() const = 0;\r
798 \r
799                 virtual IStatement* AddRef() = 0;\r
800                 virtual void Release() = 0;\r
801 \r
802             virtual ~IStatement() { }\r
803 \r
804                 // DEPRECATED METHODS (WON'T BE AVAILABLE IN VERSIONS 3.x)\r
805                 virtual bool Get(int, char*) = 0;                                       // DEPRECATED\r
806                 virtual bool Get(const std::string&, char*) = 0;        // DEPRECATED\r
807                 virtual bool Get(int, bool*) = 0;                                       // DEPRECATED\r
808                 virtual bool Get(const std::string&, bool*) = 0;        // DEPRECATED\r
809                 virtual bool Get(int, int16_t*) = 0;                            // DEPRECATED\r
810                 virtual bool Get(const std::string&, int16_t*) = 0;     // DEPRECATED\r
811                 virtual bool Get(int, int32_t*) = 0;                            // DEPRECATED\r
812                 virtual bool Get(const std::string&, int32_t*) = 0;     // DEPRECATED\r
813                 virtual bool Get(int, int64_t*) = 0;                            // DEPRECATED\r
814                 virtual bool Get(const std::string&, int64_t*) = 0;     // DEPRECATED\r
815                 virtual bool Get(int, float*) = 0;                                      // DEPRECATED\r
816                 virtual bool Get(const std::string&, float*) = 0;       // DEPRECATED\r
817                 virtual bool Get(int, double*) = 0;                                     // DEPRECATED\r
818                 virtual bool Get(const std::string&, double*) = 0;      // DEPRECATED\r
819         };\r
820         \r
821         class IEvents\r
822         {\r
823         public:\r
824                 virtual void Add(const std::string&, EventInterface*) = 0;\r
825                 virtual void Drop(const std::string&) = 0;\r
826                 virtual void List(std::vector<std::string>&) = 0;\r
827                 virtual void Clear() = 0;                               // Drop all events\r
828                 virtual void Dispatch() = 0;                    // Dispatch events (calls handlers)\r
829 \r
830                 virtual Database DatabasePtr() const = 0;\r
831 \r
832                 virtual IEvents* AddRef() = 0;\r
833                 virtual void Release() = 0;\r
834 \r
835             virtual ~IEvents() { }\r
836         };\r
837         \r
838         /* Class EventInterface is merely a pure interface.\r
839          * It is _not_ implemented by IBPP. It is only a base class definition from\r
840          * which your own event interface classes have to derive from.\r
841          * Please read the reference guide at http://www.ibpp.org for more info. */\r
842 \r
843         class EventInterface\r
844         {\r
845         public:\r
846                 virtual void ibppEventHandler(Events, const std::string&, int) = 0;\r
847                 virtual ~EventInterface() { }\r
848         };\r
849 \r
850         //      --- Factories ---\r
851         //      These methods are the only way to get one of the above\r
852         //      Interfaces.  They are at the heart of how you program using IBPP.  For\r
853         //      instance, to get access to a database, you'll write code similar to this:\r
854         //      {\r
855         //              Database db = DatabaseFactory("server", "databasename",\r
856         //                                              "user", "password");\r
857         //              db->Connect();\r
858         //              ...\r
859         //              db->Disconnect();\r
860         //      }\r
861 \r
862         Service ServiceFactory(const std::string& ServerName,\r
863                 const std::string& UserName, const std::string& UserPassword);\r
864 \r
865         Database DatabaseFactory(const std::string& ServerName,\r
866                 const std::string& DatabaseName, const std::string& UserName,\r
867                         const std::string& UserPassword, const std::string& RoleName,\r
868                                 const std::string& CharSet, const std::string& CreateParams);\r
869 \r
870         inline Database DatabaseFactory(const std::string& ServerName,\r
871                 const std::string& DatabaseName, const std::string& UserName,\r
872                         const std::string& UserPassword)\r
873                 { return DatabaseFactory(ServerName, DatabaseName, UserName, UserPassword, "", "", ""); }\r
874 \r
875         Transaction TransactionFactory(Database db, TAM am = amWrite,\r
876                 TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0));\r
877 \r
878         Statement StatementFactory(Database db, Transaction tr,\r
879                 const std::string& sql);\r
880 \r
881         inline Statement StatementFactory(Database db, Transaction tr)\r
882                 { return StatementFactory(db, tr, ""); }\r
883 \r
884         Blob BlobFactory(Database db, Transaction tr);\r
885         \r
886         Array ArrayFactory(Database db, Transaction tr);\r
887         \r
888         Events EventsFactory(Database db);\r
889 \r
890         /* IBPP uses a self initialization system. Each time an object that may\r
891          * require the usage of the Interbase client C-API library is used, the\r
892          * library internal handling details are automatically initialized, if not\r
893          * already done. You can kick this initialization at the start of an\r
894          * application by calling IBPP::CheckVersion(). This is recommended, because\r
895          * IBPP::CheckVersion will assure you that YOUR code has been compiled\r
896          * against a compatible version of the library. */\r
897 \r
898         bool CheckVersion(uint32_t);\r
899         int GDSVersion();\r
900         \r
901         /* On Win32 platform, ClientLibSearchPaths() allows to setup\r
902          * one or multiple additional paths (separated with a ';') where IBPP\r
903          * will look for the client library (before the default implicit search\r
904          * locations). This is usefull for applications distributed with a 'private'\r
905          * copy of Firebird, when the registry is useless to identify the location\r
906          * from where to attempt loading the fbclient.dll / gds32.dll.\r
907          * If called, this function must be called *early* by the application,\r
908          * before *any* other function or object methods of IBPP.\r
909          * Currently, this is a NO-OP on platforms other than Win32. */\r
910          \r
911         void ClientLibSearchPaths(const std::string&);\r
912 \r
913         /* Finally, here are some date and time conversion routines used by IBPP and\r
914          * that may be helpful at the application level. They do not depend on\r
915          * anything related to Firebird/Interbase. Just a bonus. dtoi and itod\r
916          * return false on invalid parameters or out of range conversions. */\r
917 \r
918         bool dtoi(int date, int* py, int* pm, int* pd);\r
919         bool itod(int* pdate, int year, int month, int day);\r
920         void ttoi(int itime, int* phour, int* pminute, int* psecond, int* ptt);\r
921         void itot(int* ptime, int hour, int minute, int second = 0, int tenthousandths = 0);\r
922 \r
923 }\r
924 \r
925 #endif\r
926 \r
927 //\r
928 //      EOF\r
929 //\r