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