Working with event notifications

UltraLite now supports events and notifications. A notification is a message that is sent when an event occurs, also providing additional parameter information. UltraLite has system events and events can also be user-defined.

Event notifications allow you to provide coordination and signaling between connections or applications connected to the same database. Notifications are managed in queues: either a connection's default queue or, optionally, queues that are explicitly created and named. When an event occurs, notifications are sent to registered queues (or connections).

Each connection manages its own notification queues. Named queues can be created for any connection.

Using predefined system events this feature also provides "triggers" for changes to data, such as when a change is made to a table, for example, or signaling when a synchronization has occurred. Predefined events include:

Commit
SyncComplete
TableModified

User events may also be defined and triggered by an application.

APIs for events and notifications are provided in each supported language. Additionally, a SQL function is provided to access the API functionality.

Events

Event	Occurrence
Commit	Signaled upon completion of a commit.
SyncComplete	Signaled upon completion of a sync.
TableModified	Triggered when rows in a table are inserted, updated, or deleted. One event is signaled per request, no matter how many rows were affected by the request when registering for the event. The object_name parameter specifies the table to monitor. A value of "" means all tables in the database. The table_name* notification parameter is the name of the modified table.

Event

Occurrence

Commit

Signaled upon completion of a commit.

SyncComplete

Signaled upon completion of a sync.

TableModified

Triggered when rows in a table are inserted, updated, or deleted. One event is signaled per request, no matter how many rows were affected by the request when registering for the event.

The object_name parameter specifies the table to monitor. A value of "*" means all tables in the database.

The table_name notification parameter is the name of the modified table.

note_info.event_name = "SyncComplete";
note_info.event_name_len = 12;
note_info.parms_type = ul_ev_note_info::P_NONE;

note_info.event_name = "TableModified";
note_info.event_name_len = 13;
note_info.parms_type = ul_ev_note_info::P_TABLE_NAME;
note_info.parms = table->name->data;
note_info.parms_len = table->name->len;

Working with queues

Queues can be created and destroyed.

CreateNotificationQueue creates an event notification queue for the current connection. Queue names are scoped per-connection, so different connections can create queues with the same name. When an event notification is sent, all queues in the database with a matching name receive a separate instance of the notification. Names are case insensitive. A default queue is created on demand for each connection if no queue is specified. This call fails with an error if the name already exists for the connection or isn't valid.

DestroyNotificationQueue destroys the given event notification queue. A warning is signaled if unread notifications remain in the queue. Unread notifications are discarded. A connection's default event queue, if created, is destroyed when the connection is closed.

Working with events

DeclareEvent declares an event which can then be registered for and triggered. UltraLite predefines some system events triggered by operations on the database or the environment. The event name must be unique and names are case insensitive. Returns true if the event was declared successfully, false if the name is already used or invalid.

RegisterForEvent registers a queue to receive notifications of an event. If no queue name is supplied, the default connection queue is implied, and created if required. Certain system events allow specification of an object name to which the event applies. For example, the TableModified event can specify the table name. Unlike SendNotification, only the specific queue registered will receive notifications of the event; other queues with the same name on different connections will not (unless they are also explicitly registered). Returns true if the registration succeeded, false if the queue or event does not exist.

TriggerEvent triggers an event and sends a notification to all registered queues. Returns the number of event notifications sent. Parameters may be supplied as name=value; pairs.

Working with notifications

SendNotification sends a notification to all queues in the database matching the given name (including any such queue on the current connection). This call does not block. Use the special queue name "*" to send to all queues. Returns the number of notifications sent (the number of matching queues). Parameters may be supplied as name=value; pairs.

GetNotification reads an event notification. This call blocks until a notification is received or until the given wait period expires. To cancel a wait, send another notification to the given queue or use CancelGetNotification. After reading a notification, use ReadNotificationParameter to retrieve additional parameters. Returns true if an event was read, false if the wait period expired or was canceled.

GetNotificationParameter gets a named parameter for the event notification just read by GetNotification. Only the parameters from the most-recently read notification on the given queue are available. Returns true if the parameter was found, false if the parameter was not found.

CancelGetNotification cancels any pending GetNotification calls on all queues matching the given name. Returns the number of affected queues (not necessarily the number of blocked reads).

Other considerations

Discuss this page in DocCommentXchange.