Using Notifications with EDB (Windows CE 5.0)

Article
09/14/2012

When a change occurs to a volume or database, EDB sends notifications to client applications that have requested notification. A client registers for notifications by passing a CENOTIFYREQUEST structure in the call to the CeOpenDatabaseInSession function. A client unregisters by closing the database handle. This process is the same as in CEDB, although EDB supports new notification types and does not support some of the CEDB notification types.

EDB Notification Types

The following table shows the notification types supported by EDB:

Notification type	Description
DB_NOTIFY_RECORD_CREATED	Indicates that a new record has been created.
DB_NOTIFY_RECORD_CHANGED	Indicates that a record has been changed.
DB_NOTIFY_RECORD_DELETED	Indicates that a record has been deleted.
DB_NOTIFY_VOLUME_CHANGED	Occurs only within a transaction, and indicates a change in the volume.

CENOTIFICATION Structure

Whenever a change occurs to a database or volume, EDB posts an allocated CENOTIFICATION structure to the client's window handle (obtained from the CENOTIFYREQUEST structure). The information in the CENOTIFICATION structure depends on the notification type. The following table shows the value for each member of the CENOTIFICATION structure for each notification type:

Notification type	GUID value	oidParent value	OID value
RECORD_CREATED	The GUID of the volume that contains the record	OID of the database that contains the record	OID of the record that has been created
RECORD_CHANGED	The GUID of the volume that contains the record	OID of the database that contains the record	OID of the record that has been changed
RECORD_DELETED	The GUID of the volume that contains the record	OID of the database that contains the record	OID of the record that has been deleted
VOLUME_CHANGED	The GUID of the volume that has been changed	NULL	NULL

The notification message posted is WM_DBNOTIFICATION, and the pointer to the CENOTIFICATION structure is supplied in the lParam parameter. Your application must call the CeFreeNotification function to free the memory associated with the CENOTIFICATION structure.

DB_NOTIFY_VOLUME_CHANGED Notification Type

There are two scenarios where EDB sends the DB_NOTIFY_VOLUME_CHANGED notification:

The queue changes threshold is exceeded.

When a transaction commits, EDB dispatches the relevant changes to the appropriate clients. If there are clients registered to receive notifications, EDB queues the change information during long-running transactions. If the number of queued changes exceeds a threshold, EDB stops logging individual changes; once the transaction commits, EDB send a single DB_NOTIFY_VOLUME_CHANGED notification to each client. This prevents flooding of the clients' message queues.

Note Notifications are sent only if the transaction successfully commits. If the transaction is reverted, no notification is sent.
A client registers for notifications after a transaction has begun.

If a client registers for notifications after an explicit transaction has already started, the client receives a DB_NOTIFY_VOLUME_CHANGED notification after any transaction on the volume commits. For example, if User1 has started a transaction and is making changes to a database, and then User2 opens the same database and registers for notifications, User2 will receive a DB_NOTIFY_VOLUME_CHANGED notification once User1 commits.

Because all operations occur within a transaction (whether explicit or implicit), a DB_NOTIFY_VOLUME_CHANGED notification might be sent even if no explicit transaction occurred. For example, if User2 registers for notifications while User1 is performing an Insert operation, User2 will receive a DB_NOTIFY_VOLUME_CHANGED notification once the Insert operation completes.

Note EDB sends a DB_NOTIFY_VOLUME_CHANGED notification to all clients registered to receive notifications, even if the database that changed is not the database on which the client is registered.

Setting the Change Queue Threshold

You can set the maximum number of changes to be queued during a transaction in two ways:

Setting the default value

You can set a default value to be used for all sessions and opened databases by passing a value in the CEVOLUMEOPTIONS structure when you mount a volume. For more information, see Configurable EDB Volume Options.
Setting a per-session value

You can set the value on a per-session basis by calling the CeSetSessionOption function.

Notification Compatibility Differences

EDB supports two notification styles: the CEDB method of using messages, and a new notification style in which notifications are received as a structure. The following table lists the various notification types and the database engine that supports each:

Notification type	Supported by EDB	Supported by CDEB
DB_NOTIFY_VOLUME_CHANGED	Yes	No
DB_NOTIFY_RECORD_CREATED	Yes	Yes
DB_NOTIFY_RECORD_CHANGED	Yes	Yes
DB_NOTIFY_RECORD_DELETED	Yes	Yes
DB_CEOID_DIRECTORY_DELETED	No	Yes
DB_CEOID_FILE_DELTETED	No	Yes
DB_CEOID_DATABASE_DELETED	No	Yes

Handling Notifications at the Client

When handling notifications at the client, you should be aware of these two potential issues:

Changes and notification order

Clients should not rely on the order in which changes are made within a transaction and the order in which notifications are received. There is no certainty that notifications will be received in the same order in which the changes were made.
OID value re-use

Once a client is registered, the client receives OID values in the notifications. The value of the OID depends on the notification type. However, you must be careful when using the OIDs that a client receives in a notification. For example, suppose Client1 deletes a record. Client2 will receive a notification about the delete; this notification will include the OID for the deleted record. However, EDB may reuse that OID for a new record. Therefore, Client2 can safely use the OID to clean up its own cached data or user interface, but should not use it for subsequent calls to EDB.