IBPP::Driver

This is preliminary documentation regarding the unreleased version 3.0.

The IBPP::Driver Interface represents a single instance of one Firebird or Interbase client library. It is through such a Driver instance that you will get all other interfaces of IBPP. So this is the most basic building block of any IBPP based host program.

Definition

See the file ibpp.h for an up-to-date definition of the interface. Lookup the IDriver class.

Like the other building blocks of IBPP, the actual interface class is a pure virtual class (here named IBPP::IDriver). This is the closest thing in C++ to a pure interface concept. The real working object 'behind' (IBPP internals) is derived from this 'contract' class. As long as the signature of this IDatabase class does not change, your code is binary compatible with IBPP, even if internal details of the real work-class behind have changed.

As with other IBPP building blocks, you cannot instantiate this class by yourself (due to its pure virtual methods). You also can't derive your own class from this one, due to the protected constructor and destructor. You have to get an instance from IBPP through the corresponding Factory function call.

DriverFactory

The DriverFactory is used to build and get access to a Driver object.

Driver DriverFactory();

Driver members

void Load(const std::string& paths = "", const std::string& names = "") --- Windows Version

IBPP will try to load a driver (client library) from the directories whose names are listed in the semi-column delimited string paths, in the order they are listed. If this paths parameter is left empty, here is the default ordered list tried by IBPP:

  1. the host application executable directory,
  2. the directory specified by the DefaultInstance registry value of the SOFTWARE\Firebird Project\Firebird Server\Instances registry key,
  3. no path specified, such that the system will choose locations from which to try (usually the system directories)

Should you need to list those system location among your specific list of paths, you can do so by using the three string macros: APP$, REG$, and SYS$ (they are case sensitive). You can also use the content of environment variables by listing them with a starting $ sign, like in $MYPATH.

For each of these paths, IBPP will try to load drivers whose names are listed in the semi-column delimited string names, in the order they are listed. If this names parameter is left empty, here is the default ordered list tried by IBPP:

  1. fbembed.dll
  2. fbclient.dll
  3. gds32.dll

You can also use the content of environment variables by listing them with a starting $ sign, like in $FBDRIVER.

This scheme gives full flexibility at the application level to control, or not control, which exact driver is loaded and from which location.

Some examples

Load();
Load("APP$;REG$;SYS$", "fbembed.dll;fbclient.dll;gds32.dll");
// these calls are equivalent

Load("APP$", "fbclient.dll");
// will only attempt loading fbclient.dll from the host application directory

Load("$MYPATH;APP$", "fbclient.dll");
// will only attempt loading fbclient.dll from the path represented by
// the MYPATH environment variable, and the host application directory

Load("APP$;SYS$", "");
// will try loading fbembed.dll, fbclient.dll, or gds32.dll from the host
// application directory, and from implicit system locations

void Load(const std::string& paths = "", const std::string& name = "") --- Unix Version

IBPP will try to load a driver (client library) from the directories whose names are listed in the semi-column delimited string paths, in the order they are listed. If this paths parameter is left empty, here is the default ordered list tried by IBPP:

  1. the host application executable directory,
  2. no path specified, such that the system will choose locations from which to try (usually the system directories)

Should you need to list those system location among your specific list of paths, you can do so by using the two string macros: APP$, and SYS$ (they are case sensitive). You can also use the content of environment variables by listing them with a starting $ sign, like in $MYPATH.

For each of these paths, IBPP will try to load drivers whose names are listed in the semi-column delimited string names, in the order they are listed. If this names parameter is left empty, here is the default ordered list tried by IBPP:

  1. libfbembed.so
  2. libfbclient.so
  3. libgds32.so

You can also use the content of environment variables by listing them with a starting $ sign, like in $FBDRIVER.

This scheme gives full flexibility at the application level to control, or not control, which exact driver is loaded and from which location.

It should be noted that before version 3.0, IBPP unix versions were statically linked to the Firebird client library.

Some examples

Load();
Load("APP$;SYS$", "libfbembed.so;libfbclient.so;libgds32.so");
// these calls are equivalent

Load("APP$", "libfbclient-1.5.so");
// will only attempt loading libfbclient-1.5.so from the host application directory

Load("$MYPATH;APP$", "libfbclient.so");
// will only attempt loading libfbclient.so from the path represented by
// the MYPATH environment variable, and the host application directory

Load("APP$;SYS$", "");
// will try loading libfbembed.so, libfbclient.so, or libgds32.so from the host
// application directory, and from implicit system locations

bool Loaded()

Returns true if the Firebird client library encapsulated by the Driver object is actually loaded and ready for use.

void Unload()

Completely unloads the Driver from memory. This imply rendering idle all other objects obtained through this previous driver instance. To achieve this, Unload() will actively Disconnect() all Service and Database instances obtained through this driver. This will indeed rollback any started transaction. Don't Unload() needlessly or at wrong times, or risk uncommitted work be lost.

void GetVersion(std::string& version)

Attempts to return a string describing the exact version of the loaded client library. Some libraries offer an API to retrieve such a client versioning string, while older libraries do not. If IBPP can get an answer from the library, it returns this string as is. If it can't use an existing API to get this information, IBPP builds up a string by itself based on characteristics of the main library file, if it can identify it. If IBPP cannot possibly give useful information, the string will be cleared.

Factories members

Service ServiceFactory()

Database DatabaseFactory()

Transaction TransactionFactory()

Statement StatementFactory()

Blob BlobFactory()

Array ArrayFactory()

Events EventsFactory()

reference/driver.txt · Last modified: 2006/06/07 00:52 (external edit)
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki