====== IBPP::Events =====

The Events object allows easy interactions with the events mechanism offered by Firebird. One Events object represents a set of events, linked to one [[Database]] attachment.

You really should also read the [[EventInterface]] article to grab a complete view on this topic.

===== EventsFactory =====

EventsFactory is used to create and get access to an Events object.

<code>
Events EventsFactory(Database db)
</code>

Events obects have a lifetime strictly limited by the lifetime of the [[database]] connection they depend on. One can manage multiple Events objects at the same time for a single [[database]] connection.
 

===== Methods =====

==== void Add(const std::string& name, EventInterface* catcher) ====

Adds a new event ''name'' to the set. The notifications will be sent through the ''ibppEventHandler()'' method of the [[EventInterface]]* ''catcher'' object.

==== void Drop(const std::string& name) ====

Drops an event from the set.

==== void List(std::vector<std::string>& eventsList) ====

Builds the list of all the events of this set.

==== void Clear() ====

Drops all events from the set. The Events object is indeed empty, just in the same state as after construction by the ''EventsFactory()''.

==== void Dispatch() ====

The notifications will only get delivered upon a call to this method.

This means the host program has to poll this methods from time to time to get the notifications. It is a perfectly safe mean to get the notifications. The ''ibppEventHandler()'' method of your EventInterface derived objects will only be called when you call ''Dispatch()''. This means you have full control on which thread calls your notifications methods. They are always called from the thread which calls ''Dispatch()''. This allows you full flexibility: you can safely call other IBPP methods.

==== Database DatabasePtr() ====

Returns the [[Database]] attached to this Events object.