org.virtualbox_5_0
Class IEvent

java.lang.Object
  extended by org.virtualbox_5_0.IUnknown
      extended by org.virtualbox_5_0.IEvent
Direct Known Subclasses:
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 class IEvent
extends IUnknown

Abstract parent interface for VirtualBox events. Actual events will typically implement a more specific interface which derives from this (see below).Introduction to VirtualBox eventsGenerally speaking, an event (represented by this interface) signals that something happened, while an event listener (seeIEventListener) 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 (seeIEventSource.registerListener(org.virtualbox_5_0.IEventListener,List,Boolean)). 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 (seeIVetoEvent) 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.Using eventsAny VirtualBox object capable of producing externally visible events provides an eventSource read-only attribute, which is of the typeIEventSource. 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 theIEventListenerinterface must be provided. For active listeners, such an object is typically created by the consumer, while for passive listenersIEventSource.createListener()should be used. Please note that a listener created withIEventSource.createListener()must not be used as an active listener. Once created, the listener must be registered to listen for the desired events (seeIEventSource.registerListener(org.virtualbox_5_0.IEventListener,List,Boolean)), providing an array ofVBoxEventTypeenums. Those elements can either be the individual event IDs or wildcards matching multiple event IDs. After registration, the callback'sIEventListener.handleEvent(org.virtualbox_5_0.IEvent)method is called automatically when the event is triggered, while passive listeners have to callIEventSource.getEvent(org.virtualbox_5_0.IEventListener,Integer)andIEventSource.eventProcessed(org.virtualbox_5_0.IEventListener,org.virtualbox_5_0.IEvent)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 insideIEventListener.handleEvent(org.virtualbox_5_0.IEvent)or the event processing loop is to check thegetType()attribute of the event and then cast to the appropriate specific interface using QueryInterface(). Interface ID: {0CA2ADBA-8F30-401B-A8CD-FE31DBE839C0}


Field Summary
 
Fields inherited from class org.virtualbox_5_0.IUnknown
obj, objMgr, port
 
Constructor Summary
IEvent(java.lang.String wrapped, org.virtualbox_5_0.ObjectRefManager objMgr, org.virtualbox_5_0.jaxws.VboxPortType port)
           
 
Method Summary
 IEventSource getSource()
          Source of this event.
 VBoxEventType getType()
          Event type.
 java.lang.Boolean getWaitable()
          If we can wait for this event being processed.
static IEvent queryInterface(IUnknown obj)
           
 void setProcessed()
          Internal method called by the system when all listeners of a particular event have calledIEventSource.eventProcessed(org.virtualbox_5_0.IEventListener,org.virtualbox_5_0.IEvent).
 java.lang.Boolean waitProcessed(java.lang.Integer timeout)
          Wait until time outs, or this event is processed.
 
Methods inherited from class org.virtualbox_5_0.IUnknown
getObjMgr, getRemoteWSPort, getWrapped, releaseRemote
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IEvent

public IEvent(java.lang.String wrapped,
              org.virtualbox_5_0.ObjectRefManager objMgr,
              org.virtualbox_5_0.jaxws.VboxPortType port)
Method Detail

getType

public VBoxEventType getType()
Event type.

Returns:
org.virtualbox_5_0.VBoxEventType

getSource

public IEventSource getSource()
Source of this event.

Returns:
org.virtualbox_5_0.IEventSource

getWaitable

public java.lang.Boolean getWaitable()
If we can wait for this event being processed. If false,waitProcessed(Integer)returns immediately, andsetProcessed()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.

Returns:
Boolean

queryInterface

public static IEvent queryInterface(IUnknown obj)

setProcessed

public void setProcessed()
Internal method called by the system when all listeners of a particular event have calledIEventSource.eventProcessed(org.virtualbox_5_0.IEventListener,org.virtualbox_5_0.IEvent). This should not be called by client code.


waitProcessed

public java.lang.Boolean waitProcessed(java.lang.Integer timeout)
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.

Parameters:
timeout - Maximum time to wait for event processing, in ms; 0 = no wait, -1 = indefinite wait.
Returns:
If this event was processed before timeout.