Public Member Functions | Public Attributes

IConsole Interface Reference

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

List of all members.

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).
void powerUpPaused ([retval] out IProgress progress)
 Identical to powerUp except that the VM will enter the MachineState_Paused state, instead of MachineState_Running.
void powerDown ([retval] out IProgress progress)
 Initiates the power down procedure to stop the virtual machine execution.
void reset ()
 Resets the virtual machine.
void pause ()
 Pauses the virtual machine execution.
void resume ()
 Resumes the virtual machine execution.
void powerButton ()
 Sends the ACPI power button event to the guest.
void sleepButton ()
 Sends the ACPI sleep button event to the guest.
void getPowerButtonHandled ([retval] out boolean handled)
 Checks if the last power button event was handled by guest.
void getGuestEnteredACPIMode ([retval] out boolean entered)
 Checks if the guest entered the ACPI mode G0 (working) or G1 (sleeping).
void saveState ([retval] out IProgress progress)
 Saves the current execution state of a running virtual machine and stops its execution.
void adoptSavedState (in wstring savedStateFile)
 Associates the given saved state file to the virtual machine.
void discardSavedState (in boolean fRemoveFile)
 Forcibly resets the machine to "Powered Off" state if it is currently in the "Saved" state (previously created by saveState).
void getDeviceActivity (in DeviceType type,[retval] out DeviceActivity activity)
 Gets the current activity type of a given device or device group.
void attachUSBDevice (in wstringUUID id)
 Attaches a host USB device with the given UUID to the USB controller of the virtual machine.
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.
void findUSBDeviceByAddress (in wstring name,[retval] out IUSBDevice device)
 Searches for a USB device with the given host address.
void findUSBDeviceById (in wstringUUID id,[retval] out IUSBDevice device)
 Searches for a USB device with the given UUID.
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.
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.
void takeSnapshot (in wstring name, in wstring description,[retval] out IProgress progress)
 Saves the current execution state and all settings of the machine and creates differencing images for all normal (non-independent) media.
void deleteSnapshot (in wstringUUID id,[retval] out IProgress progress)
 Starts deleting the specified snapshot asynchronously.
void deleteSnapshotAndAllChildren (in wstringUUID id,[retval] out IProgress progress)
 Starts deleting the specified snapshot and all its children asynchronously.
void deleteSnapshotRange (in wstringUUID startId, in wstringUUID endId,[retval] out IProgress progress)
 Starts deleting the specified snapshot range.
void restoreSnapshot (in ISnapshot snapshot,[retval] out IProgress progress)
 Starts resetting the machine's current state to the state contained in the given snapshot, asynchronously.
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.

Public Attributes

readonly attribute IMachine machine
 Machine object for this console session.
readonly attribute MachineState state
 Current execution state of the machine.
readonly attribute IGuest guest
 Guest object.
readonly attribute IKeyboard keyboard
 Virtual keyboard object.
readonly attribute IMouse mouse
 Virtual mouse object.
readonly attribute IDisplay display
 Virtual display object.
readonly attribute IMachineDebugger debugger
 Debugging interface.
readonly attribute IUSBDevice[] USBDevices
 Collection of USB devices currently attached to the virtual USB controller.
readonly attribute IHostUSBDevice[] remoteUSBDevices
 List of USB devices currently attached to the remote VRDE client.
readonly attribute ISharedFolder[] sharedFolders
 Collection of shared folders for the current session.
readonly attribute IVRDEServerInfo VRDEServerInfo
 Interface that provides information on Remote Desktop Extension (VRDE) connection.
readonly attribute IEventSource eventSource
 Event source for console events.
readonly attribute
IPCIDeviceAttachment[] 
attachedPCIDevices
 Array of PCI devices attached to this machine.
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.
readonly attribute IEmulatedUSB emulatedUSB
 Interface that manages emulated USB devices.

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:
{8AB7C520-2442-4B66-8D74-4FF1E195D2B6}

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:
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:
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:
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
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.
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::saveState ( [retval] out IProgress  progress  ) 

Saves the current execution state of a running virtual machine and stops its execution.

After this operation completes, the machine will go to the Saved state. Next time it is powered up, this state will be restored and the machine will continue its execution from the place where it was saved.

