VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IConsole Interface Reference

The IConsole interface represents an interface to control virtual machine execution. More...

Inheritance diagram for IConsole:

## Public Member Functions
void | powerUp ([retval] out IProgress progress)
| Starts the virtual machine execution using the current machine state (that is, its current execution state, current settings and current storage devices). More...
void | powerUpPaused ([retval] out IProgress progress)
| Identical to powerUp except that the VM will enter the MachineState_Paused state, instead of MachineState_Running. More...
void | powerDown ([retval] out IProgress progress)
| Initiates the power down procedure to stop the virtual machine execution. More...
void | reset ()
| Resets the virtual machine. More...
void | pause ()
| Pauses the virtual machine execution. More...
void | resume ()
| Resumes the virtual machine execution. More...
void | powerButton ()
| Sends the ACPI power button event to the guest. More...
void | sleepButton ()
| Sends the ACPI sleep button event to the guest. More...
void | getPowerButtonHandled ([retval] out boolean handled)
| Checks if the last power button event was handled by guest. More...
void | getGuestEnteredACPIMode ([retval] out boolean entered)
| Checks if the guest entered the ACPI mode G0 (working) or G1 (sleeping). More...
void | getDeviceActivity (in DeviceType[] type, [retval] out DeviceActivity[] activity)
| Gets the current activity type of given devices or device groups. More...
void | attachUSBDevice (in wstringUUID id, in wstring captureFilename)
| Attaches a host USB device with the given UUID to the USB controller of the virtual machine. More...
void | detachUSBDevice (in wstringUUID id, [retval] out IUSBDevice device)
| Detaches an USB device with the given UUID from the USB controller of the virtual machine. More...
void | findUSBDeviceByAddress (in wstring name, [retval] out IUSBDevice device)
| Searches for a USB device with the given host address. More...
void | findUSBDeviceById (in wstringUUID id, [retval] out IUSBDevice device)
| Searches for a USB device with the given UUID. More...
void | createSharedFolder (in wstring name, in wstring hostPath, in boolean writable, in boolean automount)
| Creates a transient new shared folder by associating the given logical name with the given host path, adds it to the collection of shared folders and starts sharing it. More...
void | removeSharedFolder (in wstring name)
| Removes a transient shared folder with the given name previously created by createSharedFolder from the collection of shared folders and stops sharing it. More...
void | teleport (in wstring hostname, in unsigned long tcpport, in wstring password, in unsigned long maxDowntime, [retval] out IProgress progress)
| Teleport the VM to a different host machine or process. More...
void | addDiskEncryptionPassword (in wstring id, in wstring password, in boolean clearOnSuspend)
| Adds a password used for hard disk encryption/decryption. More...
void | addDiskEncryptionPasswords (in wstring[] ids, in wstring[] passwords, in boolean clearOnSuspend)
| Adds a password used for hard disk encryption/decryption. More...
void | removeDiskEncryptionPassword (in wstring id)
| Removes a password used for hard disk encryption/decryption from the running VM. More...
void | clearAllDiskEncryptionPasswords ()
| Clears all provided supplied disk encryption passwords. More...

## Public Attributes
readonly attribute IMachine | machine
| Machine object for this console session. More...
readonly attribute MachineState | state
| Current execution state of the machine. More...
readonly attribute IGuest | guest
| Guest object. More...
readonly attribute IKeyboard | keyboard
| Virtual keyboard object. More...
readonly attribute IMouse | mouse
| Virtual mouse object. More...
readonly attribute IDisplay | display
| Virtual display object. More...
readonly attribute IMachineDebugger | debugger
| Debugging interface. More...
readonly attribute IUSBDevice [] | USBDevices
| Collection of USB devices currently attached to the virtual USB controller. More...
readonly attribute IHostUSBDevice [] | remoteUSBDevices
| List of USB devices currently attached to the remote VRDE client. More...
readonly attribute ISharedFolder [] | sharedFolders
| Collection of shared folders for the current session. More...
readonly attribute IVRDEServerInfo | VRDEServerInfo
| Interface that provides information on Remote Desktop Extension (VRDE) connection. More...
readonly attribute IEventSource | eventSource
| Event source for console events. More...
readonly attribute IPCIDeviceAttachment [] | attachedPCIDevices
| Array of PCI devices attached to this machine. More...
attribute boolean | useHostClipboard
| Whether the guest clipboard should be connected to the host one or whether it should only be allowed access to the VRDE clipboard. More...
readonly attribute IEmulatedUSB | emulatedUSB
| Interface that manages emulated USB devices. More...

