Public Member Functions

IConsoleCallback Interface Reference

This interface is used by a client of the Main API that need to be notified of events. More...

List of all members.

Public Member Functions

void onMousePointerShapeChange (in boolean visible, in boolean alpha, in unsigned long xHot, in unsigned long yHot, in unsigned long width, in unsigned long height, in octet[] shape)
 Notification when the guest mouse pointer shape has changed.
void onMouseCapabilityChange (in boolean supportsAbsolute, in boolean supportsRelative, in boolean needsHostCursor)
 Notification when the mouse capabilities reported by the guest have changed.
void onKeyboardLedsChange (in boolean numLock, in boolean capsLock, in boolean scrollLock)
 Notification when the guest OS executes the KBD_CMD_SET_LEDS command to alter the state of the keyboard LEDs.
void onStateChange (in MachineState state)
 Notification when the execution state of the machine has changed.
void onAdditionsStateChange ()
 Notification when a Guest Additions property changes.
void onNetworkAdapterChange (in INetworkAdapter networkAdapter)
 Notification when a property of one of the virtual network adapters changes.
void onSerialPortChange (in ISerialPort serialPort)
 Notification when a property of one of the virtual serial ports changes.
void onParallelPortChange (in IParallelPort parallelPort)
 Notification when a property of one of the virtual parallel ports changes.
void onStorageControllerChange ()
 Notification when a property of one of the virtual storage controllers changes.
void onMediumChange (in IMediumAttachment mediumAttachment)
 Notification when a medium attachment changes.
void onCPUChange (in unsigned long cpu, in boolean add)
 Notification when a CPU changes.
void onVRDPServerChange ()
 Notification when a property of the VRDP server changes.
void onRemoteDisplayInfoChange ()
 Notification when the status of the VRDP server changes.
void onUSBControllerChange ()
 Notification when a property of the virtual USB controller changes.
void onUSBDeviceStateChange (in IUSBDevice device, in boolean attached, in IVirtualBoxErrorInfo error)
 Notification when a USB device is attached to or detached from the virtual USB controller.
void onSharedFolderChange (in Scope scope)
 Notification when a shared folder is added or removed.
void onRuntimeError (in boolean fatal, in wstring id, in wstring message)
 Notification when an error happens during the virtual machine execution.
void onCanShowWindow ([retval] out boolean canShow)
 Notification when a call to IMachine::canShowConsoleWindow is made by a front-end to check if a subsequent call to IMachine::showConsoleWindow can succeed.
void onShowWindow ([retval] out unsigned long long winId)
 Notification when a call to IMachine::showConsoleWindow requests the console window to be activated and brought to foreground on the desktop of the host PC.

Detailed Description

This interface is used by a client of the Main API that need to be notified of events.

For example, a graphical user interface can use this to learn about machine state changes so they can update the list of virtual machines without having to rely on polling.

Whenever relevant events occur in VirtualBox, the callbacks in objects of this interface are called. In order for this to be useful, a client needs to create its own subclass that implements this interface in which the methods for the relevant callbacks are overridden. An instance of this subclass interface can then be passed to IConsole::registerCallback.

Interface ID:
{60703F8D-81E4-4B45-A147-DCFD07692B19}

Member Function Documentation

void IConsoleCallback::onMousePointerShapeChange ( in boolean  visible,
in boolean  alpha,
in unsigned long  xHot,
in unsigned long  yHot,
in unsigned long  width,
in unsigned long  height,
in octet[]  shape 
)

Notification when the guest mouse pointer shape has changed.

The new shape data is given.

Parameters:
visible Flag whether the pointer is visible.
alpha Flag whether the pointer has an alpha channel.
xHot The pointer hot spot x coordinate.
yHot The pointer hot spot y coordinate.
width Width of the pointer shape in pixels.
height Height of the pointer shape in pixels.
shape Shape buffer arrays.

The shape buffer contains a 1-bpp (bits per pixel) AND mask followed by a 32-bpp XOR (color) mask.

For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb). For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.

An AND mask is used for pointers with alpha channel, so if the callback does not support alpha, the pointer could be displayed as a normal color pointer.

The AND mask is a 1-bpp bitmap with byte aligned scanlines. The size of the AND mask therefore is cbAnd = (width + 7) / 8 * height. The padding bits at the end of each scanline are undefined.

The XOR mask follows the AND mask on the next 4-byte aligned offset: uint8_t *pXor = pAnd + (cbAnd + 3) & ~3. Bytes in the gap between the AND and the XOR mask are undefined. The XOR mask scanlines have no gap between them and the size of the XOR mask is: cXor = width * 4 * height.

Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
Note:
If shape is 0, only the pointer visibility is changed.
void IConsoleCallback::onMouseCapabilityChange ( in boolean  supportsAbsolute,
in boolean  supportsRelative,
in boolean  needsHostCursor 
)

Notification when the mouse capabilities reported by the guest have changed.

The new capabilities are passed.

Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onKeyboardLedsChange ( in boolean  numLock,
in boolean  capsLock,
in boolean  scrollLock 
)

Notification when the guest OS executes the KBD_CMD_SET_LEDS command to alter the state of the keyboard LEDs.

Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onStateChange ( in MachineState  state  ) 

Notification when the execution state of the machine has changed.

The new state will be given.

Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onAdditionsStateChange (  ) 

Notification when a Guest Additions property changes.

Interested callees should query IGuest attributes to find out what has changed.

