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

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
progressProgress 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
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
progressProgress 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
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
progressProgress 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.
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.
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.
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.
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.
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.
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.
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.
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.
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
idUUID of the host USB device to attach.
captureFilenameFilename 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
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
idUUID of the USB device to detach.
deviceDetached 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
void IConsole::findUSBDeviceByAddress ( in wstring  name,
[retval] out IUSBDevice  device 
)

Searches for a USB device with the given host address.

Parameters
nameAddress of the USB device (as assigned by the host) to search for.
deviceFound USB device object.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any USB device.
See also
IUSBDevice::address
void IConsole::findUSBDeviceById ( in wstringUUID  id,
[retval] out IUSBDevice  device 
)

Searches for a USB device with the given UUID.

Parameters
idUUID of the USB device to search for.
deviceFound USB device object.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Given id does not correspond to any USB device.
See also
IUSBDevice::id
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
nameUnique logical name of the shared folder.
hostPathFull path to the shared folder in the host file system.
writableWhether the share is writable or readonly
automountWhether 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.
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
nameLogical 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.
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
hostnameThe name or IP of the host to teleport to.
tcpportThe TCP port to connect to (1..65535).
passwordThe password.
maxDowntimeThe 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
progressProgress 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.
void IConsole::addDiskEncryptionPassword ( in wstring  id,
in wstring  password,
in boolean  clearOnSuspend 
)

Adds a password used for hard disk encryption/decryption.

Parameters
idThe identifier used for the password. Must match the identifier used when the encrypted medium was created.
passwordThe password.
clearOnSuspendFlag 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.
void IConsole::addDiskEncryptionPasswords ( in wstring[]  ids,
in wstring[]  passwords,
in boolean  clearOnSuspend 
)

Adds a password used for hard disk encryption/decryption.

Parameters
idsList of identifiers for the passwords. Must match the identifier used when the encrypted medium was created.
passwordsList of passwords.
clearOnSuspendFlag 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.
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
idThe identifier used for the password. Must match the identifier used when the encrypted medium was created.
void IConsole::clearAllDiskEncryptionPasswords ( )

Clears all provided supplied disk encryption passwords.

Member Data Documentation

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.
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.
readonly attribute IGuest IConsole::guest

Guest object.

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.
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.
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.
readonly attribute IMachineDebugger IConsole::debugger

Debugging interface.

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

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.

readonly attribute IVRDEServerInfo IConsole::VRDEServerInfo

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

readonly attribute IEventSource IConsole::eventSource

Event source for console events.

readonly attribute IPCIDeviceAttachment [] IConsole::attachedPCIDevices

Array of PCI devices attached to this machine.

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.

readonly attribute IEmulatedUSB IConsole::emulatedUSB

Interface that manages emulated USB devices.