ïż

reference:service [www.ibpp.org]










[[reference:service]]

http://www.ibpp.org/












 


You are here: ibpp  reference  service


Table of Contents



IBPP::Service


Definition

ServiceFactory

Methods
(general)

Methods
(User Management)

Methods
(Database Settings)

Methods
(Database Maintenance)

Service
methods (Backup / Restore)
IBPP::Service

The IBPP::Service Interface represents a single connection to the Firebird
service manager. Such a connection is used for various maintenance work.

Definition

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

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.
Methods (general)

void Connect()

Connects to the service manager, using the strings provided on the
ServiceFactory call.
bool Connected()

Returns true if the Service object is currently attached to the service
manager.
void Disconnect()

Disconnects from the service manager.
void GetVersion(std::string&
version)

Returns the version string of the engine, exactly as the engine reported it.

Methods (User
Management)

void
AddUser(const User& user)

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.
void
GetUser(User& user)

Lookups the user identified by the User::username field (fails if not
found) and retrieve its information.
void
GetUsers(std::vector<User>& users)

Retrieves all users and their information.
void ModifyUser(const User&
user)

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.
void RemoveUser(const
std::string& username)

Remove a user, looking it up through its username. Fails if the user is not
found.
Methods
(Database Settings)

void
SetPageBuffers(const std::string& dbfile, int buffers)

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.
void
SetSweepInterval(const std::string& dbfile, int sweep)

Changes the default sweep interval of the database identified by its main
filename. See the Firebird documentation for more information.
void SetSyncWrite(const
std::string& dbfile, bool)

When passed true, activates the synchronized writes, also named
forced-writes. Disables them when passed false. See the Firebird documentation
for more information.
void SetReadOnly(const
std::string& dbfile, bool)

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.
void SetReserveSpace(const
std::string& dbfile, bool)

Turns on or off the reserver space mechanism of the database. See the
Firebird documentation for more information.
Methods
(Database Maintenance)

void
Shutdown(const std::string& dbfile, DSM mode, int timeout)

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.
DSM :
Database Shutdown Mode

The DSM enumeration brings the dsForce, dsDenyTrans and dsDenyAttach
constants to control, according to Firebird documentation, how the shutdown is
done.
void Restart(const std::string&
dbfile)

The reverse of a shutdown, brings back a database online such that all users
can normally attach to it.
void Sweep(const std::string&
dbfile)

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.
void Repair(const
std::string& dbfile, RPF flags)

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.
RPF : Repair Flags

The RPF flags parameter of the Repair method allows to set various modes of
repairing actions, and specifying options.
Mutually exclusive modes :


rpMendRecords

rpValidatePages

rpValidateFull
Options on these actions :


rpReadOnly

rpIgnoreChecksums

rpKillShadows
Service methods (Backup / Restore)

void
StartBackup(const std::string& dbfile, const std::string& backupfile,
BRF flags = BRF(0))

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.
BRF : Backup
Restore Flags

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 :


brVerbose

brIgnoreChecksums

brIgnoreLimbo

brMetadataOnly

brNoGarbageCollect

brNontransportable

brConvertExtTables
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.
void
StartRestore(const std::string& backupfile, const std::string& dbfile,
int pagesize, BRF flags = BRF(0))

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.
BRF : Backup
Restore Flags

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 :


brVerbose

brReplace

brDeactivateIdx

brNoShadow

brNoValidity

brPerTableCommit

brUseAllSpace
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.
const char*
WaitMsg()

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.
void Wait()

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).




reference\service.txt · Last modified: 2006/05/27 23:14 by
olivier