org.virtualbox_5_1
Class IConsole

java.lang.Object
  extended by org.virtualbox_5_1.IUnknown
      extended by org.virtualbox_5_1.IConsole

public class IConsole
extends IUnknown

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) usingIMachine.lockMachine(org.virtualbox_5_1.ISession,org.virtualbox_5_1.LockType)orIMachine.launchVMProcess(org.virtualbox_5_1.ISession,String,String). The console object can then be found in the session'sISession.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.

See Also:
Interface ID: {872DA645-4A9B-1727-BEE2-5585105B9EED}

Field Summary
 
Fields inherited from class org.virtualbox_5_1.IUnknown
obj, objMgr, port
 
Constructor Summary
IConsole(java.lang.String wrapped, org.virtualbox_5_1.ObjectRefManager objMgr, org.virtualbox_5_1.jaxws.VboxPortType port)
           
 
Method Summary
 void addDiskEncryptionPassword(java.lang.String id, java.lang.String password, java.lang.Boolean clearOnSuspend)
          Adds a password used for hard disk encryption/decryption.
 void addDiskEncryptionPasswords(java.util.List<java.lang.String> ids, java.util.List<java.lang.String> passwords, java.lang.Boolean clearOnSuspend)
          Adds a password used for hard disk encryption/decryption.
 void attachUSBDevice(java.lang.String id, java.lang.String captureFilename)
          Attaches a host USB device with the given UUID to the USB controller of the virtual machine.
 void clearAllDiskEncryptionPasswords()
          Clears all provided supplied disk encryption passwords.
 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.
 IUSBDevice detachUSBDevice(java.lang.String id)
          Detaches an USB device with the given UUID from the USB controller of the virtual machine.
 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.
 IMachineDebugger getDebugger()
          Debugging interface.
 java.util.List<DeviceActivity> getDeviceActivity(java.util.List<DeviceType> type)
          Gets the current activity type of given devices or device groups.
 IDisplay getDisplay()
          Virtual display object.
 IEmulatedUSB getEmulatedUSB()
          Interface that manages emulated USB devices.
 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).If the machine is powered off or aborted, the execution will start from the beginning (as if the real hardware were just powered on).
 IProgress powerUpPaused()
          Identical to powerUp except that the VM will enter theMachineState.Pausedstate, instead ofMachineState.Running.
static IConsole queryInterface(IUnknown obj)
           
 void removeDiskEncryptionPassword(java.lang.String id)
          Removes a password used for hard disk encryption/decryption from the running VM.
 void removeSharedFolder(java.lang.String name)
          Removes a transient shared folder with the given name previously created bycreateSharedFolder(String,String,Boolean,Boolean)from the collection of shared folders and stops sharing it.
 void reset()
          Resets the virtual machine.
 void resume()
          Resumes the virtual machine 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 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_5_1.IUnknown
getObjMgr, getRemoteWSPort, getWrapped, releaseRemote
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IConsole

public IConsole(java.lang.String wrapped,
                org.virtualbox_5_1.ObjectRefManager objMgr,
                org.virtualbox_5_1.jaxws.VboxPortType port)
Method Detail

getMachine

public IMachine getMachine()
Machine object for this console session. NOTE: This is a convenience property, it has the same value asISession.getMachine()of the corresponding session object.

Returns:
org.virtualbox_5_1.IMachine

getState

public MachineState getState()
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.

Returns:
org.virtualbox_5_1.MachineState

getGuest

public IGuest getGuest()
Guest object.

Returns:
org.virtualbox_5_1.IGuest

getKeyboard

public IKeyboard getKeyboard()
Virtual keyboard object. NOTE: If the machine is not running, any attempt to use the returned object will result in an error.

Returns:
org.virtualbox_5_1.IKeyboard

getMouse

public IMouse getMouse()
Virtual mouse object. NOTE: If the machine is not running, any attempt to use the returned object will result in an error.

Returns:
org.virtualbox_5_1.IMouse

getDisplay

public IDisplay getDisplay()
Virtual display object. NOTE: If the machine is not running, any attempt to use the returned object will result in an error.

Returns:
org.virtualbox_5_1.IDisplay

getDebugger