void IConsoleCallback::onNetworkAdapterChange ( in INetworkAdapter  networkAdapter  ) 

Notification when a property of one of the virtual network adapters changes.

Interested callees should use INetworkAdapter methods and attributes to find out what has changed.

Parameters:
networkAdapter Network adapter that is subject to change.
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onSerialPortChange ( in ISerialPort  serialPort  ) 

Notification when a property of one of the virtual serial ports changes.

Interested callees should use ISerialPort methods and attributes to find out what has changed.

Parameters:
serialPort Serial port that is subject to change.
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onParallelPortChange ( in IParallelPort  parallelPort  ) 

Notification when a property of one of the virtual parallel ports changes.

Interested callees should use ISerialPort methods and attributes to find out what has changed.

Parameters:
parallelPort Parallel port that is subject to change.
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onStorageControllerChange (  ) 

Notification when a property of one of the virtual storage controllers changes.

Interested callees should query the corresponding collections to find out what has changed.

Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onMediumChange ( in IMediumAttachment  mediumAttachment  ) 

Notification when a medium attachment changes.

Parameters:
mediumAttachment Medium attachment that is subject to change.
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onCPUChange ( in unsigned long  cpu,
in boolean  add 
)

Notification when a CPU changes.

Parameters:
cpu The CPU which changed
add Flag whether the CPU was added or removed
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onVRDPServerChange (  ) 

Notification when a property of the VRDP server changes.

Interested callees should use IVRDPServer methods and attributes to find out what has changed.

Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onRemoteDisplayInfoChange (  ) 

Notification when the status of the VRDP server changes.

Interested callees should use IRemoteDisplayInfo attributes to find out what is the current status.

Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onUSBControllerChange (  ) 

Notification when a property of the virtual USB controller changes.

Interested callees should use IUSBController methods and attributes to find out what has changed.

Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onUSBDeviceStateChange ( in IUSBDevice  device,
in boolean  attached,
in IVirtualBoxErrorInfo  error 
)

Notification when a USB device is attached to or detached from the virtual USB controller.

This notification is sent as a result of the indirect request to attach the device because it matches one of the machine USB filters, or as a result of the direct request issued by IConsole::attachUSBDevice or IConsole::detachUSBDevice.

This notification is sent in case of both a succeeded and a failed request completion. When the request succeeds, the error parameter is null, and the given device has been already added to (when attached is true) or removed from (when attached is false) the collection represented by IConsole::USBDevices. On failure, the collection doesn't change and the error parameter represents the error message describing the failure.

Parameters:
device Device that is subject to state change.
attached true if the device was attached and false otherwise.
error null on success or an error message object on failure.
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onSharedFolderChange ( in Scope  scope  ) 

Notification when a shared folder is added or removed.

The scope argument defines one of three scopes: global shared folders (Global), permanent shared folders of the machine (Machine) or transient shared folders of the machine (Session). Interested callees should use query the corresponding collections to find out what has changed.

Parameters:
scope Scope of the notification.
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
void IConsoleCallback::onRuntimeError ( in boolean  fatal,
in wstring  id,
in wstring  message 
)

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 IConsole::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"
Parameters:
fatal Whether the error is fatal or not
id Error identifier
message Optional error message
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
Note:
This notification is not designed to be implemented by more than one callback at a time. If you have multiple IConsoleCallback instances registered on the given IConsole object, make sure you simply do nothing but return S_OK from all but one of them that does actual user notification and performs necessary actions.
void IConsoleCallback::onCanShowWindow ( [retval] out boolean  canShow  ) 

Notification when a call to IMachine::canShowConsoleWindow is made by a front-end to check if a subsequent call to IMachine::showConsoleWindow can succeed.

The callee should give an answer appropriate to the current machine state in the canShow argument. This answer must remain valid at least until the next machine state change.

Parameters:
canShow true if the console window can be shown and false otherwise.
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
Note:
This notification is not designed to be implemented by more than one callback at a time. If you have multiple IConsoleCallback instances registered on the given IConsole object, make sure you simply do nothing but return true and S_OK from all but one of them that actually manages console window activation.
void IConsoleCallback::onShowWindow ( [retval] out unsigned long long  winId  ) 

Notification when a call to IMachine::showConsoleWindow requests the console window to be activated and brought to foreground on the desktop of the host PC.

This notification should cause the VM console process to perform the requested action as described above. If it is impossible to do it at a time of this notification, this method should return a failure.

Note that many modern window managers on many platforms implement some sort of focus stealing prevention logic, so that it may be impossible to activate a window without the help of the currently active application (which is supposedly an initiator of this notification). In this case, this method must return a non-zero identifier that represents the top-level window of the VM console process. The caller, if it represents a currently active process, is responsible to use this identifier (in a platform-dependent manner) to perform actual window activation.

This method must set winId to zero if it has performed all actions necessary to complete the request and the console window is now active and in foreground, to indicate that no further action is required on the caller's side.

Parameters:
winId Platform-dependent identifier of the top-level VM console window, or zero if this method has performed all actions necessary to implement the show window semantics for the given platform and/or this VirtualBox front-end.
Expected result codes:
VBOX_E_DONT_CALL_AGAIN Do not call again, this method is a NOP.
Note:
This notification is not designed to be implemented by more than one callback at a time. If you have multiple IConsoleCallback instances registered on the given IConsole object, make sure you simply do nothing but return S_OK from all but one of them that actually manages console window activation.