VirtualBox Main API
Public Member Functions | List of all members
IEventSource Interface Reference

Event source. More...

Inheritance diagram for IEventSource:

Public Member Functions

void createListener ([retval] out IEventListener listener)
 Creates a new listener object, useful for passive mode. More...
 
void createAggregator (in IEventSource[] subordinates, [retval] out IEventSource result)
 Creates an aggregator event source, collecting events from multiple sources. More...
 
void registerListener (in IEventListener listener, in VBoxEventType[] interesting, in boolean active)
 Register an event listener. More...
 
void unregisterListener (in IEventListener listener)
 Unregister an event listener. More...
 
void fireEvent (in IEvent event, in long timeout, [retval] out boolean result)
 Fire an event for this source. More...
 
void getEvent (in IEventListener listener, in long timeout, [retval] out IEvent event)
 Get events from this peer's event queue (for passive mode). More...
 
void eventProcessed (in IEventListener listener, in IEvent event)
 Must be called for waitable events after a particular listener finished its event processing. More...
 

Detailed Description

Event source.

Generally, any object which could generate events can be an event source, or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S), an event source can work with listeners in either active or passive mode. In active mode it is up to the IEventSource implementation to call IEventListener::handleEvent, in passive mode the event source keeps track of pending events for each listener and returns available events on demand.

See IEvent for an introduction to VirtualBox event handling.

Interface ID:
{9B6E1AEE-35F3-4F4D-B5BB-ED0ECEFD8538}

Member Function Documentation

void IEventSource::createListener ( [retval] out IEventListener  listener)

Creates a new listener object, useful for passive mode.

void IEventSource::createAggregator ( in IEventSource[]  subordinates,
[retval] out IEventSource  result 
)

Creates an aggregator event source, collecting events from multiple sources.

This way a single listener can listen for events coming from multiple sources, using a single blocking getEvent on the returned aggregator.

Parameters
subordinatesSubordinate event source this one aggregates.
resultEvent source aggregating passed sources.
void IEventSource::registerListener ( in IEventListener  listener,
in VBoxEventType[]  interesting,
in boolean  active 
)

Register an event listener.

Parameters
listenerListener to register.
interestingEvent types listener is interested in. One can use wildcards like - VBoxEventType_Any to specify wildcards, matching more than one event.
activeWhich mode this listener is operating in. In active mode, IEventListener::handleEvent is called directly. In passive mode, an internal event queue is created for this this IEventListener. For each event coming in, it is added to queues for all interested registered passive listeners. It is then up to the external code to call the listener's IEventListener::handleEvent method. When done with an event, the external code must call eventProcessed.
Note
To avoid system overload, the VirtualBox server process checks if passive event listeners call IEventSource::getEvent frequently enough. In the current implementation, if more than 500 pending events are detected for a passive event listener, it is forcefully unregistered by the system, and further getEvent calls will return VBOX_E_OBJECT_NOT_FOUND.
void IEventSource::unregisterListener ( in IEventListener  listener)

Unregister an event listener.

If listener is passive, and some waitable events are still in queue they are marked as processed automatically.

Parameters
listenerListener to unregister.
void IEventSource::fireEvent ( in IEvent  event,
in long  timeout,
[retval] out boolean  result 
)

Fire an event for this source.

Parameters
eventEvent to deliver.
timeoutMaximum time to wait for event processing (if event is waitable), in ms; 0 = no wait, -1 = indefinite wait.
resulttrue if an event was delivered to all targets, or is non-waitable.
void IEventSource::getEvent ( in IEventListener  listener,
in long  timeout,
[retval] out IEvent  event 
)

Get events from this peer's event queue (for passive mode).

Calling this method regularly is required for passive event listeners to avoid system overload; see IEventSource::registerListener for details.

Parameters
listenerWhich listener to get data for.
timeoutMaximum time to wait for events, in ms; 0 = no wait, -1 = indefinite wait.
eventEvent retrieved, or null if none available.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Listener is not registered, or autounregistered.
void IEventSource::eventProcessed ( in IEventListener  listener,
in IEvent  event 
)

Must be called for waitable events after a particular listener finished its event processing.

When all listeners of a particular event have called this method, the system will then call IEvent::setProcessed.

Parameters
listenerWhich listener processed event.
eventWhich event.