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