Class RDbNotifier

RDbNotifier

Support

Supported from 5.0

Description

Provides notification of database changes to clients.

This is useful for shared databases.

Defined in RDbNotifier:
Cancel(), Close(), Connect(), EClose, ECommit, ERecover, ERollback, EUnlock, NotifyChange(), NotifyUnlock(), Open(), ResourceCheck(), ResourceCount(), ResourceMark(), SetHeapFailure(), TEvent, Version()

TInt Open(RDbDatabase& aDatabase);

Description

Opens a DBMS change notifier on a database.

Note that a notifier cannot be opened on a client side database.

Parameters

RDbDatabase& aDatabase The database to be observed.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Close();

Description

Closes a DBMS change notifier. Any outstanding notification request is automatically cancelled.

Note that this function can be called on a DBMS change notifier that has already been closed.

void NotifyUnlock(TRequestStatus& aStatus);

Description

Makes an asynchronous request for notification of a database event. All events, including the release of all read locks, are reported.

When a database event occurs, the request completes and the TRequestStatus objectcontains one of the enumerators defined by the TEvent enumeration member.

Alternatively, if an outstanding request is cancelled by a call to the Cancel() member function of this class, then the request completes with KErrCancel.

Only one notification request can be outstanding on this notifier at any one time.

Note that if further database events occur while a client is handling a request completion, the notifier records the most significant database event and this is signalled as soon as the client issues the next NotifyUnlock() or NotifyChange() request.

Parameters

TRequestStatus& aStatus The request status object. If the request is cancelled, this is set to KErrCancel. If the request completes normally, this is set to one of the enumerator values defined by the TEvent enumeration member.

void NotifyChange(TRequestStatus& aStatus);

Description

Makes an asynchronous request for notification of changes to the database.

All events which indicate a change to the database are reported; in practice, this means all database events except RDbNotifier::EUnlock.

When a change event occurs, the request completes and the TRequestStatus object contains one of the appropriate enumerators defined by the TEvent enumeration member.

Alternatively, if an outstanding request is cancelled by a call to the Cancel() member function of this class, then the request completes with KErrCancel.

Only one notification request can be outstanding on this notifier at any one time.

Note that if further database events occur while a client is handling a request completion, the notifier records the most significant database event and this is signalled as soon as the client issues the next NotifyUnlock() or NotifyChange() request.

Parameters

TRequestStatus& aStatus The request status object. If the request is cancelled, this is set to KErrCancel. If the request completes normally, this is set to one of the enumerator values defined by the TEvent enumeration member.

void Cancel();

Description

Cancels any outstanding notification request to this DBMS notifier.

The outstanding request completes with a KErrCancel.

TEvent

Description

Defines the events which may be reported by a DBMS change notifier through this RDbNotifier object.

Each enumerator corresponds to a distinct event type.

The changes are reported through a TRequestStatus object when an outstanding notification request completes.

Notes

If further database events occur while a client is handling the completion of a previous event, the notifier remembers the most significant event. The order of importance is:

ERecover > ERollback > ECommit

where the symbol > means "is more important than"

EClose The database has been closed. EUnlock All read locks have been removed. ECommit A transaction has been committed. ERollback A transaction has been rolled back ERecover The database has been recovered

TInt Connect();

Description

Makes a connection with the DBMS server. This function causes the server to start, if it is not already running.

This should be the first function called on an RDbs object after it is created.

Once a connection has been established, databases can be opened through the server.

Note that:

• Threads can make any number of simultaneous connections to the DBMS server.

• The session must stay open until all DBMS objects opened through the server have been closed.

• The session is terminated by calling the Close() member function provided by the RSessionBase class.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

static TVersion Version();

Description

Returns the version of the DBMS server.

Return value

TVersion Version information.

void ResourceMark();

Description

Marks the start point for checking the number of DBMS objects allocated in this session.

The function takes the current number of allocated DBMS objects as its benchmark number.

A call to this function is normally followed by a later call to ResourceCheck() which expects that the number of allocated DBMS objects to be the same as this benchmark number.

void ResourceCheck();

Description

Checks that the number of DBMS objects allocated in this session is the same as the benchmark number recorded by an earlier call to ResourceMark().

The function raises a CSession 2 panic if the current number of DBMS objects is not the same as that recorded by an earlier call to ResourceMark().

TInt ResourceCount();

Description

Returns the number of DBMS objects allocated in this session.

Return value

TInt The number of DBMS allocated objects.

void SetHeapFailure(RHeap::TAllocFail aType,TInt aRate);

Description

Simulates a heap allocation failure in the DBMS server's heap.

The function behaves as described by User::__DbgSetAllocFail().

Note that this function has no effect if running with a release build of EUSER.DLL.

Parameters

RHeap::TAllocFail aType An enumeration which indicates how to simulate allocation failure in the DBMS server's heap. TInt aRate The rate of failure. When aType is RHeap::EDeterministic, heap allocation fails every aRate attempts.

See also:

• RHeap::TAllocFail
• User::__DbgSetAllocFail()