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 (i.e.
void powerDown ()
 Stops the virtual machine execution.
void powerDownAsync ([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 ()
 Send the ACPI power button event to the guest.
void sleepButton ()
 Send the ACPI sleep button event to the guest.
void getPowerButtonHandled ([retval] out boolean handled)
 Check if the last power button event was handled by guest.
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 ()
 Discards (deletes) 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 uuid id)
 Attaches a host USB device with the given UUID to the USB controller of the virtual machine.
void detachUSBDevice (in uuid id,[retval] out IUSBDevice device)
 Detaches an USB device with the given UUID from the USB controller oif the virtual machine.
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) hard disks.
void discardSnapshot (in uuid id,[retval] out IProgress progress)
 Starts discarding the specified snapshot.
void discardCurrentState ([retval] out IProgress progress)
 This operation is similar to discardSnapshot() but affects the current machine state.
void discardCurrentSnapshotAndState ([retval] out IProgress progress)
 This method is equivalent to doing discardSnapshot (currentSnapshot.id(), progress) followed by discardCurrentState().
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
IUSBDeviceCollection 
USBDevices
 Collection of USB devices currently attached to the virtual USB controller.
readonly attribute
IHostUSBDeviceCollection 
remoteUSBDevices
 List of USB devices currently attached to the remote VRDP client.
readonly attribute
ISharedFolderCollection 
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:
{E3C6D4A1-A935-47CA-B16D-F9E9C496E53E}

Member Function Documentation

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

Starts the virtual machine execution using the current machine state (i.e.

its current execution state, current settings and current hard disks).

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.

Parameters:
progress Progress object to track the operation completion.
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::powerDown (  ) 

Stops the virtual machine execution.

After this operation completes, the machine will go to the PoweredOff state.

Deprecated:
This method will be removed in VirtualBox 2.1 where the powerDownAsync() method will take its name. Do not use this method in the code.

void IConsole::powerDownAsync ( [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.

Warning:
This method will be renamed to "powerDown" in VirtualBox 2.1 where the original powerDown() method will be removed. You will need to rename "powerDownAsync" to "powerDown" in your sources to make them build with version 2.1.
Parameters:
progress Progress object to track the operation completion.

void IConsole::reset (  ) 

Resets the virtual machine.

void IConsole::pause (  ) 

Pauses the virtual machine execution.

void IConsole::resume (  ) 

Resumes the virtual machine execution.

void IConsole::powerButton (  ) 

Send the ACPI power button event to the guest.

void IConsole::sleepButton (  ) 

Send the ACPI sleep button event to the guest.

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

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

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 hard disks. 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.
Note:
On success, this method implicitly calls IMachine::saveSettings() to save all current machine settings (including runtime changes to the DVD drive, etc.). Together with the impossibility to change any VM settings when it is in the Saved state, this guarantees the 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 full 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.
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, hard disk configuration etc.). If there is a mismatch, the behavior of the virtual machine is undefined.

void IConsole::discardSavedState (  ) 

Discards (deletes) the saved state of the virtual machine previously created by saveState.

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

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.

void IConsole::attachUSBDevice ( in uuid  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: Busy, Available or 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.
See also:
IUSBController::deviceFilters, USBDeviceState

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

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

After this method succeeds, the VirtualBox server reinitiates 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 reattachment.

Parameters:
id UUID of the USB device to detach.
device Detached USB device.
See also:
IUSBController::deviceFilters, USBDeviceState

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

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.

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) hard disks.

This method can be called for a PoweredOff, Saved, Running or Paused virtual machine. When the machine is PoweredOff, an offline snapshot is created, in all other cases -- an online snapshot.

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.
Note:
This method implicitly calls IMachine::saveSettings() to save all current machine settings before taking an offline snapshot.
See also:
ISnapshot, saveState

void IConsole::discardSnapshot ( in uuid  id,
[retval] out IProgress  progress 
)

Starts discarding the specified snapshot.

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

If the discarded 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 hard disks based on hard disks of the discarded snapshot will be also merged as described above.

If the discarded snapshot is the first one (the root snapshot) and it has exactly one child snapshot, this child snapshot will become the first snapshot after discarding. If there are no children at all (i.e. the first snapshot is the only snapshot of the machine), both the current and the first snapshot of the machine will be set to null. In all other cases, the first snapshot cannot be discarded.

You cannot discard the snapshot if it stores normal (non-differencing) hard disks that have differencing hard disks based on them. Snapshots of such kind can be discarded only when every normal hard disk has either no children at all or exactly one child. In the former case, the normal hard disk simply becomes unused (i.e. not attached to any VM). In the latter case, it receives all the changes strored in the child hard disk, and then it replaces the child hard disk in the configuration of the corresponding snapshot or machine.

Also, you cannot discard the snapshot if it stores hard disks (of any type) having differencing child hard disks that belong to other machines. Such snapshots can be only discarded after you discard all snapshots of other machines containing "foreign" child disks, or detach these "foreign" child disks from machines they are attached to.

One particular example of the snapshot storing normal hard disks is the first snapshot of a virtual machine that had normal hard disks attached when taking the snapshot. Be careful when discarding such snapshots because this implicitly commits changes (made since the snapshot being discarded has been taken) to normal hard disks (as described above), which may be not what you want.

The virtual machine is put to the Discarding state until the discard operation is completed.

Parameters:
id UUID of the snapshot to discard.
progress Progress object to track the operation completion.
Note:
The machine must not be running, otherwise the operation will fail.

Child hard disks of all normal hard disks of the discarded snapshot must be accessible for this operation to succeed. In particular, this means that all virtual machines, whose hard disks are directly or indirectly based on the hard disks of discarded snapshot, must be powered off.

Merging hard disk contents can be very time and disk space consuming, if these disks are big in size and have many children. However, if the snapshot being discarded is the last (head) snapshot on the branch, the operation will be rather quick.

Note that discarding the current snapshot will imlicitly call IMachine::saveSettings() to make all current machine settings permanent.

void IConsole::discardCurrentState ( [retval] out IProgress  progress  ) 

This operation is similar to discardSnapshot() but affects the current machine state.

This means that the state stored in the current snapshot will become a new current state, and all current settings of the machine and changes stored in differencing hard disks will be lost.

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

If the current snapshot of the machine 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 current snapshot.

Parameters:
progress Progress object to track the operation completion.
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 discarded (as if IConsole::discardSavedState() were called).

void IConsole::discardCurrentSnapshotAndState ( [retval] out IProgress  progress  ) 

This method is equivalent to doing discardSnapshot (currentSnapshot.id(), progress) followed by discardCurrentState().

As a result, the machine will be fully restored from the snapshot preceeding the current snapshot, while both the current snapshot and the current machine state will be discarded.

If the current snapshot is the first snapshot of the machine (i.e. it has the only snapshot), the current machine state will be discarded before discarding the snapshot. In other words, the machine will be restored from its last snapshot, before discarding it. This differs from performing a single discardSnapshot() call (note that no discardCurrentState() will be possible after it) to the effect that the latter will preserve the current state instead of discarding it.

Unless explicitly mentioned otherwise, all remarks and limitations of the above two methods also apply to this method.

Parameters:
progress Progress object to track the operation completion.
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 discarded (as if discardSavedState() were called).

This method is more efficient than calling two above methods separately: it requires less IPC calls and provides a single progress object.

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.


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.

Debugging interface.

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

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

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 Display (VRDP) connection.


Generated on Fri Nov 21 21:38:41 2008 for VirtualBox Main API by  doxygen 1.5.5