Table of Contents

class EventInterface

The EventInterface class is strictly an interface class. IBPP does not implement this class. To use the Events mechanism, you will have to derive a class from this one and implement its virtual ibppEventHandler() method. IBPP will call that method to notify the events occurences.

Definition

class EventInterface
{
public:
    virtual void ibppEventHandler(Events eventsSet, const std::string& eventName, int count) = 0;
    virtual ~EventInterface() { };
};

Methods

void ibppEventHandler(Events eventsSet, const std::string& eventName, int count)

This is the only method you have to implement in your class derived from EventInterface.

When an event will trigger this method will be called. Upon call, you get a pointer to the Events set (which in turn can get you a pointer to the related Database (through Events::DatabasePtr()). You also get the event name and the count of occurences (since the last time you were notified) of the event.

Indeed, the count might be greater than 1. Why? Because Firebird reports events at transaction commit time. So if you signal an event on INSERT and there are 3 INSERTs, at commit time you will be notified that the event triggered 3 times. Also, there might be multiple commits between your calls to Events::Dispatch.

Notifications

This Dispatch() based synchronous delivery of notifications is the safest method. It is also the only one correct based on the current Firebird C-API which forbids re-issuing a wait for events from the events handler.

The ibppEventHandler() is only called from within your own calls to Events::Dispatch(). This way you have full control and the notifications are called from the context of your thread (the one which calls Events::Disptach()).

You can issue other database operations from within your notification handler. The only downside to this synchronous notification mechanism is that you have to somehow poll the Events::Dispatch() on a regular basis. In a typical windows program you might for instance do so each time a Windows message is dispatched (in your typical WaitForMessage() / DispatchMessage() loop). Just calling Events::Dispatch() from there should be a good starting point. Your notification handler could post a Windows message to transmit the notification to the relevant parts of your application.

Using a timer based mechanism is similar.