EPOC   SDK Home Glossary Indexes Previous Next Up

RDbNotifier class


Contents


RDbNotifier class — DBMS change notifier

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Derivation

RDbNotifier

DBMS change notifier

Defined in

d32dbms.h

Link against

edbms.lib

Description

Databases can provide notification of changes to clients; this is particularly useful for shared databases. The notification service is provided by objects of the RDbNotifier class.


Opening and closing the change notifier


Open() — Open a notifier on a database

TInt Open(RDbDatabase& aDatabase);

Description

Use this function to open a DBMS change notifier on a database.

Arguments

RDbDatabase& aDatabase

A reference to the database to be observed.

Return value

TInt

KErrNone if successful or one of the system error codes; see system error codes.

Notes

A notifier cannot be opened on a client side database.


Close() — Close the notifier

void Close();

Description

Use this function to close a DBMS change notifier. Any outstanding notification request is automatically cancelled.

Notes

Close() can be called on a DBMS change notifier that has already been closed.


Requesting database events


NotifyUnlock() — Request notification of a database event

void NotifyUnlock(TRequestStatus& aStatus);

Description

Use this function to make 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 TRequestStatus contains 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.

Arguments

TRequestStatus& aStatus

A reference to 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.

Notes

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.


NotifyChange() — Request notification of changes to the database

void NotifyChange(TRequestStatus& aStatus);

Description

Use this function to make 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 TRequestStatus 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.

Arguments

TRequestStatus& aStatus

A reference to 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.

Notes

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.


Cancelling an outstanding request


Cancel() — Cancel outstanding notification request

void Cancel();

Description

Use this function to cancel any outstanding notification request to this DBMS notifier.

The outstanding request completes with a KErrCancel.


Enumerations


TEvent enum — Events reported by the DBMS change notifier

Description

This enumeration defines the events which may be reported by a DBMS change notifier through this RDbNotifier.

Each enumerator corresponds to a distinct event type.

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

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.

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.

EPOC       SDK Home Glossary Indexes Previous Next Up