|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.virtualbox_4_2.IUnknown
org.virtualbox_4_2.IConsole
public class IConsole
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(org.virtualbox_4_2.ISession,org.virtualbox_4_2.LockType)
or IMachine.launchVMProcess(org.virtualbox_4_2.ISession,String,String)
. The console object can
then be found in the session's ISession.getConsole()
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.
Interface ID: {DB7AB4CA-2A3F-4183-9243-C1208DA92392}
Field Summary |
---|
Fields inherited from class org.virtualbox_4_2.IUnknown |
---|
obj, port |
Constructor Summary | |
---|---|
IConsole(java.lang.String wrapped,
org.virtualbox_4_2.jaxws.VboxPortType port)
|
Method Summary | |
---|---|
void |
adoptSavedState(java.lang.String savedStateFile)
Associates the given saved state file to the virtual machine. |
void |
attachUSBDevice(java.lang.String id)
Attaches a host USB device with the given UUID to the USB controller of the virtual machine. |
void |
createSharedFolder(java.lang.String name,
java.lang.String hostPath,
java.lang.Boolean writable,
java.lang.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. |
IProgress |
deleteSnapshot(java.lang.String id)
Starts deleting the specified snapshot asynchronously. |
IProgress |
deleteSnapshotAndAllChildren(java.lang.String id)
Starts deleting the specified snapshot and all its children asynchronously. |
IProgress |
deleteSnapshotRange(java.lang.String startId,
java.lang.String endId)
Starts deleting the specified snapshot range. |
IUSBDevice |
detachUSBDevice(java.lang.String id)
Detaches an USB device with the given UUID from the USB controller of the virtual machine. |
void |
discardSavedState(java.lang.Boolean fRemoveFile)
Forcibly resets the machine to "Powered Off" state if it is currently in the "Saved" state (previously created by saveState() ). |
IUSBDevice |
findUSBDeviceByAddress(java.lang.String name)
Searches for a USB device with the given host address. |
IUSBDevice |
findUSBDeviceById(java.lang.String id)
Searches for a USB device with the given UUID. |
java.util.List<IPCIDeviceAttachment> |
getAttachedPCIDevices()
Array of PCI devices attached to this machine. |
DeviceActivity |
getDeviceActivity(DeviceType type)
Gets the current activity type of a given device or device group. |
IDisplay |
getDisplay()
Virtual display object. |
IEventSource |
getEventSource()
Event source for console events. |
IGuest |
getGuest()
Guest object. |
java.lang.Boolean |
getGuestEnteredACPIMode()
Checks if the guest entered the ACPI mode G0 (working) or G1 (sleeping). |
IKeyboard |
getKeyboard()
Virtual keyboard object. |
IMachine |
getMachine()
Machine object for this console session. |
IMouse |
getMouse()
Virtual mouse object. |
java.lang.Boolean |
getPowerButtonHandled()
Checks if the last power button event was handled by guest. |
java.util.List<IHostUSBDevice> |
getRemoteUSBDevices()
List of USB devices currently attached to the remote VRDE client. |
java.util.List<ISharedFolder> |
getSharedFolders()
Collection of shared folders for the current session. |
MachineState |
getState()
Current execution state of the machine. |
java.util.List<IUSBDevice> |
getUSBDevices()
Collection of USB devices currently attached to the virtual USB controller. |
java.lang.Boolean |
getUseHostClipboard()
Whether the guest clipboard should be connected to the host one or whether it should only be allowed access to the VRDE clipboard. |
IVRDEServerInfo |
getVRDEServerInfo()
Interface that provides information on Remote Desktop Extension (VRDE) connection. |
void |
pause()
Pauses the virtual machine execution. |
void |
powerButton()
Sends the ACPI power button event to the guest. |
IProgress |
powerDown()
Initiates the power down procedure to stop the virtual machine execution. |
IProgress |
powerUp()
Starts the virtual machine execution using the current machine state (that is, its current execution state, current settings and current storage devices). |
IProgress |
powerUpPaused()
Identical to powerUp except that the VM will enter the MachineState.Paused state, instead of
MachineState.Running . |
static IConsole |
queryInterface(IUnknown obj)
|
void |
removeSharedFolder(java.lang.String name)
Removes a transient shared folder with the given name previously created by createSharedFolder(String,String,Boolean,Boolean) from the collection of
shared folders and stops sharing it. |
void |
reset()
Resets the virtual machine. |
IProgress |
restoreSnapshot(ISnapshot snapshot)
Starts resetting the machine's current state to the state contained in the given snapshot, asynchronously. |
void |
resume()
Resumes the virtual machine execution. |
IProgress |
saveState()
Saves the current execution state of a running virtual machine and stops its execution. |
void |
setUseHostClipboard(java.lang.Boolean value)
Whether the guest clipboard should be connected to the host one or whether it should only be allowed access to the VRDE clipboard. |
void |
sleepButton()
Sends the ACPI sleep button event to the guest. |
IProgress |
takeSnapshot(java.lang.String name,
java.lang.String description)
Saves the current execution state and all settings of the machine and creates differencing images for all normal (non-independent) media. |
IProgress |
teleport(java.lang.String hostname,
java.lang.Long tcpport,
java.lang.String password,
java.lang.Long maxDowntime)
Teleport the VM to a different host machine or process. |
Methods inherited from class org.virtualbox_4_2.IUnknown |
---|
getRemoteWSPort, getWrapped, releaseRemote |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public IConsole(java.lang.String wrapped, org.virtualbox_4_2.jaxws.VboxPortType port)
Method Detail |
---|
public IMachine getMachine()
ISession.getMachine()
of the corresponding session
object.
public MachineState getState()
public IGuest getGuest()
public IKeyboard getKeyboard()
public IMouse getMouse()
public IDisplay getDisplay()
public java.util.List<IUSBDevice> getUSBDevices()
public java.util.List<IHostUSBDevice> getRemoteUSBDevices()
public java.util.List<ISharedFolder> getSharedFolders()
IMachine.getSharedFolders()
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(String,String,Boolean,Boolean)
. Existing shared folders can be
removed using removeSharedFolder(String)
.
public IVRDEServerInfo getVRDEServerInfo()
public IEventSource getEventSource()
public java.util.List<IPCIDeviceAttachment> getAttachedPCIDevices()
public java.lang.Boolean getUseHostClipboard()
public void setUseHostClipboard(java.lang.Boolean value)
value
- Booleanpublic static IConsole queryInterface(IUnknown obj)
public IProgress powerUp()
MachineState.Saved
state,
it will continue its execution the point where the state has
been saved.
If the machine IMachine.getTeleporterEnabled()
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(org.virtualbox_4_2.ISession,String,String)
as well.
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine already running. |
@link ::VBOX_E_HOST_ERROR VBOX_E_HOST_ERROR | Host interface does not exist or name not set. |
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Invalid saved state file. |
IMachine.launchVMProcess(org.virtualbox_4_2.ISession,String,String)
instead; these
front-ends will power up the machine automatically for you.saveState()
public IProgress powerUpPaused()
MachineState.Paused
state, instead of
MachineState.Running
.
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine already running. |
@link ::VBOX_E_HOST_ERROR VBOX_E_HOST_ERROR | Host interface does not exist or name not set. |
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Invalid saved state file. |
powerUp()
public IProgress powerDown()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine must be Running, Paused or Stuck to be powered down. |
public void reset()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state. |
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR | Virtual machine error in reset operation. |
public void pause()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state. |
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR | Virtual machine error in suspend operation. |
public void resume()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine not in Paused state. |
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR | Virtual machine error in resume operation. |
public void powerButton()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state. |
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERROR | Controlled power off failed. |
public void sleepButton()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state. |
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERROR | Sending sleep button event failed. |
public java.lang.Boolean getPowerButtonHandled()
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERROR | Checking if the event was handled by the guest OS failed. |
public java.lang.Boolean getGuestEnteredACPIMode()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state. |
public IProgress saveState()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine state neither Running nor Paused. |
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Failed to create directory for saved state file. |
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.
NOTE:
The machine must be in the Running or Paused state, otherwise
the operation will fail.takeSnapshot(String,String)
public void adoptSavedState(java.lang.String savedStateFile)
IMachine.getSnapshotFolder()
).
savedStateFile
- Path to the saved state file to adopt.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine state neither PoweredOff nor Aborted. |
public void discardSavedState(java.lang.Boolean fRemoveFile)
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(String)
.
The location of the file can be found in the
IMachine.getStateFilePath()
attribute.
fRemoveFile
- Whether to also remove the saved state file.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine not in state Saved. |
public DeviceActivity getDeviceActivity(DeviceType type)
E_INVALIDARG | Invalid device type. |
public void attachUSBDevice(java.lang.String id)
USBDeviceState.Busy
,
USBDeviceState.Available
or
USBDeviceState.Held
,
otherwise an error is immediately returned.
When the device state is
USBDeviceState.Busy
, an error may also
be returned if the host computer refuses to release it for some reason.
id
- UUID of the host USB device to attach.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine state neither Running nor Paused. |
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERROR | Virtual machine does not have a USB controller. |
IUSBController.getDeviceFilters()
,
USBDeviceState
public IUSBDevice detachUSBDevice(java.lang.String id)
id
- UUID of the USB device to detach.
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERROR | Virtual machine does not have a USB controller. |
E_INVALIDARG | USB device not attached to this virtual machine. |
IUSBController.getDeviceFilters()
,
USBDeviceState
public IUSBDevice findUSBDeviceByAddress(java.lang.String name)
name
- Address of the USB device (as assigned by the host) to
search for.
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | Given name does not correspond to any USB device. |
IUSBDevice.getAddress()
public IUSBDevice findUSBDeviceById(java.lang.String id)
id
- UUID of the USB device to search for.
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | Given id does not correspond to any USB device. |
IUSBDevice.getId()
public void createSharedFolder(java.lang.String name, java.lang.String hostPath, java.lang.Boolean writable, java.lang.Boolean automount)
ISharedFolder
to read more about logical names.
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 readonlyautomount
- Whether the share gets automatically mounted by the guest
or not.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine in Saved state or currently changing state. |
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Shared folder already exists or not accessible. |
public void removeSharedFolder(java.lang.String name)
createSharedFolder(String,String,Boolean,Boolean)
from the collection of
shared folders and stops sharing it.
name
- Logical name of the shared folder to remove.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine in Saved state or currently changing state. |
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Shared folder does not exists. |
public IProgress takeSnapshot(java.lang.String name, java.lang.String description)
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
IMachine.getCurrentSnapshot()
of the associated virtual machine and becomes a new current snapshot.
name
- Short name for the snapshot.description
- Optional description of the snapshot.
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine currently changing state. |
IMachine.saveSettings()
to
save all current machine settings before taking an offline snapshot.public IProgress deleteSnapshot(java.lang.String id)
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:
IMedium.getState()
) 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.IMachine.getState()
is
changed to "DeletingSnapshot", "DeletingSnapshotOnline" or
"DeletingSnapshotPaused" while this operation is in progress.
id
- UUID of the snapshot to delete.
@link ::VBOX_E_INVALID_VM_STATE 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. |
public IProgress deleteSnapshotAndAllChildren(java.lang.String id)
ISnapshot
for an introduction to
snapshots. The conditions and many details are the same as with
deleteSnapshot(String)
.
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.
id
- UUID of the snapshot to delete, including all its children.
@link ::VBOX_E_INVALID_VM_STATE 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. |
public IProgress deleteSnapshotRange(java.lang.String startId, java.lang.String endId)
deleteSnapshot(String)
. See
ISnapshot
for an introduction to snapshots. The
conditions and many details are the same as with
deleteSnapshot(String)
.
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.
startId
- UUID of the first snapshot to delete.endId
- UUID of the last snapshot to delete.
@link ::VBOX_E_INVALID_VM_STATE 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. |
public IProgress restoreSnapshot(ISnapshot snapshot)
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 MachineState.Saved
, so that the
next time it is powered on, the execution state will be restored
from the state of the snapshot.
snapshot
- The snapshot to restore the VM state from.
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine is running. |
MachineState.Saved
prior to this operation, the saved state file will be implicitly
deleted (as if discardSavedState(Boolean)
were
called).public IProgress teleport(java.lang.String hostname, java.lang.Long tcpport, java.lang.String password, java.lang.Long maxDowntime)
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.
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine not running or paused. |
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |