libs/ibpp/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 <cstdint>                      // 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