Using Notifications with EDB

  • Article

Other versions of this page are also available for the following:

Windows Mobile Not SupportedWindows Embedded CE Supported

8/28/2008

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 (EDB) 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_CHANGED

Indicates that a record has been changed.

DB_NOTIFY_RECORD_CREATED

Indicates that a new record has been created.

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 to a database or volume occurs, EDB posts an allocated CENOTIFICATION structure to the client's window handle obtained from CENOTIFYREQUEST. The information in CENOTIFICATION depends on the notification type. The following table shows the value for the guid, oidParent, and oid members of CENOTIFICATION for each notification type:

Notification type guid value oidParent value oid value

RECORD_CREATED

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

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

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

GUID of the volume that has been changed

NULL

NULL

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

DB_NOTIFY_VOLUME_CHANGED Notification Type

EDB sends the DB_NOTIFY_VOLUME_CHANGED notification in the following situations:

  • The queue changes threshold is exceeded.
    When a transaction is committed, 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 sends 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 is successfully committed. 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 is committed. For example, if User 1 has started a transaction and is making changes to a database, and then User 2 opens the same database and registers for notifications, User 2 receives a DB_NOTIFY_VOLUME_CHANGED notification once User 1 commits the changes.
    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 User 2 registers for notifications while User 1 is performing an insert operation, User 2 receives a DB_NOTIFY_VOLUME_CHANGED notification once the insert operation is completed.

    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 the following ways:

Notification Compatibility Differences

EDB supports the following notification styles:

  • Using messages, as in CEDB.
  • A new notification style in which notifications are received as a structure.

The following table shows the notification types and the database engine that supports each.

Notification type Supported by EDB Supported by CDEB

DB_CEOID_DATABASE_DELETED

No

Yes

DB_CEOID_DIRECTORY_DELETED

No

Yes

DB_CEOID_FILE_DELTETED

No

Yes

DB_NOTIFY_RECORD_CHANGED

Yes

Yes

DB_NOTIFY_RECORD_CREATED

Yes

Yes

DB_NOTIFY_RECORD_DELETED

Yes

Yes

DB_NOTIFY_VOLUME_CHANGED

Yes

No

Handling Notifications at the Client

When handling notifications at the client, there are the following 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, if Client 1 deletes a record. Client 2 receives a notification about the deletion. This notification includes the OID for the deleted record. However, EDB can reuse that OID for a new record. Therefore, Client 2 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.

See Also

Reference

CeOpenDatabaseInSession (EDB)
CeFreeNotification (EDB)
CEVOLUMEOPTIONS (EDB)

Concepts

Configurable EDB Volume Options

Other Resources

EDB Database Support
CENOTIFICATION
CENOTIFYREQUEST