public IMachineDebugger getDebugger()
Debugging interface.

Returns:
org.virtualbox_5_1.IMachineDebugger

getUSBDevices

public java.util.List<IUSBDevice> getUSBDevices()
Collection of USB devices currently attached to the virtual USB controller. NOTE: The collection is empty if the machine is not running.

Returns:
List<org.virtualbox_5_1.IUSBDevice>

getRemoteUSBDevices

public java.util.List<IHostUSBDevice> getRemoteUSBDevices()
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.

Returns:
List<org.virtualbox_5_1.IHostUSBDevice>

getSharedFolders

public java.util.List<ISharedFolder> getSharedFolders()
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 toIMachine.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 usingcreateSharedFolder(String,String,Boolean,Boolean). Existing shared folders can be removed usingremoveSharedFolder(String).

Returns:
List<org.virtualbox_5_1.ISharedFolder>

getVRDEServerInfo

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

Returns:
org.virtualbox_5_1.IVRDEServerInfo

getEventSource

public IEventSource getEventSource()
Event source for console events.

Returns:
org.virtualbox_5_1.IEventSource

getAttachedPCIDevices

public java.util.List<IPCIDeviceAttachment> getAttachedPCIDevices()
Array of PCI devices attached to this machine.

Returns:
List<org.virtualbox_5_1.IPCIDeviceAttachment>

getUseHostClipboard

public 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. This setting may not affect existing guest clipboard connections which are already connected to the host clipboard.

Returns:
Boolean

setUseHostClipboard

public 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. This setting may not affect existing guest clipboard connections which are already connected to the host clipboard.

Parameters:
value - Boolean

getEmulatedUSB

public IEmulatedUSB getEmulatedUSB()
Interface that manages emulated USB devices.

Returns:
org.virtualbox_5_1.IEmulatedUSB

queryInterface

public static IConsole queryInterface(IUnknown obj)

powerUp

public IProgress powerUp()
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 theMachineState.Savedstate, it will continue its execution the point where the state has been saved. If the machineIMachine.getTeleporterEnabled()property is enabled on the machine being powered up, the machine will wait for an incoming teleportation in theMachineState.TeleportingInstate. 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 byIMachine.launchVMProcess(org.virtualbox_5_1.ISession,String,String)as well.

Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine already running.
@link ::VBOX_E_HOST_ERROR VBOX_E_HOST_ERRORHost interface does not exist or name not set.
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERRORInvalid 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), useIMachine.launchVMProcess(org.virtualbox_5_1.ISession,String,String)instead; these front-ends will power up the machine automatically for you.
See Also:
IMachine.saveState()

powerUpPaused

public IProgress powerUpPaused()
Identical to powerUp except that the VM will enter theMachineState.Pausedstate, instead ofMachineState.Running.

Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine already running.
@link ::VBOX_E_HOST_ERROR VBOX_E_HOST_ERRORHost interface does not exist or name not set.
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERRORInvalid saved state file.
See Also:
powerUp()

powerDown

public IProgress powerDown()
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.

Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine must be Running, Paused or Stuck to be powered down.

reset

public void reset()
Resets the virtual machine. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine not in Running state.
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERRORVirtual machine error in reset operation.


pause

public void pause()
Pauses the virtual machine execution. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine not in Running state.
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERRORVirtual machine error in suspend operation.


resume

public void resume()
Resumes the virtual machine execution. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine not in Paused state.
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERRORVirtual machine error in resume operation.


powerButton

public void powerButton()
Sends the ACPI power button event to the guest. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine not in Running state.
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERRORControlled power off failed.


sleepButton

public void sleepButton()
Sends the ACPI sleep button event to the guest. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine not in Running state.
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERRORSending sleep button event failed.


getPowerButtonHandled

public java.lang.Boolean getPowerButtonHandled()
Checks if the last power button event was handled by guest. Expected result codes:
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERRORChecking if the event was handled by the guest OS failed.


getGuestEnteredACPIMode

public java.lang.Boolean getGuestEnteredACPIMode()
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:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine not in Running state.


getDeviceActivity

