IRuntimeErrorEvent Interface Reference

Notification when an error happens during the virtual machine execution. More...

Inheritance diagram for IRuntimeErrorEvent:

Public Attributes
readonly attribute boolean	fatal
	Whether the error is fatal or not.
readonly attribute wstring	id
	Error identifier.
readonly attribute wstring	message
	Optional error message.
Public Attributes inherited from IEvent
readonly attribute VBoxEventType	type
	Event type.
readonly attribute IEventSource	source
	Source of this event.
readonly attribute boolean	waitable
	If we can wait for this event being processed.

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

Detailed Description

Notification when an error happens during the virtual machine execution.

There are three kinds of runtime errors:

• fatal
• non-fatal with retry
• non-fatal warnings

Fatal errors are indicated by the fatal parameter set to true. In case of fatal errors, the virtual machine execution is always paused before calling this notification, and the notification handler is supposed either to immediately save the virtual machine state using IMachine::saveState or power it off using IConsole::powerDown. Resuming the execution can lead to unpredictable results.

Non-fatal errors and warnings are indicated by the fatal parameter set to false. If the virtual machine is in the Paused state by the time the error notification is received, it means that the user can try to resume the machine execution after attempting to solve the problem that caused the error. In this case, the notification handler is supposed to show an appropriate message to the user (depending on the value of the id parameter) that offers several actions such as Retry, Save or Power Off. If the user wants to retry, the notification handler should continue the machine execution using the IConsole::resume call. If the machine execution is not Paused during this notification, then it means this notification is a warning (for example, about a fatal condition that can happen very soon); no immediate action is required from the user, the machine continues its normal execution.

Note that in either case the notification handler must not perform any action directly on a thread where this notification is called. Everything it is allowed to do is to post a message to another thread that will then talk to the user and take the corresponding action.

Currently, the following error identifiers are known:

• "HostMemoryLow"
• "HostAudioNotResponding"
• "VDIStorageFull"
• "3DSupportIncompatibleAdditions"

Interface ID:

{883DD18B-0721-4CDE-867C-1A82ABAF914C}

Member Data Documentation

fatal

readonly attribute boolean IRuntimeErrorEvent::fatal

Whether the error is fatal or not.

id

readonly attribute wstring IRuntimeErrorEvent::id

Error identifier.

message

readonly attribute wstring IRuntimeErrorEvent::message

Optional error message.