Public Member Functions

IEventSource Interface Reference

Event source. More...

List of all members.

Public Member Functions

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

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:
subordinates Subordinate event source this one aggregates.
result Event source aggregating passed sources.
void IEventSource::registerListener ( in IEventListener  listener,
in VBoxEventType[]  interesting,
in boolean  active 
)

Register an event listener.

Parameters:
listener Listener to register.
interesting Event types listener is interested in. One can use wildcards like - VBoxEventType_Any to specify wildcards, matching more than one event.
active Which 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:
listener Listener to unregister.
void IEventSource::fireEvent ( in IEvent  event,
in long  timeout,
[retval] out boolean  result 
)

Fire an event for this source.

Parameters:
event Event to deliver.
timeout Maximum time to wait for event processing (if event is waitable), in ms; 0 = no wait, -1 = indefinite wait.
result true 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:
listener Which listener to get data for.
timeout Maximum time to wait for events, in ms; 0 = no wait, -1 = indefinite wait.
event Event 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:
listener Which listener processed event.
event Which event.