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