## Detailed Description

The IConsole interface represents an interface to control virtual machine execution.

A console object gets created when a machine has been locked for a particular session (client process) using IMachine::lockMachine or IMachine::launchVMProcess. The console object can then be found in the session's ISession::console attribute.

Methods of the IConsole interface allow the caller to query the current virtual machine execution state, pause the machine or power it down, save the machine state or take a snapshot, attach and detach removable media and so on.

See also
  ISession

Interface ID:
  `{872DA645-4A9B-1727-BEE2-5585105B9EED}`

## Member Function Documentation

## ◆ powerUp()

void IConsole::powerUp | ( | [retval] out IProgress | progress | ) |

Starts the virtual machine execution using the current machine state (that is, its current execution state, current settings and current storage devices).

If the machine is powered off or aborted, the execution will start from the beginning (as if the real hardware were just powered on).

If the machine is in the MachineState_Saved state, it will continue its execution the point where the state has been saved.

If the machine IMachine::teleporterEnabled property is enabled on the machine being powered up, the machine will wait for an incoming teleportation in the MachineState_TeleportingIn state. The returned progress object will have at least three operations where the last three are defined as: (1) powering up and starting TCP server, (2) waiting for incoming teleportations, and (3) perform teleportation. These operations will be reflected as the last three operations of the progress objected returned by IMachine::launchVMProcess as well.

Parameters

  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine already running.
  VBOX_E_HOST_ERROR | Host interface does not exist or name not set.
  VBOX_E_FILE_ERROR | Invalid saved state file.

Note
  This method is only useful for front-ends that want to actually execute virtual machines in their own process (like the VirtualBox or VBoxSDL front-ends). Unless you are intending to write such a front-end, do not call this method. If you simply want to start virtual machine execution using one of the existing front-ends (for example the VirtualBox GUI or headless server), use IMachine::launchVMProcess instead; these front-ends will power up the machine automatically for you.

See also
  IMachine::saveState

## ◆ powerUpPaused()

void IConsole::powerUpPaused | ( | [retval] out IProgress | progress | ) |

Identical to powerUp except that the VM will enter the MachineState_Paused state, instead of MachineState_Running.

Parameters

  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine already running.
  VBOX_E_HOST_ERROR | Host interface does not exist or name not set.
  VBOX_E_FILE_ERROR | Invalid saved state file.

See also
  powerUp

## ◆ powerDown()

void IConsole::powerDown | ( | [retval] out IProgress | progress | ) |

Initiates the power down procedure to stop the virtual machine execution.

The completion of the power down procedure is tracked using the returned IProgress object. After the operation is complete, the machine will go to the PoweredOff state.

Parameters

  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine must be Running, Paused or Stuck to be powered down.

## ◆ reset()

void IConsole::reset | ( |  | ) |

Resets the virtual machine.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state.
  VBOX_E_VM_ERROR | Virtual machine error in reset operation.

## ◆ pause()

void IConsole::pause | ( |  | ) |

Pauses the virtual machine execution.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state.
  VBOX_E_VM_ERROR | Virtual machine error in suspend operation.

## ◆ resume()

void IConsole::resume | ( |  | ) |

Resumes the virtual machine execution.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not in Paused state.
  VBOX_E_VM_ERROR | Virtual machine error in resume operation.

## ◆ powerButton()

void IConsole::powerButton | ( |  | ) |

Sends the ACPI power button event to the guest.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state.
  VBOX_E_PDM_ERROR | Controlled power off failed.

## ◆ sleepButton()

void IConsole::sleepButton | ( |  | ) |

Sends the ACPI sleep button event to the guest.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state.
  VBOX_E_PDM_ERROR | Sending sleep button event failed.

## ◆ getPowerButtonHandled()

void IConsole::getPowerButtonHandled | ( | [retval] out boolean | handled | ) |

Checks if the last power button event was handled by guest.

Expected result codes:

  VBOX_E_PDM_ERROR | Checking if the event was handled by the guest OS failed.

## ◆ getGuestEnteredACPIMode()

void IConsole::getGuestEnteredACPIMode | ( | [retval] out boolean | entered | ) |

Checks if the guest entered the ACPI mode G0 (working) or G1 (sleeping).

If this method returns `false`, the guest will most likely not respond to external ACPI events.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state.

## ◆ getDeviceActivity()

void IConsole::getDeviceActivity | ( | in DeviceType [] | type,
|  | [retval] out DeviceActivity [] | activity
| ) |  |

Gets the current activity type of given devices or device groups.

Expected result codes:

  E_INVALIDARG | Invalid device type.

