The IBPP::Service Interface represents a single connection to the Firebird service manager. Such a connection is used for various maintenance work.
See the file ibpp.h for an up-to-date definition of the interface. Lookup the IService class.
Like the other building blocks of IBPP, the actual interface class is a pure virtual class (here named IBPP::IService). 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 IService 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.
ServiceFactory is used to build and get access to a Service object.
Service ServiceFactory(const std::string& ServerName,
const std::string& UserName, const std::string& UserPassword);
Simply, to connect a Service interface requires a Server name, a User name and a password.
Connects to the service manager, using the strings provided on the ServiceFactory call.
Returns true if the Service object is currently attached to the service manager.
Disconnects from the service manager.
Returns the version string of the engine, exactly as the engine reported it.
Creates a user (or fails if it already exists). The key is the User::username field. All other fields are stored, provided they are not empty strings or zeroes.
Lookups the user identified by the User::username field (fails if not found) and retrieve its information.
Retrieves all users and their information.
Lookups the user identified by the User::username field (fails if not found) and update its information with all User members which are not empty strings or zeroes. That is to update only the middlename, leaving other fields intact, fill in only the username (for lookup) and the middlename (for udpate). Leave the others fields to empty strings and the userid and groupid set at zero : they won't be updated.
Remove a user, looking it up through its username. Fails if the user is not found.
Changes the default number of pages used by the cache of the database. The database is identified by its main filename. See the Firebird documentation for more information.
Changes the default sweep interval of the database identified by its main filename. See the Firebird documentation for more information.
When passed true, activates the synchronized writes, also named forced-writes. Disables them when passed false. See the Firebird documentation for more information.
Turns the database to read-only mode, or turn it off (read-write/normal), following the boolean parameter. See the Firebird documentation for more information.
Turns on or off the reserver space mechanism of the database. See the Firebird documentation for more information.
Used to shutdown a database. Shutting down a database consists of properly denying connections from other users than the SYSDBA or owner user. The dbfile is the main filename of the database to act upon. It is relative to the server machine. The DSM mode and the timeout controls the way the shutdown is accomplished. Please see Firebird documentation for more information. The timeout specifies how many seconds are given to the shutdown to be effective or not.
The DSM enumeration brings the dsForce, dsDenyTrans and dsDenyAttach constants to control, according to Firebird documentation, how the shutdown is done.
The reverse of a shutdown, brings back a database online such that all users can normally attach to it.
Start a sweep over the database whose main file name is given as dbfile. That file name is relative to the server machine. The sweep is the process known as garbage collection. Such a process can automatically run cooperatively with other database activites or forced to execute through this call.
Allows to run some repairing actions over a possibly damaged database. This is advanced usage and we advise you to carefully review Firebird documentation before usage. Focus on the gfix command-line utility which this Service method is partially an equivalent.
The RPF flags parameter of the Repair method allows to set various modes of repairing actions, and specifying options.
Mutually exclusive modes :
Options on these actions :
Starts a backup job ('gbak' like, at the server side). The dbfile is the database main filename, the backupfile is the target file that will be created or overwritten. And the optional BRF flags parameter allows for finer control of the backup procedure. Both files are relatives to the server machine.
StartBackup is an asynchronous method. It returns immediately. See the WaitMsg() and Wait() methods for more information.
The BRF enumeration brings numerous flags to control various characteristics of the backup or restore procedures.
The flags which are valid for a Backup operation are :
Please refer to Firebird documentation for detailed information. Those flags have a name in IBPP which clearly map to their relative concept in Firebird. For most usages, not using the BRF flags parameter (which sets it to the default of 0, no flags) is adequate. The most used flag is brVerbose, which only controls the verbosity of the report while the backup runs.
Starts a restore job ('gbak' like, at the server side). The backupfile is the source file containing the backup which will be read and dbfile is the database main filename which will be created. By default, the restore fails if the database file exists, though this is a feature of Firebird itself to check this, so beware of bugs there that might let you trash an existing DB. The optional BRF flags parameter allows for finer control of the restore procedure. Both files are relatives to the server machine.
StartRestore is an asynchronous method. It returns immediately. See the WaitMsg() and Wait() methods for more information.
The BRF enumeration brings numerous flags to control various characteristics of the backup or restore procedures.
The flags which are valid for a Restore operation are :
Please refer to Firebird documentation for detailed information. Those flags have a name in IBPP which clearly map to their relative concept in Firebird. For most usages, not using the BRF flags parameter (which sets it to the default of 0, no flags) is adequate. The most used flag is brVerbose, which only controls the verbosity of the report while the restore runs.
The Service methods whose name begins with the word 'Start' (namely the StartBackup and the StartRestore) are asynchronous methods, possibly returning a quite large amount of log data while they run. The methods StartBackup and StartRestore immediately return when the operation was successfully started (else, an exception is thrown). The host application must somehow wait for the operation to end (or check wether it ended). This is done through the methods WaitMsg() or Wait().
WaitMsg() is a non blocking call, designed to be called in a loop (or polled in other conditions. If its return value is 0 (null pointer), the operation ended. If the returned pointer is not null, the operation is still running (or there still is some log info to retrieve). In such case, the returned pointer points to a C-string containing one line of log information. The host program is then free to display it or save it.
The Wait() method is useful when application finally don't want to report on the progress of the started operation. The Wait() is a blocking call. It will only return when the previously started operation will end (or immediately if it already ended between the Start… call and the Wait() call).