This operation differs from taking a snapshot to the effect that it doesn't create new differencing media. Also, once the machine is powered up from the state saved using this method, the saved state is deleted, so it will be impossible to return to this state later.

Parameters:
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_INVALID_VM_STATE Virtual machine state neither Running nor Paused.
VBOX_E_FILE_ERROR Failed to create directory for saved state file.
Note:
On success, this method implicitly calls IMachine::saveSettings to save all current machine settings (including runtime changes to the DVD medium, etc.). Together with the impossibility to change any VM settings when it is in the Saved state, this guarantees adequate hardware configuration of the machine when it is restored from the saved state file.
The machine must be in the Running or Paused state, otherwise the operation will fail.
See also:
takeSnapshot
void IConsole::adoptSavedState ( in wstring  savedStateFile  ) 

Associates the given saved state file to the virtual machine.

On success, the machine will go to the Saved state. Next time it is powered up, it will be restored from the adopted saved state and continue execution from the place where the saved state file was created.

The specified saved state file path may be absolute or relative to the folder the VM normally saves the state to (usually, IMachine::snapshotFolder).

Parameters:
savedStateFile Path to the saved state file to adopt.
Expected result codes:
VBOX_E_INVALID_VM_STATE Virtual machine state neither PoweredOff nor Aborted.
Note:
It's a caller's responsibility to make sure the given saved state file is compatible with the settings of this virtual machine that represent its virtual hardware (memory size, storage disk configuration etc.). If there is a mismatch, the behavior of the virtual machine is undefined.
void IConsole::discardSavedState ( in boolean  fRemoveFile  ) 

Forcibly resets the machine to "Powered Off" state if it is currently in the "Saved" state (previously created by saveState).

Next time the machine is powered up, a clean boot will occur.

If fRemoveFile is true, the file in the machine directory into which the machine state was saved is also deleted. If this is false, then the state can be recovered and later re-inserted into a machine using adoptSavedState. The location of the file can be found in the IMachine::stateFilePath attribute.

Parameters:
fRemoveFile Whether to also remove the saved state file.
Expected result codes:
VBOX_E_INVALID_VM_STATE Virtual machine not in state Saved.
Note:
This operation is equivalent to resetting or powering off the machine without doing a proper shutdown of the guest operating system; as with resetting a running phyiscal computer, it can can lead to data loss.
void IConsole::getDeviceActivity ( in DeviceType  type,
[retval] out DeviceActivity  activity 
)

Gets the current activity type of a given device or device group.

Expected result codes:
E_INVALIDARG Invalid device type.
void IConsole::attachUSBDevice ( in wstringUUID  id  ) 

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.
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:
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
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
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
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.
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.
void IConsole::takeSnapshot ( in wstring  name,
in wstring  description,
[retval] out IProgress  progress 
)

Saves the current execution state and all settings of the machine and creates differencing images for all normal (non-independent) media.

See ISnapshot for an introduction to snapshots.

This method can be called for a PoweredOff, Saved (see saveState), Running or Paused virtual machine. When the machine is PoweredOff, an offline snapshot is created. When the machine is Running a live snapshot is created, and an online snapshot is created when Paused.

The taken snapshot is always based on the current snapshot of the associated virtual machine and becomes a new current snapshot.

Parameters:
name Short name for the snapshot.
description Optional description of the snapshot.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_INVALID_VM_STATE Virtual machine currently changing state.
Note:
This method implicitly calls IMachine::saveSettings to save all current machine settings before taking an offline snapshot.
void IConsole::deleteSnapshot ( in wstringUUID  id,
[retval] out IProgress  progress 
)

Starts deleting the specified snapshot asynchronously.

See ISnapshot for an introduction to snapshots.

The execution state and settings of the associated machine stored in the snapshot will be deleted. The contents of all differencing media of this snapshot will be merged with the contents of their dependent child media to keep the medium chain valid (in other words, all changes represented by media being deleted will be propagated to their child medium). After that, this snapshot's differencing medium will be deleted. The parent of this snapshot will become a new parent for all its child snapshots.

If the deleted snapshot is the current one, its parent snapshot will become a new current snapshot. The current machine state is not directly affected in this case, except that currently attached differencing media based on media of the deleted snapshot will be also merged as described above.

