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.
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.
The DriverFactory is used to build and get access to a Driver object.
Driver DriverFactory();
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:
DefaultInstance registry value of the SOFTWARE\Firebird Project\Firebird Server\Instances registry key,
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:
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.
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
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:
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:
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.
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
Returns true if the Firebird client library encapsulated by the Driver object is actually loaded and ready for use.
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.
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.