## ◆ attachUSBDevice()

void IConsole::attachUSBDevice | ( | in wstringUUID | id,
|  | in wstring | captureFilename
| ) |  |

Attaches a host USB device with the given UUID to the USB controller of the virtual machine.

The device needs to be in one of the following states: USBDeviceState_Busy, USBDeviceState_Available or USBDeviceState_Held, otherwise an error is immediately returned.

When the device state is Busy, an error may also be returned if the host computer refuses to release it for some reason.

Parameters

  id | UUID of the host USB device to attach.
  captureFilename | Filename to capture the USB traffic to.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine state neither Running nor Paused.
  VBOX_E_PDM_ERROR | Virtual machine does not have a USB controller.

See also
  IUSBDeviceFilters::deviceFilters, USBDeviceState

## ◆ detachUSBDevice()

void IConsole::detachUSBDevice | ( | in wstringUUID | id,
|  | [retval] out IUSBDevice | device
| ) |  |

Detaches an USB device with the given UUID from the USB controller of the virtual machine.

After this method succeeds, the VirtualBox server re-initiates all USB filters as if the device were just physically attached to the host, but filters of this machine are ignored to avoid a possible automatic re-attachment.

Parameters

  id | UUID of the USB device to detach.
  device | Detached USB device.

Expected result codes:

  VBOX_E_PDM_ERROR | Virtual machine does not have a USB controller.
  E_INVALIDARG | USB device not attached to this virtual machine.

See also
  IUSBDeviceFilters::deviceFilters, USBDeviceState

## ◆ findUSBDeviceByAddress()

void IConsole::findUSBDeviceByAddress | ( | in wstring | name,
|  | [retval] out IUSBDevice | device
| ) |  |

Searches for a USB device with the given host address.

Parameters

  name | Address of the USB device (as assigned by the host) to search for.
  device | Found USB device object.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | Given `name` does not correspond to any USB device.

See also
  IUSBDevice::address

## ◆ findUSBDeviceById()

void IConsole::findUSBDeviceById | ( | in wstringUUID | id,
|  | [retval] out IUSBDevice | device
| ) |  |

Searches for a USB device with the given UUID.

Parameters

  id | UUID of the USB device to search for.
  device | Found USB device object.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | Given `id` does not correspond to any USB device.

See also
  IUSBDevice::id

## ◆ createSharedFolder()

void IConsole::createSharedFolder | ( | in wstring | name,
|  | in wstring | hostPath,
|  | in boolean | writable,
|  | in boolean | automount
| ) |  |

Creates a transient new shared folder by associating the given logical name with the given host path, adds it to the collection of shared folders and starts sharing it.

Refer to the description of ISharedFolder to read more about logical names.

Parameters

  name | Unique logical name of the shared folder.
  hostPath | Full path to the shared folder in the host file system.
  writable | Whether the share is writable or readonly
  automount | Whether the share gets automatically mounted by the guest or not.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine in Saved state or currently changing state.
  VBOX_E_FILE_ERROR | Shared folder already exists or not accessible.

## ◆ removeSharedFolder()

void IConsole::removeSharedFolder | ( | in wstring | name | ) |

Removes a transient shared folder with the given name previously created by createSharedFolder from the collection of shared folders and stops sharing it.

Parameters

  name | Logical name of the shared folder to remove.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine in Saved state or currently changing state.
  VBOX_E_FILE_ERROR | Shared folder does not exists.

## ◆ teleport()

void IConsole::teleport | ( | in wstring | hostname,
|  | in unsigned long | tcpport,
|  | in wstring | password,
|  | in unsigned long | maxDowntime,
|  | [retval] out IProgress | progress
| ) |  |

Teleport the VM to a different host machine or process.

Todo:
  Explain the details.

Parameters

  hostname | The name or IP of the host to teleport to.
  tcpport | The TCP port to connect to (1..65535).
  password | The password.
  maxDowntime | The maximum allowed downtime given as milliseconds. 0 is not a valid value. Recommended value: 250 ms.

The higher the value is, the greater the chance for a successful teleportation. A small value may easily result in the teleportation process taking hours and eventually fail.

Parameters

  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not running or paused.

Note
  The current implementation treats this a guideline, not as an absolute rule.

## ◆ addDiskEncryptionPassword()

void IConsole::addDiskEncryptionPassword | ( | in wstring | id,
|  | in wstring | password,
|  | in boolean | clearOnSuspend
| ) |  |

Adds a password used for hard disk encryption/decryption.

