# 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 | forgetSavedState (in boolean remove)
| Forgets the saved state of the virtual machine 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)
| 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 | 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.
void | registerCallback (in IConsoleCallback callback)
| Registers a new console callback on this instance.
void | unregisterCallback (in IConsoleCallback callback)
| Unregisters the console callback previously registered using registerCallback.
## Public Attributes
readonly attribute IMachine | machine
| Machine object this console is sessioned with.
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 VRDP client.
readonly attribute ISharedFolder[] | sharedFolders
| Collection of shared folders for the current session.
readonly attribute IRemoteDisplayInfo | remoteDisplayInfo
| Interface that provides information on Remote Display (VRDP) connection.

## Detailed Description

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

The console object that implements the IConsole interface is obtained from a session object after the session for the given machine has been opened using one of IVirtualBox::openSession, IVirtualBox::openRemoteSession or IVirtualBox::openExistingSession methods.

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:
  `{6375231A-C17C-464B-92CB-AE9E128D71C3}`

## 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 IVirtualBox::openRemoteSession 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:
  Unless you are trying to write a new VirtualBox front-end that performs direct machine execution (like the VirtualBox or VBoxSDL front-ends), don't call IConsole::powerUp in a direct session opened by IVirtualBox::openSession and use this session only to change virtual machine settings. If you simply want to start virtual machine execution using one of the existing front-ends (for example the VirtualBox GUI or headless server), simply use IVirtualBox::openRemoteSession; 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::forgetSavedState | ( | in boolean | remove | ) |

Forgets the saved state of the virtual machine previously created by saveState.

Next time the machine is powered up, a clean boot will occur. If remove is `true` the saved state file is deleted.

Parameters:

  | remove | If `true` 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 in the guest OS.

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:
  IUSBController::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:
  IUSBController::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 |
| ) |  |  |

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

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 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. In particular, this means that all virtual machines, whose media are directly or indirectly based on the media of deleted snapshot, must be powered off.
- You cannot delete the snapshot if a medium attached to it has more than once 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::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::forgetSavedState 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.

void IConsole::registerCallback | ( | in IConsoleCallback | callback | ) |

Registers a new console callback on this instance.

The methods of the callback interface will be called by this instance when the appropriate event occurs.

void IConsole::unregisterCallback | ( | in IConsoleCallback | callback | ) |

Unregisters the console callback previously registered using registerCallback.

Expected result codes:

  E_INVALIDARG | Given callback handler is not registered.

## Member Data Documentation

readonly attribute IMachine IConsole::machine

Machine object this console is sessioned with.

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 this console is sessioned with. 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 VRDP 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 IRemoteDisplayInfo IConsole::remoteDisplayInfo

Interface that provides information on Remote Display (VRDP) connection.