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.
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

## ◆ createListener()

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

Creates a new listener object, useful for passive mode.

## ◆ createAggregator()

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.

## ◆ registerListener()

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`.

## ◆ unregisterListener()

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.

## ◆ fireEvent()

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.

## ◆ getEvent()

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.

## ◆ eventProcessed()

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.