public java.util.List<DeviceActivity> getDeviceActivity(java.util.List<DeviceType> type)
Gets the current activity type of given devices or device groups. Expected result codes:
E_INVALIDARGInvalid device type.


attachUSBDevice

public void attachUSBDevice(java.lang.String id,
                            java.lang.String captureFilename)
Attaches a host USB device with the given UUID to the USB controller of the virtual machine. The device needs to be in one of the following states:USBDeviceState.Busy,USBDeviceState.AvailableorUSBDeviceState.Held, otherwise an error is immediately returned. When the device state isUSBDeviceState.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.
captureFilename - Filename to capture the USB traffic to. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine state neither Running nor Paused.
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERRORVirtual machine does not have a USB controller.
See Also:
IUSBDeviceFilters.getDeviceFilters(), USBDeviceState

detachUSBDevice

public IUSBDevice detachUSBDevice(java.lang.String id)
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.
Returns:
Detached USB device. Expected result codes:
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERRORVirtual machine does not have a USB controller.
E_INVALIDARGUSB device not attached to this virtual machine.
See Also:
IUSBDeviceFilters.getDeviceFilters(), USBDeviceState

findUSBDeviceByAddress

public IUSBDevice findUSBDeviceByAddress(java.lang.String name)
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.
Returns:
Found USB device object. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDGiven name does not correspond to any USB device.
See Also:
IUSBDevice.getAddress()

findUSBDeviceById

public IUSBDevice findUSBDeviceById(java.lang.String id)
Searches for a USB device with the given UUID.

Parameters:
id - UUID of the USB device to search for.
Returns:
Found USB device object. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDGiven id does not correspond to any USB device.
See Also:
IUSBDevice.getId()

createSharedFolder

public 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. Refer to the description ofISharedFolderto 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:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine in Saved state or currently changing state.
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERRORShared folder already exists or not accessible.

removeSharedFolder

public void removeSharedFolder(java.lang.String name)
Removes a transient shared folder with the given name previously created bycreateSharedFolder(String,String,Boolean,Boolean)from the collection of shared folders and stops sharing it.

Parameters:
name - Logical name of the shared folder to remove. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine in Saved state or currently changing state.
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERRORShared folder does not exists.

teleport

public 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. 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.
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATEVirtual machine not running or paused.
NOTE: The current implementation treats this a guideline, not as an absolute rule.

addDiskEncryptionPassword

public void addDiskEncryptionPassword(java.lang.String id,
                                      java.lang.String password,
                                      java.lang.Boolean clearOnSuspend)
Adds a password used for hard disk encryption/decryption.

Parameters:
id - The identifier used for the password. Must match the identifier used when the encrypted medium was created.
password - The password.
clearOnSuspend - Flag whether to clear the password on VM suspend (due to a suspending host for example). The password must be supplied again before the VM can resume. Expected result codes:
@link ::VBOX_E_PASSWORD_INCORRECT VBOX_E_PASSWORD_INCORRECTThe password provided wasn't correct for at least one disk using the provided ID.

addDiskEncryptionPasswords

public void addDiskEncryptionPasswords(java.util.List<java.lang.String> ids,
                                       java.util.List<java.lang.String> passwords,
                                       java.lang.Boolean clearOnSuspend)
Adds a password used for hard disk encryption/decryption.

Parameters:
ids - List of identifiers for the passwords. Must match the identifier used when the encrypted medium was created.
passwords - List of passwords.
clearOnSuspend - Flag whether to clear the given passwords on VM suspend (due to a suspending host for example). The passwords must be supplied again before the VM can resume. Expected result codes:
@link ::VBOX_E_PASSWORD_INCORRECT VBOX_E_PASSWORD_INCORRECTThe password provided wasn't correct for at least one disk using the provided ID.

removeDiskEncryptionPassword

public void removeDiskEncryptionPassword(java.lang.String id)
Removes a password used for hard disk encryption/decryption from the running VM. As soon as the medium requiring this password is accessed the VM is paused with an error and the password must be provided again.

Parameters:
id - The identifier used for the password. Must match the identifier used when the encrypted medium was created.

clearAllDiskEncryptionPasswords

public void clearAllDiskEncryptionPasswords()
Clears all provided supplied disk encryption passwords.