Parameters

  id | The identifier used for the password. Must match the identifier used when the encrypted medium was created.
  password | The password.
  clearOnSuspend | Flag whether to clear the password on VM suspend (due to a suspending host for example). The password must be supplied again before the VM can resume.

Expected result codes:

  VBOX_E_PASSWORD_INCORRECT | The password provided wasn't correct for at least one disk using the provided ID.

## ◆ addDiskEncryptionPasswords()

void IConsole::addDiskEncryptionPasswords | ( | in wstring [] | ids,
|  | in wstring [] | passwords,
|  | in boolean | clearOnSuspend
| ) |  |

Adds a password used for hard disk encryption/decryption.

Parameters

  ids | List of identifiers for the passwords. Must match the identifier used when the encrypted medium was created.
  passwords | List of passwords.
  clearOnSuspend | Flag whether to clear the given passwords on VM suspend (due to a suspending host for example). The passwords must be supplied again before the VM can resume.

Expected result codes:

  VBOX_E_PASSWORD_INCORRECT | The password provided wasn't correct for at least one disk using the provided ID.

## ◆ removeDiskEncryptionPassword()

void IConsole::removeDiskEncryptionPassword | ( | in wstring | id | ) |

Removes a password used for hard disk encryption/decryption from the running VM.

As soon as the medium requiring this password is accessed the VM is paused with an error and the password must be provided again.

Parameters

  id | The identifier used for the password. Must match the identifier used when the encrypted medium was created.

## ◆ clearAllDiskEncryptionPasswords()

void IConsole::clearAllDiskEncryptionPasswords | ( |  | ) |

Clears all provided supplied disk encryption passwords.

## Member Data Documentation

## ◆ machine

readonly attribute IMachine IConsole::machine

Machine object for this console session.

Note
  This is a convenience property, it has the same value as ISession::machine of the corresponding session object.

## ◆ state

readonly attribute MachineState IConsole::state

Current execution state of the machine.

Note
  This property always returns the same value as the corresponding property of the IMachine object for this console session. For the process that owns (executes) the VM, this is the preferable way of querying the VM state, because no IPC calls are made.

## ◆ guest

readonly attribute IGuest IConsole::guest

Guest object.

## ◆ keyboard

readonly attribute IKeyboard IConsole::keyboard

Virtual keyboard object.

Note
  If the machine is not running, any attempt to use the returned object will result in an error.

## ◆ mouse

readonly attribute IMouse IConsole::mouse

Virtual mouse object.

Note
  If the machine is not running, any attempt to use the returned object will result in an error.

## ◆ display

readonly attribute IDisplay IConsole::display

Virtual display object.

Note
  If the machine is not running, any attempt to use the returned object will result in an error.

## ◆ debugger

readonly attribute IMachineDebugger IConsole::debugger

Debugging interface.

## ◆ USBDevices

readonly attribute IUSBDevice [] IConsole::USBDevices

Collection of USB devices currently attached to the virtual USB controller.

Note
  The collection is empty if the machine is not running.

## ◆ remoteUSBDevices

readonly attribute IHostUSBDevice [] IConsole::remoteUSBDevices

List of USB devices currently attached to the remote VRDE client.

Once a new device is physically attached to the remote host computer, it appears in this list and remains there until detached.

## ◆ sharedFolders

readonly attribute ISharedFolder [] IConsole::sharedFolders

Collection of shared folders for the current session.

These folders are called transient shared folders because they are available to the guest OS running inside the associated virtual machine only for the duration of the session (as opposed to IMachine::sharedFolders which represent permanent shared folders). When the session is closed (e.g. the machine is powered down), these folders are automatically discarded.

New shared folders are added to the collection using createSharedFolder. Existing shared folders can be removed using removeSharedFolder.

## ◆ VRDEServerInfo

readonly attribute IVRDEServerInfo IConsole::VRDEServerInfo

Interface that provides information on Remote Desktop Extension (VRDE) connection.

## ◆ eventSource

readonly attribute IEventSource IConsole::eventSource

Event source for console events.

## ◆ attachedPCIDevices

readonly attribute IPCIDeviceAttachment [] IConsole::attachedPCIDevices

Array of PCI devices attached to this machine.

## ◆ useHostClipboard

attribute boolean IConsole::useHostClipboard

Whether the guest clipboard should be connected to the host one or whether it should only be allowed access to the VRDE clipboard.

This setting may not affect existing guest clipboard connections which are already connected to the host clipboard.

## ◆ emulatedUSB

readonly attribute IEmulatedUSB IConsole::emulatedUSB

Interface that manages emulated USB devices.