If the deleted snapshot is the first or current snapshot, then the respective IMachine attributes will be adjusted. Deleting the current snapshot will also implicitly call IMachine::saveSettings to make all current machine settings permanent.

Deleting a snapshot has the following preconditions:

  • Child media of all normal media of the deleted snapshot must be accessible (see IMedium::state) for this operation to succeed. If only one running VM refers to all images which participates in merging the operation can be performed while the VM is running. Otherwise all virtual machines whose media are directly or indirectly based on the media of deleted snapshot must be powered off. In any case, online snapshot deleting usually is slower than the same operation without any running VM.
  • You cannot delete the snapshot if a medium attached to it has more than one child medium (differencing images) because otherwise merging would be impossible. This might be the case if there is more than one child snapshot or differencing images were created for other reason (e.g. implicitly because of multiple machine attachments).

The virtual machine's state is changed to "DeletingSnapshot", "DeletingSnapshotOnline" or "DeletingSnapshotPaused" while this operation is in progress.

Parameters:
id UUID of the snapshot to delete.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_INVALID_VM_STATE The running virtual machine prevents deleting this snapshot. This happens only in very specific situations, usually snapshots can be deleted without trouble while a VM is running. The error message text explains the reason for the failure.
Note:
Merging medium contents can be very time and disk space consuming, if these media are big in size and have many children. However, if the snapshot being deleted is the last (head) snapshot on the branch, the operation will be rather quick.
void IConsole::deleteSnapshotAndAllChildren ( in wstringUUID  id,
[retval] out IProgress  progress 
)

Starts deleting the specified snapshot and all its children asynchronously.

See ISnapshot for an introduction to snapshots. The conditions and many details are the same as with deleteSnapshot.

This operation is very fast if the snapshot subtree does not include the current state. It is still significantly faster than deleting the snapshots one by one if the current state is in the subtree and there are more than one snapshots from current state to the snapshot which marks the subtree, since it eliminates the incremental image merging.

Parameters:
id UUID of the snapshot to delete, including all its children.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_INVALID_VM_STATE The running virtual machine prevents deleting this snapshot. This happens only in very specific situations, usually snapshots can be deleted without trouble while a VM is running. The error message text explains the reason for the failure.
E_NOTIMPL The method is not implemented yet.
Note:
This API method is right now not implemented!
void IConsole::deleteSnapshotRange ( in wstringUUID  startId,
in wstringUUID  endId,
[retval] out IProgress  progress 
)

Starts deleting the specified snapshot range.

This is limited to linear snapshot lists, which means there may not be any other child snapshots other than the direct sequence between the start and end snapshot. If the start and end snapshot point to the same snapshot this method is completely equivalent to deleteSnapshot. See ISnapshot for an introduction to snapshots. The conditions and many details are the same as with deleteSnapshot.

This operation is generally faster than deleting snapshots one by one and often also needs less extra disk space before freeing up disk space by deleting the removed disk images corresponding to the snapshot.

Parameters:
startId UUID of the first snapshot to delete.
endId UUID of the last snapshot to delete.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_INVALID_VM_STATE The running virtual machine prevents deleting this snapshot. This happens only in very specific situations, usually snapshots can be deleted without trouble while a VM is running. The error message text explains the reason for the failure.
E_NOTIMPL The method is not implemented yet.
Note:
This API method is right now not implemented!
void IConsole::restoreSnapshot ( in ISnapshot  snapshot,
[retval] out IProgress  progress 
)

Starts resetting the machine's current state to the state contained in the given snapshot, asynchronously.

All current settings of the machine will be reset and changes stored in differencing media will be lost. See ISnapshot for an introduction to snapshots.

After this operation is successfully completed, new empty differencing media are created for all normal media of the machine.

If the given snapshot is an online snapshot, the machine will go to the saved state, so that the next time it is powered on, the execution state will be restored from the state of the snapshot.

Parameters:
snapshot The snapshot to restore the VM state from.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_INVALID_VM_STATE Virtual machine is running.
Note:
The machine must not be running, otherwise the operation will fail.
If the machine state is Saved prior to this operation, the saved state file will be implicitly deleted (as if IConsole::discardSavedState were called).
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.

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.

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.

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.

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

readonly attribute IEventSource IConsole::eventSource

Event source for console events.

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.