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

Abstract parent interface for VirtualBox events. More...

Inheritance diagram for IEvent:
IAdditionsStateChangedEvent IBandwidthGroupChangedEvent IClipboardModeChangedEvent ICPUChangedEvent ICPUExecutionCapChangedEvent IDnDModeChangedEvent IEventSourceChangedEvent IExtraDataChangedEvent IGuestKeyboardEvent IGuestMonitorChangedEvent IGuestMultiTouchEvent IGuestSessionEvent IGuestUserStateChangedEvent IHostNameResolutionConfigurationChangeEvent IKeyboardLedsChangedEvent IMachineEvent IMediumChangedEvent IMediumConfigChangedEvent IMediumRegisteredEvent IMouseCapabilityChangedEvent IMousePointerShapeChangedEvent INATNetworkChangedEvent INetworkAdapterChangedEvent IParallelPortChangedEvent IReusableEvent IRuntimeErrorEvent ISerialPortChangedEvent ISharedFolderChangedEvent IShowWindowEvent IStateChangedEvent IStorageControllerChangedEvent IStorageDeviceChangedEvent IUSBControllerChangedEvent IUSBDeviceStateChangedEvent IVBoxSVCAvailabilityChangedEvent IVetoEvent IVideoCaptureChangedEvent IVRDEServerChangedEvent IVRDEServerInfoChangedEvent

Public Member Functions

void setProcessed ()
 Internal method called by the system when all listeners of a particular event have called IEventSource::eventProcessed. More...
void waitProcessed (in long timeout, [retval] out boolean result)
 Wait until time outs, or this event is processed. More...

Public Attributes

readonly attribute VBoxEventType type
 Event type. More...
readonly attribute IEventSource source
 Source of this event. More...
readonly attribute boolean waitable
 If we can wait for this event being processed. More...

Detailed Description

Abstract parent interface for VirtualBox events.

Actual events will typically implement a more specific interface which derives from this (see below).

Introduction to VirtualBox events

Generally speaking, an event (represented by this interface) signals that something happened, while an event listener (see IEventListener) represents an entity that is interested in certain events. In order for this to work with unidirectional protocols (i.e. web services), the concepts of passive and active listener are used.

Event consumers can register themselves as listeners, providing an array of events they are interested in (see IEventSource::registerListener). When an event triggers, the listener is notified about the event. The exact mechanism of the notification depends on whether the listener was registered as an active or passive listener:

  Waitable events are useful in situations where the event generator wants to track
  delivery or a party wants to wait until all listeners have completed the event. A
  typical example would be a vetoable event (see @link ::IVetoEvent IVetoEvent@endlink<b></b>) where a
  listeners might veto a certain action, and thus the event producer has to make
  sure that all listeners have processed the event and not vetoed before taking
  the action.

  A given event may have both passive and active listeners at the same time.

  <b>Using events</b>

  Any VirtualBox object capable of producing externally visible events provides an
  @c eventSource read-only attribute, which is of the type @link ::IEventSource IEventSource@endlink<b></b>.
  This event source object is notified by VirtualBox once something has happened, so
  consumers may register event listeners with this event source. To register a listener,
  an object implementing the @link ::IEventListener IEventListener@endlink<b></b> interface must be provided.
  For active listeners, such an object is typically created by the consumer, while for
  passive listeners @link IEventSource::createListener IEventSource::createListener@endlink<b></b> should be used. Please
  note that a listener created with @link IEventSource::createListener IEventSource::createListener@endlink<b></b> must not be used as an active listener.

  Once created, the listener must be registered to listen for the desired events
  (see @link IEventSource::registerListener IEventSource::registerListener@endlink<b></b>), providing an array of
  @link ::VBoxEventType VBoxEventType@endlink<b></b> enums. Those elements can either be the individual
  event IDs or wildcards matching multiple event IDs.

  After registration, the callback's @link IEventListener::handleEvent IEventListener::handleEvent@endlink<b></b> method is
  called automatically when the event is triggered, while passive listeners have to call
  @link IEventSource::getEvent IEventSource::getEvent@endlink<b></b> and @link IEventSource::eventProcessed IEventSource::eventProcessed@endlink<b></b> in
  an event processing loop.

  The IEvent interface is an abstract parent interface for all such VirtualBox events
  coming in. As a result, the standard use pattern inside @link IEventListener::handleEvent IEventListener::handleEvent@endlink<b></b>
  or the event processing loop is to check the @link #type type@endlink<b></b> attribute of the event and
  then cast to the appropriate specific interface using @c QueryInterface().
Interface ID:

Member Function Documentation

void IEvent::setProcessed ( )

Internal method called by the system when all listeners of a particular event have called IEventSource::eventProcessed.

This should not be called by client code.

void IEvent::waitProcessed ( in long  timeout,
[retval] out boolean  result 

Wait until time outs, or this event is processed.

Event must be waitable for this operation to have described semantics, for non-waitable returns true immediately.

timeoutMaximum time to wait for event processing, in ms; 0 = no wait, -1 = indefinite wait.
resultIf this event was processed before timeout.

Member Data Documentation

readonly attribute VBoxEventType IEvent::type

Event type.

readonly attribute IEventSource IEvent::source

Source of this event.

readonly attribute boolean IEvent::waitable

If we can wait for this event being processed.

If false, waitProcessed returns immediately, and setProcessed doesn't make sense. Non-waitable events are generally better performing, as no additional overhead associated with waitability imposed. Waitable events are needed when one need to be able to wait for particular event processed, for example for vetoable changes, or if event refers to some resource which need to be kept immutable until all consumers confirmed events.