The events API provides components with a way to signal other components that a certain event has occurred. For instance a WWW proxy might issue an event when the user makes a request or a response is received. A virus scanner might signal an event when some malware has been detected. Other components can register themselves as event sinks and be notified when those events have occurred.
Event generators are called event sources and their general object structure is as follows:
Before signalling an event you need to set up an event source and its associated events with calls to EventRegisterSourceClass, EventRegisterEventSource and EventRegisterEvent amongst others. Once your source and events are set up, you can signal an event by calling EventProcessEvent passing in an EventContextHandle that describes the event you wish to send.
The fields in the EventContextHandle that you need to set are as follows:
After setting up the event context, you can call EventProcessEvent
In order to process events you need to register an event sink. This can be a full sink or a minisink.
A full sink requires you to register the sink and then manage it via the events API. You can attach it to event, detach, receive notifications of new events in the system and much more. The WinGate Policy Engine component is one such sink component. It dynamically attaches and detaches event sinks when users drop event sources into the various policies.
A minisink on the other hand is registered by the component and then the events system manages displaying and hooking the minisink to compatible events. You just need to supply a few functions via the EventMiniSinkEngineInterface and EventMiniSinkGUIInterface and the framework does the rest. There are of course limitations to minisinks and they are described more in the Minisinks section.
Once the sink is registered then when the event is triggered the framework will call your handler function (EventSinkEvent or EventMiniSinkEvaluate depending on the type of sink)
Event processing is a serialised operation. When an event occurs, the event handlers for that event are processed one after the other with each handler able to cancel event handling when they process the event. |