IConsoleCallback Interface Reference

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 octetPtr shape)
 Notification when the guest mouse pointer shape has changed.
void onMouseCapabilityChange (in boolean supportsAbsolute, 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 onDVDDriveChange ()
 Notification when a property of the virtual DVD drive changes.
void onFloppyDriveChange ()
 Notification when a property of the virtual floppy drive 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 onVRDPServerChange ()
 Notification when a property 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.


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 octetPtr  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 Address of the shape buffer.
The buffer contains 1 bpp (bits per pixel) AND mask followed by 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.

AND mask presents 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 1 bpp bitmap with byte aligned scanlines. Size of AND mask, therefore, is cbAnd = (width + 7) / 8 * height. The padding bits at the end of any scanline are undefined.

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

Note:
If 'shape' is equal to 0, only pointer visibility is being changed.
Warning:
This method is non-scriptable. In particluar, this also means that an attempt to call it from a process other than the process that has created and owns the object will most likely fail or crash your application.

void IConsoleCallback::onMouseCapabilityChange ( in boolean  supportsAbsolute,
in boolean  needsHostCursor 
)

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

The new capabilities are passed.

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.

void IConsoleCallback::onStateChange ( in MachineState  state  ) 

Notification when the execution state of the machine has changed.

The new state will be given.

void IConsoleCallback::onAdditionsStateChange (  ) 

Notification when a Guest Additions property changes.

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

void IConsoleCallback::onDVDDriveChange (  ) 

Notification when a property of the virtual DVD drive changes.

Interested callees should use IDVDDrive methods to find out what has changed.

void IConsoleCallback::onFloppyDriveChange (  ) 

Notification when a property of the virtual floppy drive changes.

Interested callees should use IFloppyDrive methods 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.

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.

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.

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.

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.

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 perameter 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.

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 Sope of the notification.

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 probem 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 identificators are known:

  • "HostMemoryLow"
  • "HostAudioNotResponding"
  • "VDIStorageFull"
Parameters:
fatal Whether the error is fatal or not
id Error identificator
message Optional error message
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.
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.
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 returnS_OK from all but one of them that actually manages console window activation.


Generated on Fri Nov 21 21:38:41 2008 for VirtualBox Main API by  doxygen 1.5.5