|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.virtualbox_5_0.IUnknown
org.virtualbox_5_0.IMachine
public class IMachine
The IMachine interface represents a virtual machine, or guest, created
in VirtualBox.
This interface is used in two contexts. First of all, a collection of
objects implementing this interface is stored in theIVirtualBox.getMachines()
attribute which lists all the virtual
machines that are currently registered with this VirtualBox
installation. Also, once a session has been opened for the given virtual
machine (e.g. the virtual machine is running), the machine object
associated with the open session can be queried from the session object;
seeISession
for details.
The main role of this interface is to expose the settings of the virtual
machine and provide methods to change various aspects of the virtual
machine's configuration. For machine objects stored in theIVirtualBox.getMachines()
collection, all attributes are
read-only unless explicitly stated otherwise in individual attribute
and method descriptions.
In order to change a machine setting, a session for this machine must be
opened using one of thelockMachine(org.virtualbox_5_0.ISession,org.virtualbox_5_0.LockType)
orlaunchVMProcess(org.virtualbox_5_0.ISession,String,String)
methods. After the
machine has been successfully locked for a session, a mutable machine object
needs to be queried from the session object and then the desired settings
changes can be applied to the returned object using IMachine attributes and
methods. See theISession
interface description for more
information about sessions.
Note that IMachine does not provide methods to control virtual machine
execution (such as start the machine, or power it down) -- these methods
are grouped in a separate interface calledIConsole
.
ISession
,
Interface ID: {F30138D4-E5EA-4B3A-8858-A059DE4C93FD}
Field Summary |
---|
Fields inherited from class org.virtualbox_5_0.IUnknown |
---|
obj, objMgr, port |
Constructor Summary | |
---|---|
IMachine(java.lang.String wrapped,
org.virtualbox_5_0.ObjectRefManager objMgr,
org.virtualbox_5_0.jaxws.VboxPortType port)
|
Method Summary | |
---|---|
IStorageController |
addStorageController(java.lang.String name,
StorageBus connectionType)
Adds a new storage controller (SCSI, SAS or SATA controller) to the machine and returns it as an instance of IStorageController . |
IUSBController |
addUSBController(java.lang.String name,
USBControllerType type)
Adds a new USB controller to the machine and returns it as an instance of IUSBController . |
void |
adoptSavedState(java.lang.String savedStateFile)
Associates the given saved state file to the virtual machine. |
void |
applyDefaults(java.lang.String flags)
Applies the defaults for the configured guest OS type. |
void |
attachDevice(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
DeviceType type,
IMedium medium)
Attaches a device and optionally mounts a medium to the given storage controller ( IStorageController , identified by name),
at the indicated port and device. |
void |
attachDeviceWithoutMedium(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
DeviceType type)
Attaches a device and optionally mounts a medium to the given storage controller ( IStorageController , identified by name),
at the indicated port and device. |
void |
attachHostPCIDevice(java.lang.Integer hostAddress,
java.lang.Integer desiredGuestAddress,
java.lang.Boolean tryToUnbind)
Attaches host PCI device with the given (host) PCI address to the PCI bus of the virtual machine. |
java.lang.Boolean |
canShowConsoleWindow()
Returns true if the VM console process can activate the console window and bring it to foreground on the desktop of the host PC. |
IProgress |
cloneTo(IMachine target,
CloneMode mode,
java.util.List<CloneOptions> options)
Creates a clone of this machine, either as a full clone (which means creating independent copies of the hard disk media, save states and so on), or as a linked clone (which uses its own differencing media, sharing the parent media with the source machine). |
void |
createSharedFolder(java.lang.String name,
java.lang.String hostPath,
java.lang.Boolean writable,
java.lang.Boolean automount)
Creates a new permanent 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 |
deleteConfig(java.util.List<IMedium> media)
Deletes the files associated with this machine from disk. |
void |
deleteGuestProperty(java.lang.String name)
Deletes an entry from the machine's guest property store. |
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. |
void |
detachDevice(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device)
Detaches the device attached to a device slot of the specified bus. |
void |
detachHostPCIDevice(java.lang.Integer hostAddress)
Detach host PCI device from 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() ). |
void |
discardSettings()
Discards any changes to the machine settings made since the session has been opened or since the last call to saveSettings() ordiscardSettings() . |
void |
enumerateGuestProperties(java.lang.String patterns,
Holder<java.util.List<java.lang.String>> names,
Holder<java.util.List<java.lang.String>> values,
Holder<java.util.List<java.lang.Long>> timestamps,
Holder<java.util.List<java.lang.String>> flags)
Return a list of the guest properties matching a set of patterns along with their values, time stamps and flags. |
IVirtualSystemDescription |
exportTo(IAppliance appliance,
java.lang.String location)
Exports the machine to an OVF appliance. |
ISnapshot |
findSnapshot(java.lang.String nameOrId)
Returns a snapshot of this machine with the given name or UUID. |
java.lang.Boolean |
getAccelerate2DVideoEnabled()
This setting determines whether VirtualBox allows this machine to make use of the 2D video acceleration support available on the host. |
java.lang.Boolean |
getAccelerate3DEnabled()
This setting determines whether VirtualBox allows this machine to make use of the 3D graphics support available on the host. |
IVirtualBoxErrorInfo |
getAccessError()
Error information describing the reason of machine inaccessibility. |
java.lang.Boolean |
getAccessible()
Whether this virtual machine is currently accessible or not. |
java.lang.Boolean |
getAllowTracingToAccessVM()
Enables tracepoints in PDM devices and drivers to use the VMCPU or VM structures when firing off trace points. |
IAudioAdapter |
getAudioAdapter()
Associated audio adapter, always present. |
java.lang.Long |
getAutostartDelay()
Number of seconds to wait until the VM should be started during system boot. |
java.lang.Boolean |
getAutostartEnabled()
Enables autostart of the VM during system boot. |
AutostopType |
getAutostopType()
Action type to do when the system is shutting down. |
IBandwidthControl |
getBandwidthControl()
Bandwidth control manager. |
IBIOSSettings |
getBIOSSettings()
Object containing all BIOS settings. |
DeviceType |
getBootOrder(java.lang.Long position)
Returns the device type that occupies the specified position in the boot order. |
ChipsetType |
getChipsetType()
Chipset type used in this VM. |
ClipboardMode |
getClipboardMode()
Synchronization mode between the host OS clipboard and the guest OS clipboard. |
java.lang.Long |
getCPUCount()
Number of virtual CPUs in the VM. |
java.lang.Long |
getCPUExecutionCap()
Means to limit the number of CPU cycles a guest can use. |
java.lang.Boolean |
getCPUHotPlugEnabled()
This setting determines whether VirtualBox allows CPU hotplugging for this machine. |
void |
getCPUIDLeaf(java.lang.Long id,
Holder<java.lang.Long> valEax,
Holder<java.lang.Long> valEbx,
Holder<java.lang.Long> valEcx,
Holder<java.lang.Long> valEdx)
Returns the virtual CPU cpuid information for the specified leaf. |
java.lang.Long |
getCPUIDPortabilityLevel()
Virtual CPUID portability level, the higher number the fewer newer or vendor specific CPU feature is reported to the guest (via the CPUID instruction). |
java.lang.Boolean |
getCPUProperty(CPUPropertyType property)
Returns the virtual CPU boolean value of the specified property. |
java.lang.Boolean |
getCPUStatus(java.lang.Long cpu)
Returns the current status of the given CPU. |
ISnapshot |
getCurrentSnapshot()
Current snapshot of this machine. |
java.lang.Boolean |
getCurrentStateModified()
Returns true if the current state of the machine is not identical to the state stored in the current snapshot. |
java.lang.String |
getDefaultFrontend()
Selects which VM frontend should be used by default when launching this VM through the launchVMProcess(org.virtualbox_5_0.ISession,String,String) method. |
java.lang.String |
getDescription()
Description of the virtual machine. |
DnDMode |
getDnDMode()
Sets or retrieves the current drag'n drop mode. |
ParavirtProvider |
getEffectiveParavirtProvider()
Returns the effective paravirtualization provider for this VM. |
java.lang.Boolean |
getEmulatedUSBCardReaderEnabled()
|
java.lang.String |
getExtraData(java.lang.String key)
Returns associated machine-specific extra data. |
java.util.List<java.lang.String> |
getExtraDataKeys()
Returns an array representing the machine-specific extra data keys which currently have values defined. |
java.lang.String |
getFaultToleranceAddress()
The address the fault tolerance source or target. |
java.lang.String |
getFaultTolerancePassword()
The password to check for on the standby VM. |
java.lang.Long |
getFaultTolerancePort()
The TCP port the fault tolerance source or target will use for communication. |
FaultToleranceState |
getFaultToleranceState()
Fault tolerance state; disabled, source or target. |
java.lang.Long |
getFaultToleranceSyncInterval()
The interval in ms used for syncing the state between source and target. |
FirmwareType |
getFirmwareType()
Type of firmware (such as legacy BIOS or EFI), used for initial bootstrap in this VM. |
GraphicsControllerType |
getGraphicsControllerType()
Graphics controller type. |
java.util.List<java.lang.String> |
getGroups()
Array of machine group names of which this machine is a member.""and"/"are synonyms for the toplevel group. |
void |
getGuestProperty(java.lang.String name,
Holder<java.lang.String> value,
Holder<java.lang.Long> timestamp,
Holder<java.lang.String> flags)
Reads an entry from the machine's guest property store. |
java.lang.Long |
getGuestPropertyTimestamp(java.lang.String property)
Reads a property timestamp from the machine's guest property store. |
java.lang.String |
getGuestPropertyValue(java.lang.String property)
Reads a value from the machine's guest property store. |
java.lang.String |
getHardwareUUID()
The UUID presented to the guest via memory tables, hardware and guest properties. |
java.lang.String |
getHardwareVersion()
Hardware version identifier. |
java.lang.Boolean |
getHPETEnabled()
This attribute controls if High Precision Event Timer (HPET) is enabled in this VM. |
java.lang.Boolean |
getHWVirtExProperty(HWVirtExPropertyType property)
Returns the value of the specified hardware virtualization boolean property. |
byte[] |
getIcon()
Overridden VM Icon details. |
java.lang.String |
getId()
UUID of the virtual machine. |
java.lang.Boolean |
getIOCacheEnabled()
When set to true, the builtin I/O cache of the virtual machine will be enabled. |
java.lang.Long |
getIOCacheSize()
Maximum size of the I/O cache in MB. |
KeyboardHIDType |
getKeyboardHIDType()
Type of keyboard HID used in this VM. |
java.lang.Long |
getLastStateChange()
Time stamp of the last execution state change, in milliseconds since 1970-01-01 UTC. |
java.lang.String |
getLogFolder()
Full path to the folder that stores a set of rotated log files recorded during machine execution. |
IMedium |
getMedium(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device)
Returns the virtual medium attached to a device slot of the specified bus. |
IMediumAttachment |
getMediumAttachment(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device)
Returns a medium attachment which corresponds to the controller with the given name, on the given port and device slot. |
java.util.List<IMediumAttachment> |
getMediumAttachments()
Array of media attached to this machine. |
java.util.List<IMediumAttachment> |
getMediumAttachmentsOfController(java.lang.String name)
Returns an array of medium attachments which are attached to the the controller with the given name. |
java.lang.Long |
getMemoryBalloonSize()
Memory balloon size in megabytes. |
java.lang.Long |
getMemorySize()
System memory size in megabytes. |
java.lang.Long |
getMonitorCount()
Number of virtual monitors. |
java.lang.String |
getName()
Name of the virtual machine. |
INetworkAdapter |
getNetworkAdapter(java.lang.Long slot)
Returns the network adapter associated with the given slot. |
java.lang.String |
getOSTypeId()
User-defined identifier of the Guest OS type. |
java.lang.Boolean |
getPageFusionEnabled()
This setting determines whether VirtualBox allows page fusion for this machine (64-bit hosts only). |
IParallelPort |
getParallelPort(java.lang.Long slot)
Returns the parallel port associated with the given slot. |
ParavirtProvider |
getParavirtProvider()
The paravirtualized guest interface provider. |
IVirtualBox |
getParent()
Associated parent object. |
java.util.List<IPCIDeviceAttachment> |
getPCIDeviceAssignments()
Array of PCI devices assigned to this machine, to get list of all PCI devices attached to the machine use IConsole.getAttachedPCIDevices() attribute, as this attribute
is intended to list only devices additional to what described in
virtual hardware config. |
PointingHIDType |
getPointingHIDType()
Type of pointing HID (such as mouse or tablet) used in this VM. |
java.lang.Boolean |
getRTCUseUTC()
When set to true, the RTC device of the virtual machine will run in UTC time, otherwise in local time. |
ISerialPort |
getSerialPort(java.lang.Long slot)
Returns the serial port associated with the given slot. |
java.lang.String |
getSessionName()
Name of the session. |
java.lang.Long |
getSessionPID()
Identifier of the session process. |
SessionState |
getSessionState()
Current session state for this machine. |
java.lang.String |
getSettingsFilePath()
Full name of the file containing machine settings data. |
java.lang.Boolean |
getSettingsModified()
Whether the settings of this machine have been modified (but neither yet saved nor discarded). |
java.util.List<ISharedFolder> |
getSharedFolders()
Collection of shared folders for this machine (permanent shared folders). |
java.lang.Long |
getSnapshotCount()
Number of snapshots taken on this machine. |
java.lang.String |
getSnapshotFolder()
Full path to the directory used to store snapshot data (differencing media and saved state files) of this machine. |
MachineState |
getState()
Current execution state of this machine. |
java.lang.String |
getStateFilePath()
Full path to the file that stores the execution state of the machine when it is in the MachineState.Saved state. |
IStorageController |
getStorageControllerByInstance(StorageBus connectionType,
java.lang.Long instance)
Returns a storage controller of a specific storage bus with the given instance number. |
IStorageController |
getStorageControllerByName(java.lang.String name)
Returns a storage controller with the given name. |
java.util.List<IStorageController> |
getStorageControllers()
Array of storage controllers attached to this machine. |
java.lang.String |
getTeleporterAddress()
The address the target teleporter will listen on. |
java.lang.Boolean |
getTeleporterEnabled()
When set to true, the virtual machine becomes a target teleporter the next time it is powered on. |
java.lang.String |
getTeleporterPassword()
The password to check for on the target teleporter. |
java.lang.Long |
getTeleporterPort()
The TCP port the target teleporter will listen for incoming teleportations on. |
java.lang.String |
getTracingConfig()
Tracepoint configuration to apply at startup when getTracingEnabled() is true. |
java.lang.Boolean |
getTracingEnabled()
Enables the tracing facility in the VMM (including PDM devices + drivers). |
IUSBController |
getUSBControllerByName(java.lang.String name)
Returns a USB controller with the given type. |
java.lang.Long |
getUSBControllerCountByType(USBControllerType type)
Returns the number of USB controllers of the given type attached to the VM. |
java.util.List<IUSBController> |
getUSBControllers()
Array of USB controllers attached to this machine. |
IUSBDeviceFilters |
getUSBDeviceFilters()
Associated USB device filters object. |
java.lang.Boolean |
getUSBProxyAvailable()
Returns whether there is an USB proxy available. |
java.lang.Boolean |
getVideoCaptureEnabled()
This setting determines whether VirtualBox uses video recording to record VM session. |
java.lang.String |
getVideoCaptureFile()
This setting determines the filename VirtualBox uses to save the recorded content. |
java.lang.Long |
getVideoCaptureFPS()
This setting determines the maximum number of frames per second. |
java.lang.Long |
getVideoCaptureHeight()
This setting determines the vertical resolution of the recorded video. |
java.lang.Long |
getVideoCaptureMaxFileSize()
This setting determines the maximal number of captured video file size in MB. |
java.lang.Long |
getVideoCaptureMaxTime()
This setting determines the maximum amount of time in milliseconds the video capture will work for. |
java.lang.String |
getVideoCaptureOptions()
This setting contains any additional video capture options required in comma-separated key=value format. |
java.lang.Long |
getVideoCaptureRate()
This setting determines the bitrate in kilobits per second. |
java.util.List<java.lang.Boolean> |
getVideoCaptureScreens()
This setting determines for which screens video recording is enabled. |
java.lang.Long |
getVideoCaptureWidth()
This setting determines the horizontal resolution of the recorded video. |
java.lang.String |
getVMProcessPriority()
Sets the priority of the VM process. |
java.lang.Long |
getVRAMSize()
Video memory size in megabytes. |
IVRDEServer |
getVRDEServer()
VirtualBox Remote Desktop Extension (VRDE) server object. |
void |
hotPlugCPU(java.lang.Long cpu)
Plugs a CPU into the machine. |
void |
hotUnplugCPU(java.lang.Long cpu)
Removes a CPU from the machine. |
IProgress |
launchVMProcess(ISession session,
java.lang.String name,
java.lang.String environment)
Spawns a new process that will execute the virtual machine and obtains a shared lock on the machine for the calling session. |
void |
lockMachine(ISession session,
LockType lockType)
Locks the machine for the given session to enable the caller to make changes to the machine or start the VM or control VM execution. |
void |
mountMedium(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
IMedium medium,
java.lang.Boolean force)
Mounts a medium ( IMedium , identified
by the given UUID id) to the given storage controller
(IStorageController , identified by name),
at the indicated port and device. |
void |
nonRotationalDevice(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
java.lang.Boolean nonRotational)
Sets a flag in the device information which indicates that the medium is not based on rotational technology, i.e. |
void |
passthroughDevice(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
java.lang.Boolean passthrough)
Sets the passthrough mode of an existing DVD device. |
static IMachine |
queryInterface(IUnknown obj)
|
java.lang.String |
queryLogFilename(java.lang.Long idx)
Queries for the VM log file name of an given index. |
void |
querySavedGuestScreenInfo(java.lang.Long screenId,
Holder<java.lang.Long> originX,
Holder<java.lang.Long> originY,
Holder<java.lang.Long> width,
Holder<java.lang.Long> height,
Holder<java.lang.Boolean> enabled)
Returns the guest dimensions from the saved state. |
java.util.List<BitmapFormat> |
querySavedScreenshotInfo(java.lang.Long screenId,
Holder<java.lang.Long> width,
Holder<java.lang.Long> height)
Returns available formats and size of the screenshot from saved state. |
byte[] |
readLog(java.lang.Long idx,
java.lang.Long offset,
java.lang.Long size)
Reads the VM log file. |
byte[] |
readSavedScreenshotToArray(java.lang.Long screenId,
BitmapFormat bitmapFormat,
Holder<java.lang.Long> width,
Holder<java.lang.Long> height)
Screenshot in requested format is retrieved to an array of bytes. |
byte[] |
readSavedThumbnailToArray(java.lang.Long screenId,
BitmapFormat bitmapFormat,
Holder<java.lang.Long> width,
Holder<java.lang.Long> height)
Thumbnail is retrieved to an array of bytes in the requested format. |
void |
removeAllCPUIDLeaves()
Removes all the virtual CPU cpuid leaves |
void |
removeCPUIDLeaf(java.lang.Long id)
Removes the virtual CPU cpuid leaf for the specified index |
void |
removeSharedFolder(java.lang.String name)
Removes the permanent 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 |
removeStorageController(java.lang.String name)
Removes a storage controller from the machine with all devices attached to it. |
void |
removeUSBController(java.lang.String name)
Removes a USB controller from the machine. |
IProgress |
restoreSnapshot(ISnapshot snapshot)
Starts resetting the machine's current state to the state contained in the given snapshot, asynchronously. |
void |
saveSettings()
Saves any changes to machine settings made since the session has been opened or a new machine has been created, or since the last call to saveSettings() ordiscardSettings() . |
IProgress |
saveState()
Saves the current execution state of a running virtual machine and stops its execution. |
void |
setAccelerate2DVideoEnabled(java.lang.Boolean value)
This setting determines whether VirtualBox allows this machine to make use of the 2D video acceleration support available on the host. |
void |
setAccelerate3DEnabled(java.lang.Boolean value)
This setting determines whether VirtualBox allows this machine to make use of the 3D graphics support available on the host. |
void |
setAllowTracingToAccessVM(java.lang.Boolean value)
Enables tracepoints in PDM devices and drivers to use the VMCPU or VM structures when firing off trace points. |
void |
setAutoDiscardForDevice(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
java.lang.Boolean discard)
Sets a flag in the device information which indicates that the medium supports discarding unused blocks (called trimming for SATA or unmap for SCSI devices) .This may or may not be supported by a particular drive, and is silently ignored in the latter case. |
void |
setAutostartDelay(java.lang.Long value)
Number of seconds to wait until the VM should be started during system boot. |
void |
setAutostartEnabled(java.lang.Boolean value)
Enables autostart of the VM during system boot. |
void |
setAutostopType(AutostopType value)
Action type to do when the system is shutting down. |
void |
setBandwidthGroupForDevice(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
IBandwidthGroup bandwidthGroup)
Sets the bandwidth group of an existing storage device. |
void |
setBootOrder(java.lang.Long position,
DeviceType device)
Puts the given device to the specified position in the boot order. |
void |
setChipsetType(ChipsetType value)
Chipset type used in this VM. |
void |
setClipboardMode(ClipboardMode value)
Synchronization mode between the host OS clipboard and the guest OS clipboard. |
void |
setCPUCount(java.lang.Long value)
Number of virtual CPUs in the VM. |
void |
setCPUExecutionCap(java.lang.Long value)
Means to limit the number of CPU cycles a guest can use. |
void |
setCPUHotPlugEnabled(java.lang.Boolean value)
This setting determines whether VirtualBox allows CPU hotplugging for this machine. |
void |
setCPUIDLeaf(java.lang.Long id,
java.lang.Long valEax,
java.lang.Long valEbx,
java.lang.Long valEcx,
java.lang.Long valEdx)
Sets the virtual CPU cpuid information for the specified leaf. |
void |
setCPUIDPortabilityLevel(java.lang.Long value)
Virtual CPUID portability level, the higher number the fewer newer or vendor specific CPU feature is reported to the guest (via the CPUID instruction). |
void |
setCPUProperty(CPUPropertyType property,
java.lang.Boolean value)
Sets the virtual CPU boolean value of the specified property. |
void |
setDefaultFrontend(java.lang.String value)
Selects which VM frontend should be used by default when launching this VM through the launchVMProcess(org.virtualbox_5_0.ISession,String,String) method. |
void |
setDescription(java.lang.String value)
Description of the virtual machine. |
void |
setDnDMode(DnDMode value)
Sets or retrieves the current drag'n drop mode. |
void |
setEmulatedUSBCardReaderEnabled(java.lang.Boolean value)
|
void |
setExtraData(java.lang.String key,
java.lang.String value)
Sets associated machine-specific extra data. |
void |
setFaultToleranceAddress(java.lang.String value)
The address the fault tolerance source or target. |
void |
setFaultTolerancePassword(java.lang.String value)
The password to check for on the standby VM. |
void |
setFaultTolerancePort(java.lang.Long value)
The TCP port the fault tolerance source or target will use for communication. |
void |
setFaultToleranceState(FaultToleranceState value)
Fault tolerance state; disabled, source or target. |
void |
setFaultToleranceSyncInterval(java.lang.Long value)
The interval in ms used for syncing the state between source and target. |
void |
setFirmwareType(FirmwareType value)
Type of firmware (such as legacy BIOS or EFI), used for initial bootstrap in this VM. |
void |
setGraphicsControllerType(GraphicsControllerType value)
Graphics controller type. |
void |
setGroups(java.util.List<java.lang.String> value)
Array of machine group names of which this machine is a member.""and"/"are synonyms for the toplevel group. |
void |
setGuestProperty(java.lang.String property,
java.lang.String value,
java.lang.String flags)
Sets, changes or deletes an entry in the machine's guest property store. |
void |
setGuestPropertyValue(java.lang.String property,
java.lang.String value)
Sets or changes a value in the machine's guest property store. |
void |
setHardwareUUID(java.lang.String value)
The UUID presented to the guest via memory tables, hardware and guest properties. |
void |
setHardwareVersion(java.lang.String value)
Hardware version identifier. |
void |
setHotPluggableForDevice(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
java.lang.Boolean hotPluggable)
Sets a flag in the device information which indicates that the attached device is hot pluggable or not. |
void |
setHPETEnabled(java.lang.Boolean value)
This attribute controls if High Precision Event Timer (HPET) is enabled in this VM. |
void |
setHWVirtExProperty(HWVirtExPropertyType property,
java.lang.Boolean value)
Sets a new value for the specified hardware virtualization boolean property. |
void |
setIcon(byte[] value)
Overridden VM Icon details. |
void |
setIOCacheEnabled(java.lang.Boolean value)
When set to true, the builtin I/O cache of the virtual machine will be enabled. |
void |
setIOCacheSize(java.lang.Long value)
Maximum size of the I/O cache in MB. |
void |
setKeyboardHIDType(KeyboardHIDType value)
Type of keyboard HID used in this VM. |
void |
setMemoryBalloonSize(java.lang.Long value)
Memory balloon size in megabytes. |
void |
setMemorySize(java.lang.Long value)
System memory size in megabytes. |
void |
setMonitorCount(java.lang.Long value)
Number of virtual monitors. |
void |
setName(java.lang.String value)
Name of the virtual machine. |
void |
setNoBandwidthGroupForDevice(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device)
Sets no bandwidth group for an existing storage device. |
void |
setOSTypeId(java.lang.String value)
User-defined identifier of the Guest OS type. |
void |
setPageFusionEnabled(java.lang.Boolean value)
This setting determines whether VirtualBox allows page fusion for this machine (64-bit hosts only). |
void |
setParavirtProvider(ParavirtProvider value)
The paravirtualized guest interface provider. |
void |
setPointingHIDType(PointingHIDType value)
Type of pointing HID (such as mouse or tablet) used in this VM. |
void |
setRTCUseUTC(java.lang.Boolean value)
When set to true, the RTC device of the virtual machine will run in UTC time, otherwise in local time. |
IProgress |
setSettingsFilePath(java.lang.String settingsFilePath)
Currently, it is an error to change this property on any machine. |
void |
setSnapshotFolder(java.lang.String value)
Full path to the directory used to store snapshot data (differencing media and saved state files) of this machine. |
void |
setStorageControllerBootable(java.lang.String name,
java.lang.Boolean bootable)
Sets the bootable flag of the storage controller with the given name. |
void |
setTeleporterAddress(java.lang.String value)
The address the target teleporter will listen on. |
void |
setTeleporterEnabled(java.lang.Boolean value)
When set to true, the virtual machine becomes a target teleporter the next time it is powered on. |
void |
setTeleporterPassword(java.lang.String value)
The password to check for on the target teleporter. |
void |
setTeleporterPort(java.lang.Long value)
The TCP port the target teleporter will listen for incoming teleportations on. |
void |
setTracingConfig(java.lang.String value)
Tracepoint configuration to apply at startup when getTracingEnabled() is true. |
void |
setTracingEnabled(java.lang.Boolean value)
Enables the tracing facility in the VMM (including PDM devices + drivers). |
void |
setVideoCaptureEnabled(java.lang.Boolean value)
This setting determines whether VirtualBox uses video recording to record VM session. |
void |
setVideoCaptureFile(java.lang.String value)
This setting determines the filename VirtualBox uses to save the recorded content. |
void |
setVideoCaptureFPS(java.lang.Long value)
This setting determines the maximum number of frames per second. |
void |
setVideoCaptureHeight(java.lang.Long value)
This setting determines the vertical resolution of the recorded video. |
void |
setVideoCaptureMaxFileSize(java.lang.Long value)
This setting determines the maximal number of captured video file size in MB. |
void |
setVideoCaptureMaxTime(java.lang.Long value)
This setting determines the maximum amount of time in milliseconds the video capture will work for. |
void |
setVideoCaptureOptions(java.lang.String value)
This setting contains any additional video capture options required in comma-separated key=value format. |
void |
setVideoCaptureRate(java.lang.Long value)
This setting determines the bitrate in kilobits per second. |
void |
setVideoCaptureScreens(java.util.List<java.lang.Boolean> value)
This setting determines for which screens video recording is enabled. |
void |
setVideoCaptureWidth(java.lang.Long value)
This setting determines the horizontal resolution of the recorded video. |
void |
setVMProcessPriority(java.lang.String value)
Sets the priority of the VM process. |
void |
setVRAMSize(java.lang.Long value)
Video memory size in megabytes. |
java.lang.Long |
showConsoleWindow()
Activates the console window and brings it to foreground on the desktop of the host PC. |
IProgress |
takeSnapshot(java.lang.String name,
java.lang.String description,
java.lang.Boolean pause,
Holder<java.lang.String> id)
Saves the current execution state and all settings of the machine and creates differencing images for all normal (non-independent) media. |
void |
temporaryEjectDevice(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
java.lang.Boolean temporaryEject)
Sets the behavior for guest-triggered medium eject. |
void |
unmountMedium(java.lang.String name,
java.lang.Integer controllerPort,
java.lang.Integer device,
java.lang.Boolean force)
Unmounts any currently mounted medium ( IMedium ,
identified by the given UUID id) to the given storage controller
(IStorageController , identified by name),
at the indicated port and device. |
java.util.List<IMedium> |
unregister(CleanupMode cleanupMode)
Unregisters a machine previously registered with IVirtualBox.registerMachine(org.virtualbox_5_0.IMachine) and optionally do additional
cleanup before the machine is unregistered. |
Methods inherited from class org.virtualbox_5_0.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 |
---|
public IMachine(java.lang.String wrapped, org.virtualbox_5_0.ObjectRefManager objMgr, org.virtualbox_5_0.jaxws.VboxPortType port)
Method Detail |
---|
public IVirtualBox getParent()
public byte[] getIcon()
public void setIcon(byte[] value)
value
- byte[]public java.lang.Boolean getAccessible()
getAccessError()
property may be used to get the
detailed error information describing the reason of
inaccessibility, including XML error messages.
When the machine is inaccessible, only the following properties
can be used on it:An attempt to access any other property or method will return
an error.
The only possible action you can perform on an inaccessible
machine is to unregister it using theunregister(org.virtualbox_5_0.CleanupMode)
call (or, to check
for the accessibility state once more by querying this
property).
NOTE: In the current implementation, once this property returns
true, the machine will never become inaccessible
later, even if its settings file cannot be successfully
read/written any more (at least, until the VirtualBox
server is restarted). This limitation may be removed in
future releases.
public IVirtualBoxErrorInfo getAccessError()
getAccessible()
returned false (i.e. the
machine is currently inaccessible). Otherwise, a null
IVirtualBoxErrorInfo object will be returned.
public java.lang.String getName()
saveSettings()
to confirm the
change. The containing subdirectory will be also renamed, but
only if it has exactly the same name as the settings file
itself prior to changing this property (for backward compatibility
with previous API releases). The above implies the following
limitations:saveSettings()
is called.saveSettings()
will return an appropriate error message explaining the exact
reason and the changes you made to this machine will not be saved.
Starting with VirtualBox 4.0, a ".vbox" extension of the settings
file is recommended, but not enforced. (Previous versions always
used a generic ".xml" extension.)
public void setName(java.lang.String value)
saveSettings()
to confirm the
change. The containing subdirectory will be also renamed, but
only if it has exactly the same name as the settings file
itself prior to changing this property (for backward compatibility
with previous API releases). The above implies the following
limitations:saveSettings()
is called.saveSettings()
will return an appropriate error message explaining the exact
reason and the changes you made to this machine will not be saved.
Starting with VirtualBox 4.0, a ".vbox" extension of the settings
file is recommended, but not enforced. (Previous versions always
used a generic ".xml" extension.)
value
- Stringpublic java.lang.String getDescription()
public void setDescription(java.lang.String value)
value
- Stringpublic java.lang.String getId()
public java.util.List<java.lang.String> getGroups()
public void setGroups(java.util.List<java.lang.String> value)
value
- List<String>public java.lang.String getOSTypeId()
IVirtualBox.getGuestOSType(String)
to obtain
an IGuestOSType object representing details about the given
Guest OS type.
NOTE: This value may differ from the value returned byIGuest.getOSTypeId()
if Guest Additions are
installed to the guest OS.
public void setOSTypeId(java.lang.String value)
IVirtualBox.getGuestOSType(String)
to obtain
an IGuestOSType object representing details about the given
Guest OS type.
NOTE: This value may differ from the value returned byIGuest.getOSTypeId()
if Guest Additions are
installed to the guest OS.
value
- Stringpublic java.lang.String getHardwareVersion()
public void setHardwareVersion(java.lang.String value)
value
- Stringpublic java.lang.String getHardwareUUID()
public void setHardwareUUID(java.lang.String value)
value
- Stringpublic java.lang.Long getCPUCount()
public void setCPUCount(java.lang.Long value)
value
- Longpublic java.lang.Boolean getCPUHotPlugEnabled()
public void setCPUHotPlugEnabled(java.lang.Boolean value)
value
- Booleanpublic java.lang.Long getCPUExecutionCap()
public void setCPUExecutionCap(java.lang.Long value)
value
- Longpublic java.lang.Long getCPUIDPortabilityLevel()
public void setCPUIDPortabilityLevel(java.lang.Long value)
value
- Longpublic java.lang.Long getMemorySize()
public void setMemorySize(java.lang.Long value)
value
- Longpublic java.lang.Long getMemoryBalloonSize()
public void setMemoryBalloonSize(java.lang.Long value)
value
- Longpublic java.lang.Boolean getPageFusionEnabled()
public void setPageFusionEnabled(java.lang.Boolean value)
value
- Booleanpublic GraphicsControllerType getGraphicsControllerType()
public void setGraphicsControllerType(GraphicsControllerType value)
value
- org.virtualbox_5_0.GraphicsControllerTypepublic java.lang.Long getVRAMSize()
public void setVRAMSize(java.lang.Long value)
value
- Longpublic java.lang.Boolean getAccelerate3DEnabled()
public void setAccelerate3DEnabled(java.lang.Boolean value)
value
- Booleanpublic java.lang.Boolean getAccelerate2DVideoEnabled()
public void setAccelerate2DVideoEnabled(java.lang.Boolean value)
value
- Booleanpublic java.lang.Long getMonitorCount()
public void setMonitorCount(java.lang.Long value)
value
- Longpublic java.lang.Boolean getVideoCaptureEnabled()
public void setVideoCaptureEnabled(java.lang.Boolean value)
value
- Booleanpublic java.util.List<java.lang.Boolean> getVideoCaptureScreens()
public void setVideoCaptureScreens(java.util.List<java.lang.Boolean> value)
value
- List<Boolean>public java.lang.String getVideoCaptureFile()
public void setVideoCaptureFile(java.lang.String value)
value
- Stringpublic java.lang.Long getVideoCaptureWidth()
public void setVideoCaptureWidth(java.lang.Long value)
value
- Longpublic java.lang.Long getVideoCaptureHeight()
public void setVideoCaptureHeight(java.lang.Long value)
value
- Longpublic java.lang.Long getVideoCaptureRate()
public void setVideoCaptureRate(java.lang.Long value)
value
- Longpublic java.lang.Long getVideoCaptureFPS()
public void setVideoCaptureFPS(java.lang.Long value)
value
- Longpublic java.lang.Long getVideoCaptureMaxTime()
public void setVideoCaptureMaxTime(java.lang.Long value)
value
- Longpublic java.lang.Long getVideoCaptureMaxFileSize()
public void setVideoCaptureMaxFileSize(java.lang.Long value)
value
- Longpublic java.lang.String getVideoCaptureOptions()
public void setVideoCaptureOptions(java.lang.String value)
value
- Stringpublic IBIOSSettings getBIOSSettings()
public FirmwareType getFirmwareType()
public void setFirmwareType(FirmwareType value)
value
- org.virtualbox_5_0.FirmwareTypepublic PointingHIDType getPointingHIDType()
public void setPointingHIDType(PointingHIDType value)
value
- org.virtualbox_5_0.PointingHIDTypepublic KeyboardHIDType getKeyboardHIDType()
public void setKeyboardHIDType(KeyboardHIDType value)
value
- org.virtualbox_5_0.KeyboardHIDTypepublic java.lang.Boolean getHPETEnabled()
public void setHPETEnabled(java.lang.Boolean value)
value
- Booleanpublic ChipsetType getChipsetType()
public void setChipsetType(ChipsetType value)
value
- org.virtualbox_5_0.ChipsetTypepublic java.lang.String getSnapshotFolder()
getSettingsFilePath()
>/<getId()
>.
Currently, it is an error to try to change this property on
a machine that has snapshots (because this would require to
move possibly large files to a different location).
A separate method will be available for this purpose later.
NOTE: Setting this property to null or to an empty string will restore
the initial value.
NOTE: When setting this property, the specified path can be
absolute (full path) or relative to the directory where thegetSettingsFilePath()
is located. When reading this property, a full path is
always returned.
NOTE: The specified path may not exist, it will be created
when necessary.
public void setSnapshotFolder(java.lang.String value)
getSettingsFilePath()
>/<getId()
>.
Currently, it is an error to try to change this property on
a machine that has snapshots (because this would require to
move possibly large files to a different location).
A separate method will be available for this purpose later.
NOTE: Setting this property to null or to an empty string will restore
the initial value.
NOTE: When setting this property, the specified path can be
absolute (full path) or relative to the directory where thegetSettingsFilePath()
is located. When reading this property, a full path is
always returned.
NOTE: The specified path may not exist, it will be created
when necessary.
value
- Stringpublic IVRDEServer getVRDEServer()
public java.lang.Boolean getEmulatedUSBCardReaderEnabled()
public void setEmulatedUSBCardReaderEnabled(java.lang.Boolean value)
public java.util.List<IMediumAttachment> getMediumAttachments()
public java.util.List<IUSBController> getUSBControllers()
public IUSBDeviceFilters getUSBDeviceFilters()
public IAudioAdapter getAudioAdapter()
public java.util.List<IStorageController> getStorageControllers()
public java.lang.String getSettingsFilePath()
public java.lang.Boolean getSettingsModified()
ISession.getMachine()
and on new machines
created byIVirtualBox.createMachine(String,String,List,String,String)
or opened
byIVirtualBox.openMachine(String)
but not
yet registered, or on unregistered machines after callingunregister(org.virtualbox_5_0.CleanupMode)
. For all other
cases, the settings can never be modified.
NOTE: For newly created unregistered machines, the value of this
property is always true untilsaveSettings()
is called (no matter if any machine settings have been
changed after the creation or not). For opened machines
the value is set to false (and then follows to normal rules).
public SessionState getSessionState()
public java.lang.String getSessionName()
getSessionState()
is
Spawning or Locked, this attribute contains the
same value as passed to thelaunchVMProcess(org.virtualbox_5_0.ISession,String,String)
method in the
name parameter. If the session was established withlockMachine(org.virtualbox_5_0.ISession,org.virtualbox_5_0.LockType)
, it is the name of the session
(if set, otherwise empty string). IfgetSessionState()
is SessionClosed, the value of this
attribute is an empty string.
public java.lang.Long getSessionPID()
lockMachine(org.virtualbox_5_0.ISession,org.virtualbox_5_0.LockType)
call. The returned
value is only valid ifgetSessionState()
is Locked or
Unlocking by the time this property is read.
public MachineState getState()
public java.lang.Long getLastStateChange()
public java.lang.String getStateFilePath()
MachineState.Saved
state.
NOTE: When the machine is not in the Saved state, this attribute is
an empty string.
public java.lang.String getLogFolder()
public ISnapshot getCurrentSnapshot()
takeSnapshot(String,String,Boolean,Holder)
,deleteSnapshot(String)
orrestoreSnapshot(org.virtualbox_5_0.ISnapshot)
, depending on which was called last.
SeeISnapshot
for details.
public java.lang.Long getSnapshotCount()
public java.lang.Boolean getCurrentStateModified()
restoreSnapshot(org.virtualbox_5_0.ISnapshot)
takeSnapshot(String,String,Boolean,Holder)
(issued on a "powered off" or "saved"
machine, for whichgetSettingsModified()
returns false)
public java.util.List<ISharedFolder> getSharedFolders()
createSharedFolder(String,String,Boolean,Boolean)
. Existing shared folders can be
removed usingremoveSharedFolder(String)
.
public ClipboardMode getClipboardMode()
public void setClipboardMode(ClipboardMode value)
value
- org.virtualbox_5_0.ClipboardModepublic DnDMode getDnDMode()
public void setDnDMode(DnDMode value)
value
- org.virtualbox_5_0.DnDModepublic java.lang.Boolean getTeleporterEnabled()
public void setTeleporterEnabled(java.lang.Boolean value)
value
- Booleanpublic java.lang.Long getTeleporterPort()
public void setTeleporterPort(java.lang.Long value)
value
- Longpublic java.lang.String getTeleporterAddress()
public void setTeleporterAddress(java.lang.String value)
value
- Stringpublic java.lang.String getTeleporterPassword()
public void setTeleporterPassword(java.lang.String value)
value
- Stringpublic ParavirtProvider getParavirtProvider()
public void setParavirtProvider(ParavirtProvider value)
value
- org.virtualbox_5_0.ParavirtProviderpublic FaultToleranceState getFaultToleranceState()
public void setFaultToleranceState(FaultToleranceState value)
value
- org.virtualbox_5_0.FaultToleranceStatepublic java.lang.Long getFaultTolerancePort()
public void setFaultTolerancePort(java.lang.Long value)
value
- Longpublic java.lang.String getFaultToleranceAddress()
public void setFaultToleranceAddress(java.lang.String value)
value
- Stringpublic java.lang.String getFaultTolerancePassword()
public void setFaultTolerancePassword(java.lang.String value)
value
- Stringpublic java.lang.Long getFaultToleranceSyncInterval()
public void setFaultToleranceSyncInterval(java.lang.Long value)
value
- Longpublic java.lang.Boolean getRTCUseUTC()
public void setRTCUseUTC(java.lang.Boolean value)
value
- Booleanpublic java.lang.Boolean getIOCacheEnabled()
public void setIOCacheEnabled(java.lang.Boolean value)
value
- Booleanpublic java.lang.Long getIOCacheSize()
public void setIOCacheSize(java.lang.Long value)
value
- Longpublic java.util.List<IPCIDeviceAttachment> getPCIDeviceAssignments()
IConsole.getAttachedPCIDevices()
attribute, as this attribute
is intended to list only devices additional to what described in
virtual hardware config. Usually, this list keeps host's physical
devices assigned to the particular machine.
public IBandwidthControl getBandwidthControl()
public java.lang.Boolean getTracingEnabled()
public void setTracingEnabled(java.lang.Boolean value)
value
- Booleanpublic java.lang.String getTracingConfig()
getTracingEnabled()
is true. The string specifies
a space separated of tracepoint group names to enable. The special
group 'all' enables all tracepoints. Check DBGFR3TracingConfig for
more details on available tracepoint groups and such.
Note that on hosts supporting DTrace (or similar), a lot of the
tracepoints may be implemented exclusively as DTrace probes. So, the
effect of the same config may differ between Solaris and Windows for
example.
public void setTracingConfig(java.lang.String value)
getTracingEnabled()
is true. The string specifies
a space separated of tracepoint group names to enable. The special
group 'all' enables all tracepoints. Check DBGFR3TracingConfig for
more details on available tracepoint groups and such.
Note that on hosts supporting DTrace (or similar), a lot of the
tracepoints may be implemented exclusively as DTrace probes. So, the
effect of the same config may differ between Solaris and Windows for
example.
value
- Stringpublic java.lang.Boolean getAllowTracingToAccessVM()
public void setAllowTracingToAccessVM(java.lang.Boolean value)
value
- Booleanpublic java.lang.Boolean getAutostartEnabled()
public void setAutostartEnabled(java.lang.Boolean value)
value
- Booleanpublic java.lang.Long getAutostartDelay()
public void setAutostartDelay(java.lang.Long value)
value
- Longpublic AutostopType getAutostopType()
public void setAutostopType(AutostopType value)
value
- org.virtualbox_5_0.AutostopTypepublic java.lang.String getDefaultFrontend()
launchVMProcess(org.virtualbox_5_0.ISession,String,String)
method.
Empty or null strings do not define a particular default, it is up
tolaunchVMProcess(org.virtualbox_5_0.ISession,String,String)
to select one. See the
description oflaunchVMProcess(org.virtualbox_5_0.ISession,String,String)
for the valid
frontend types.
This per-VM setting overrides the default defined byISystemProperties.getDefaultFrontend()
attribute, and is
overridden by a frontend type passed tolaunchVMProcess(org.virtualbox_5_0.ISession,String,String)
.
public void setDefaultFrontend(java.lang.String value)
launchVMProcess(org.virtualbox_5_0.ISession,String,String)
method.
Empty or null strings do not define a particular default, it is up
tolaunchVMProcess(org.virtualbox_5_0.ISession,String,String)
to select one. See the
description oflaunchVMProcess(org.virtualbox_5_0.ISession,String,String)
for the valid
frontend types.
This per-VM setting overrides the default defined byISystemProperties.getDefaultFrontend()
attribute, and is
overridden by a frontend type passed tolaunchVMProcess(org.virtualbox_5_0.ISession,String,String)
.
value
- Stringpublic java.lang.Boolean getUSBProxyAvailable()
public java.lang.String getVMProcessPriority()
E_NOTIMPL | This attribute is currently not implemented. |
public void setVMProcessPriority(java.lang.String value)
E_NOTIMPL | This attribute is currently not implemented. |
value
- Stringpublic static IMachine queryInterface(IUnknown obj)
public void lockMachine(ISession session, LockType lockType)
ISession.getMachine()
attribute.ISession.getType()
, which will have been
set to either WriteLock or Shared.IConsole
object which controls VM execution.
Also in all of the above cases, one must always callISession.unlockMachine()
to release the lock on the machine, or
the machine's state will eventually be set to "Aborted".
To change settings on a machine, the following sequence is typically
performed:ISession.getMachine()
.saveSettings()
.ISession.unlockMachine()
.
session
- Session object for which the machine will be locked.lockType
- If set to Write, then attempt to acquire an exclusive write lock or fail.
If set to Shared, then either acquire an exclusive write lock or establish
a link to an existing session.
Expected result codes:
E_UNEXPECTED | Virtual machine not registered. |
E_ACCESSDENIED | Process not started by OpenRemoteSession. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Session already open or being opened. |
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR | Failed to assign machine to session. |
public IProgress launchVMProcess(ISession session, java.lang.String name, java.lang.String environment)
IConsole
object which can be used
to control machine execution, but it cannot be used to change all VM settings
which would be available after alockMachine(org.virtualbox_5_0.ISession,org.virtualbox_5_0.LockType)
call.
The caller must eventually release the session's shared lock by callingISession.unlockMachine()
on the local session object once this call
has returned. However, the session's state (seeISession.getState()
)
will not return to "Unlocked" until the remote session has also unlocked
the machine (i.e. the machine has stopped running).
Launching a VM process can take some time (a new VM is started in a new process,
for which memory and other resources need to be set up). Because of this,
anIProgress
object is returned to allow the caller to wait
for this asynchronous operation to be completed. Until then, the caller's
session object remains in the "Unlocked" state, and itsISession.getMachine()
andISession.getConsole()
attributes cannot be accessed.
It is recommended to useIProgress.waitForCompletion(Integer)
or
similar calls to wait for completion. Completion is signalled when the VM
is powered on. If launching the VM fails, error messages can be queried
via the progress object, if available.
The progress object will have at least 2 sub-operations. The first
operation covers the period up to the new VM process calls powerUp.
The subsequent operations mirror theIConsole.powerUp()
progress object. BecauseIConsole.powerUp()
may require
some extra sub-operations, theIProgress.getOperationCount()
may change at the completion of operation.
For details on the teleportation progress operation, seeIConsole.powerUp()
.The environment argument is a string containing definitions of
environment variables in the following format:NAME[=VALUE]\n NAME[=VALUE]\n ...where\\nis the new line character. These environment variables will be appended to the environment of the VirtualBox server process. If an environment variable exists both in the server process and in this list, the value from this list takes precedence over the server's variable. If the value of the environment variable is omitted, this variable will be removed from the resulting environment. If the environment string is null or empty, the server environment is inherited by the started process as is.
session
- Client session object to which the VM process will be connected (this
must be in "Unlocked" state).name
- Front-end to use for the new VM process. The following are currently supported:getDefaultFrontend()
andISystemProperties.getDefaultFrontend()
.environment
- Environment to pass to the VM process.
E_UNEXPECTED | Virtual machine not registered. |
E_INVALIDARG | Invalid session type type. |
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | No machine matching machineId found. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Session already open or being opened. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Launching process for machine failed. |
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR | Failed to assign machine to session. |
public void setBootOrder(java.lang.Long position, DeviceType device)
DeviceType.Null
should be used.
TODO setHardDiskBootOrder(), setNetworkBootOrder()
position
- Position in the boot order ( 1 to the total number of
devices the machine can boot from, as returned byISystemProperties.getMaxBootPosition()
).device
- The type of the device used to boot at the given position.
Expected result codes:
E_INVALIDARG | Boot position out of range. |
E_NOTIMPL | Booting from USB device currently not supported. |
public DeviceType getBootOrder(java.lang.Long position)
DeviceType.Null
is returned.
TODO getHardDiskBootOrder(), getNetworkBootOrder()
position
- Position in the boot order ( 1 to the total number of
devices the machine can boot from, as returned byISystemProperties.getMaxBootPosition()
).
E_INVALIDARG | Boot position out of range. |
public void attachDevice(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, DeviceType type, IMedium medium)
IStorageController
, identified by name),
at the indicated port and device.
This method is intended for managing storage devices in general while a
machine is powered off. It can be used to attach and detach fixed
and removable media. The following kind of media can be attached
to a machine:IVirtualBox.openMedium(String,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.AccessMode,Boolean)
.IHost.getDVDDrives()
andIHost.getFloppyDrives()
arrays to indicate a host drive.
For removable devices, you can also usemountMedium(String,Integer,Integer,org.virtualbox_5_0.IMedium,Boolean)
to change the media while the machine is running.IMediumAttachment
will appear in the machine's list of medium
attachments (seegetMediumAttachments()
).
SeeIMedium
andIMediumAttachment
for more
information about attaching media.
The specified device slot must not have a device attached to it,
or this method will fail.
name
- Name of the storage controller to attach the device to.controllerPort
- Port to attach the device to. For an IDE controller, 0 specifies
the primary controller and 1 specifies the secondary controller.
For a SCSI controller, this must range from 0 to 15; for a SATA controller,
from 0 to 29; for an SAS controller, from 0 to 7.device
- Device slot in the given port to attach the device to. This is only
relevant for IDE controllers, for which 0 specifies the master device and
1 specifies the slave device. For all other controller types, this must
be 0.type
- Device type of the attached device. For media opened byIVirtualBox.openMedium(String,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.AccessMode,Boolean)
, this must match the device type
specified there.medium
- Medium to mount or null for an empty drive.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range, or file or UUID not found. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Machine must be registered before media can be attached. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USE | A medium is already attached to this or another virtual machine. |
saveSettings()
.
NOTE: If the medium is being attached indirectly, a new differencing medium
will implicitly be created for it and attached instead. If the
changes made to the machine settings (including this indirect
attachment) are later cancelled usingdiscardSettings()
,
this implicitly created differencing medium will implicitly
be deleted.public void attachDeviceWithoutMedium(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, DeviceType type)
IStorageController
, identified by name),
at the indicated port and device.
This method is intended for managing storage devices in general while a
machine is powered off. It can be used to attach and detach fixed
and removable media. The following kind of media can be attached
to a machine:IVirtualBox.openMedium(String,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.AccessMode,Boolean)
.IHost.getDVDDrives()
andIHost.getFloppyDrives()
arrays to indicate a host drive.
For removable devices, you can also usemountMedium(String,Integer,Integer,org.virtualbox_5_0.IMedium,Boolean)
to change the media while the machine is running.IMediumAttachment
will appear in the machine's list of medium
attachments (seegetMediumAttachments()
).
SeeIMedium
andIMediumAttachment
for more
information about attaching media.
The specified device slot must not have a device attached to it,
or this method will fail.
name
- Name of the storage controller to attach the device to.controllerPort
- Port to attach the device to. For an IDE controller, 0 specifies
the primary controller and 1 specifies the secondary controller.
For a SCSI controller, this must range from 0 to 15; for a SATA controller,
from 0 to 29; for an SAS controller, from 0 to 7.device
- Device slot in the given port to attach the device to. This is only
relevant for IDE controllers, for which 0 specifies the master device and
1 specifies the slave device. For all other controller types, this must
be 0.type
- Device type of the attached device. For media opened byIVirtualBox.openMedium(String,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.AccessMode,Boolean)
, this must match the device type
specified there.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range, or file or UUID not found. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Machine must be registered before media can be attached. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USE | A medium is already attached to this or another virtual machine. |
saveSettings()
.
NOTE: If the medium is being attached indirectly, a new differencing medium
will implicitly be created for it and attached instead. If the
changes made to the machine settings (including this indirect
attachment) are later cancelled usingdiscardSettings()
,
this implicitly created differencing medium will implicitly
be deleted.public void detachDevice(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device)
saveSettings()
call. SeeIMedium
for more detailed information about attaching media.
name
- Name of the storage controller to detach the medium from.controllerPort
- Port number to detach the medium from.device
- Device slot number to detach the medium from.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Attempt to detach medium from a running virtual machine. |
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | No medium attached to given slot/bus. |
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTED | Medium format does not support storage deletion (only for implicitly created differencing media, should not happen). |
attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
for the indirect attachment using this
method willnotimplicitly delete them. TheIMedium.deleteStorage()
operation should be
explicitly performed by the caller after the medium is successfully
detached and the settings are saved withsaveSettings()
, if it is the desired action.public void passthroughDevice(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, java.lang.Boolean passthrough)
attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
for how to attach a new device.
The controllerPort and device parameters specify the device slot and
have have the same meaning as withattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
.
name
- Name of the storage controller.controllerPort
- Storage controller port.device
- Device slot in the given port.passthrough
- New value for the passthrough setting.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
public void temporaryEjectDevice(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, java.lang.Boolean temporaryEject)
attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
for how to
attach a new device.
The controllerPort and device parameters specify the device slot and
have have the same meaning as withattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
.
name
- Name of the storage controller.controllerPort
- Storage controller port.device
- Device slot in the given port.temporaryEject
- New value for the eject behavior.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
public void nonRotationalDevice(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, java.lang.Boolean nonRotational)
attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
for how to attach a new device.
The controllerPort and device parameters specify the device slot and
have have the same meaning as withattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
.
name
- Name of the storage controller.controllerPort
- Storage controller port.device
- Device slot in the given port.nonRotational
- New value for the non-rotational device flag.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
public void setAutoDiscardForDevice(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, java.lang.Boolean discard)
attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
for how to attach a new
device.
The controllerPort and device parameters specify the device slot and
have have the same meaning as withattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
.
name
- Name of the storage controller.controllerPort
- Storage controller port.device
- Device slot in the given port.discard
- New value for the discard device flag.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, SCSI port out of range. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
public void setHotPluggableForDevice(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, java.lang.Boolean hotPluggable)
attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
for how to attach a new device.
The controllerPort and device parameters specify the device slot and
have have the same meaning as withattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
.
name
- Name of the storage controller.controllerPort
- Storage controller port.device
- Device slot in the given port.hotPluggable
- New value for the hot-pluggable device flag.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTED | Controller doesn't support hot plugging. |
public void setBandwidthGroupForDevice(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, IBandwidthGroup bandwidthGroup)
attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
for how to attach a new device.
The controllerPort and device parameters specify the device slot and
have have the same meaning as withattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
.
name
- Name of the storage controller.controllerPort
- Storage controller port.device
- Device slot in the given port.bandwidthGroup
- New value for the bandwidth group or null for no group.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
public void setNoBandwidthGroupForDevice(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device)
attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
for how to attach a new device.
The controllerPort and device parameters specify the device slot and
have have the same meaning as withattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
.
name
- Name of the storage controller.controllerPort
- Storage controller port.device
- Device slot in the given port.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
public void unmountMedium(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, java.lang.Boolean force)
IMedium
,
identified by the given UUID id) to the given storage controller
(IStorageController
, identified by name),
at the indicated port and device. The device must already exist;
This method is intended only for managing removable media, where the
device is fixed but media is changeable at runtime (such as DVDs
and floppies). It cannot be used for fixed media such as hard disks.
The controllerPort and device parameters specify the device slot
and have have the same meaning as withattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
.
The specified device slot must have a medium mounted, which will be
unmounted. If there is no mounted medium it will do nothing.
SeeIMedium
for more detailed information about
attaching/unmounting media.
name
- Name of the storage controller to unmount the medium from.controllerPort
- Port to unmount the medium from.device
- Device slot in the given port to unmount the medium from.force
- Allows to force unmount of a medium which is locked by
the device slot in the given port medium is attached to.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Attempt to unmount medium that is not removable - not DVD or floppy. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USE | Medium already attached to this or another virtual machine. |
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | Medium not attached to specified port, device, controller. |
public void mountMedium(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device, IMedium medium, java.lang.Boolean force)
IMedium
, identified
by the given UUID id) to the given storage controller
(IStorageController
, identified by name),
at the indicated port and device. The device must already exist;
seeattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
for how to attach a new device.
This method is intended only for managing removable media, where the
device is fixed but media is changeable at runtime (such as DVDs
and floppies). It cannot be used for fixed media such as hard disks.
The controllerPort and device parameters specify the device slot and
have have the same meaning as withattachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
.
The specified device slot can have a medium mounted, which will be
unmounted first. Specifying a zero UUID (or an empty string) for
medium does just an unmount.
SeeIMedium
for more detailed information about
attaching media.
name
- Name of the storage controller to attach the medium to.controllerPort
- Port to attach the medium to.device
- Device slot in the given port to attach the medium to.medium
- Medium to mount or null for an empty drive.force
- Allows to force unmount/mount of a medium which is locked by
the device slot in the given port to attach the medium to.
Expected result codes:
E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Attempt to attach medium to an unregistered virtual machine. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Invalid machine state. |
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USE | Medium already attached to this or another virtual machine. |
public IMedium getMedium(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device)
mountMedium(String,Integer,Integer,org.virtualbox_5_0.IMedium,Boolean)
to the given device slot then this
method will return not the same object as passed to themountMedium(String,Integer,Integer,org.virtualbox_5_0.IMedium,Boolean)
call. SeeIMedium
for
more detailed information about mounting a medium.
name
- Name of the storage controller the medium is attached to.controllerPort
- Port to query.device
- Device slot in the given port to query.
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | No medium attached to given slot/bus. |
public java.util.List<IMediumAttachment> getMediumAttachmentsOfController(java.lang.String name)
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | A storage controller with given name doesn't exist. |
public IMediumAttachment getMediumAttachment(java.lang.String name, java.lang.Integer controllerPort, java.lang.Integer device)
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | No attachment exists for the given controller/port/device combination. |
public void attachHostPCIDevice(java.lang.Integer hostAddress, java.lang.Integer desiredGuestAddress, java.lang.Boolean tryToUnbind)
hostAddress
- Address of the host PCI device.desiredGuestAddress
- Desired position of this device on guest PCI bus.tryToUnbind
- If VMM shall try to unbind existing drivers from the
device before attaching it to the guest.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine state is not stopped (PCI hotplug not yet implemented). |
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERROR | Virtual machine does not have a PCI controller allowing attachment of physical devices. |
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTED | Hardware or host OS doesn't allow PCI device passthrough. |
IHostPCIDevicePlugEvent
public void detachHostPCIDevice(java.lang.Integer hostAddress)
hostAddress
- Address of the host PCI device.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine state is not stopped (PCI hotplug not yet implemented). |
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | This host device is not attached to this machine. |
@link ::VBOX_E_PDM_ERROR VBOX_E_PDM_ERROR | Virtual machine does not have a PCI controller allowing attachment of physical devices. |
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTED | Hardware or host OS doesn't allow PCI device passthrough. |
IHostPCIDevicePlugEvent
public INetworkAdapter getNetworkAdapter(java.lang.Long slot)
ISystemProperties.getMaxNetworkAdapters(org.virtualbox_5_0.ChipsetType)
property,
so the maximum slot number is one less than that property's value.
Expected result codes:
E_INVALIDARG | Invalid slot number. |
public IStorageController addStorageController(java.lang.String name, StorageBus connectionType)
IStorageController
.
name identifies the controller for subsequent calls such asgetStorageControllerByName(String)
,getStorageControllerByInstance(org.virtualbox_5_0.StorageBus,Long)
,removeStorageController(String)
,attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.IMedium)
ormountMedium(String,Integer,Integer,org.virtualbox_5_0.IMedium,Boolean)
.
After the controller has been added, you can set its exact
type by setting theIStorageController.getControllerType()
.
Expected result codes:
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USE | A storage controller with given name exists already. |
E_INVALIDARG | Invalid controllerType. |
public IStorageController getStorageControllerByName(java.lang.String name)
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | A storage controller with given name doesn't exist. |
public IStorageController getStorageControllerByInstance(StorageBus connectionType, java.lang.Long instance)
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | A storage controller with given instance number doesn't exist. |
public void removeStorageController(java.lang.String name)
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | A storage controller with given name doesn't exist. |
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTED | Medium format does not support storage deletion (only for implicitly created differencing media, should not happen). |
public void setStorageControllerBootable(java.lang.String name, java.lang.Boolean bootable)
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | A storage controller with given name doesn't exist. |
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USE | Another storage controller is marked as bootable already. |
public IUSBController addUSBController(java.lang.String name, USBControllerType type)
IUSBController
.
Expected result codes:
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USE | A USB controller with given type exists already. |
E_INVALIDARG | Invalid controllerType. |
public void removeUSBController(java.lang.String name)
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | A USB controller with given type doesn't exist. |
public IUSBController getUSBControllerByName(java.lang.String name)
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | A USB controller with given name doesn't exist. |
public java.lang.Long getUSBControllerCountByType(USBControllerType type)
public ISerialPort getSerialPort(java.lang.Long slot)
ISystemProperties.getSerialPortCount()
property,
so the maximum slot number is one less than that property's value.
Expected result codes:
E_INVALIDARG | Invalid slot number. |
public IParallelPort getParallelPort(java.lang.Long slot)
ISystemProperties.getParallelPortCount()
property,
so the maximum slot number is one less than that property's value.
Expected result codes:
E_INVALIDARG | Invalid slot number. |
public java.util.List<java.lang.String> getExtraDataKeys()
public java.lang.String getExtraData(java.lang.String key)
key
- Name of the data key to get.
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Settings file not accessible. |
@link ::VBOX_E_XML_ERROR VBOX_E_XML_ERROR | Could not parse the settings file. |
public void setExtraData(java.lang.String key, java.lang.String value)
key
- Name of the data key to set.value
- Value to assign to the key.
Expected result codes:
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Settings file not accessible. |
@link ::VBOX_E_XML_ERROR VBOX_E_XML_ERROR | Could not parse the settings file. |
IExtraDataCanChangeEvent
notification for a permission. If one of the listeners refuses the
new value, the change will not be performed.
NOTE: On success, theIExtraDataChangedEvent
notification
is called to inform all registered listeners about a successful data
change.
NOTE: This method can be called outside the machine session and therefore
it's a caller's responsibility to handle possible race conditions
when several clients change the same key at the same time.public java.lang.Boolean getCPUProperty(CPUPropertyType property)
property
- Property type to query.
E_INVALIDARG | Invalid property. |
public void setCPUProperty(CPUPropertyType property, java.lang.Boolean value)
property
- Property type to query.value
- Property value.
Expected result codes:
E_INVALIDARG | Invalid property. |
public void getCPUIDLeaf(java.lang.Long id, Holder<java.lang.Long> valEax, Holder<java.lang.Long> valEbx, Holder<java.lang.Long> valEcx, Holder<java.lang.Long> valEdx)
id
- CPUID leaf index.valEax
- CPUID leaf value for register eax.valEbx
- CPUID leaf value for register ebx.valEcx
- CPUID leaf value for register ecx.valEdx
- CPUID leaf value for register edx.
Expected result codes:
E_INVALIDARG | Invalid id. |
public void setCPUIDLeaf(java.lang.Long id, java.lang.Long valEax, java.lang.Long valEbx, java.lang.Long valEcx, java.lang.Long valEdx)
id
- CPUID leaf index.valEax
- CPUID leaf value for register eax.valEbx
- CPUID leaf value for register ebx.valEcx
- CPUID leaf value for register ecx.valEdx
- CPUID leaf value for register edx.
Expected result codes:
E_INVALIDARG | Invalid id. |
public void removeCPUIDLeaf(java.lang.Long id)
id
- CPUID leaf index.
Expected result codes:
E_INVALIDARG | Invalid id. |
public void removeAllCPUIDLeaves()
public java.lang.Boolean getHWVirtExProperty(HWVirtExPropertyType property)
property
- Property type to query.
E_INVALIDARG | Invalid property. |
public void setHWVirtExProperty(HWVirtExPropertyType property, java.lang.Boolean value)
property
- Property type to set.value
- New property value.
Expected result codes:
E_INVALIDARG | Invalid property. |
public IProgress setSettingsFilePath(java.lang.String settingsFilePath)
settingsFilePath
- New settings file path, will be used to determine the new
location for the attached media if it is in the same directory or
below as the original settings file.
E_NOTIMPL | The operation is not implemented yet. |
public void saveSettings()
saveSettings()
ordiscardSettings()
.
For registered machines, new settings become visible to all
other VirtualBox clients after successful invocation of this
method.
Expected result codes:
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Settings file not accessible. |
@link ::VBOX_E_XML_ERROR VBOX_E_XML_ERROR | Could not parse the settings file. |
E_ACCESSDENIED | Modification request refused. |
IMachineDataChangedEvent
notification event after the configuration has been successfully
saved (only for registered machines).
NOTE: Calling this method is only valid on instances returned
byISession.getMachine()
and on new machines
created byIVirtualBox.createMachine(String,String,List,String,String)
but not
yet registered, or on unregistered machines after callingunregister(org.virtualbox_5_0.CleanupMode)
.
public void discardSettings()
saveSettings()
ordiscardSettings()
.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine is not mutable. |
ISession.getMachine()
and on new machines
created byIVirtualBox.createMachine(String,String,List,String,String)
or
opened byIVirtualBox.openMachine(String)
but not
yet registered, or on unregistered machines after callingunregister(org.virtualbox_5_0.CleanupMode)
.
public java.util.List<IMedium> unregister(CleanupMode cleanupMode)
IVirtualBox.registerMachine(org.virtualbox_5_0.IMachine)
and optionally do additional
cleanup before the machine is unregistered.
This method does not delete any files. It only changes the machine configuration and
the list of registered machines in the VirtualBox object. To delete the files which
belonged to the machine, including the XML file of the machine itself, calldeleteConfig(List)
, optionally with the array of IMedium objects which was returned
from this method.
How thoroughly this method cleans up the machine configuration before unregistering
the machine depends on the cleanupMode argument.IMediumAttachment
).
It is the responsibility of the caller to delete all such configuration in this mode.
In this mode, the API behaves like the former IVirtualBox::unregisterMachine() API
which it replaces.deleteConfig(List)
API for closing and deletion.deleteConfig(List)
in that case because users will typically want to preserve ISO and RAW image files.deleteConfig(List)
. This way, the machine is completely
deleted with all its saved states and hard disk images, but images for removable
drives (such as ISO and RAW files) will remain on disk.
This API does not verify whether the media files returned in the array are still
attached to other machines (i.e. shared between several machines). If such a shared
image is passed todeleteConfig(List)
however, closing the image will fail there
and the image will be silently skipped.
This API may, however, move media from this machine's media registry to other media
registries (seeIMedium
for details on media registries). For machines
created with VirtualBox 4.0 or later, if media from this machine's media registry
are also attached to another machine (shared attachments), each such medium will be
moved to another machine's registry. This is because without this machine's media
registry, the other machine cannot find its media any more and would become inaccessible.
This API implicitly callssaveSettings()
to save all current machine settings
before unregistering it. It may also silently callsaveSettings()
on other machines
if media are moved to other machines' media registries.
After successful method invocation, theIMachineRegisteredEvent
event
is fired.
The call will fail if the machine is currently locked (seeISession
).
cleanupMode
- How to clean up after the machine has been unregistered.
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Machine is currently locked for a session. |
getAccessible()
), it
will be unregistered and fully uninitialized right afterwards. As a result,
the returned machine object will be unusable and an attempt to callanymethod will return the "Object not ready" error.public IProgress deleteConfig(java.util.List<IMedium> media)
unregister(org.virtualbox_5_0.CleanupMode)
call.
This method must only be called on machines which are either write-locked (i.e. on instances
returned byISession.getMachine()
) or on unregistered machines (i.e. not yet
registered machines created byIVirtualBox.createMachine(String,String,List,String,String)
or opened byIVirtualBox.openMachine(String)
, or after having calledunregister(org.virtualbox_5_0.CleanupMode)
).
The following files will be deleted by this method:unregister(org.virtualbox_5_0.CleanupMode)
had been previously called with a cleanupMode
argument other than "UnregisterOnly", this will delete all saved state files that
the machine had in use; possibly one if the machine was in "Saved" state and one
for each online snapshot that the machine had.IMedium.close()
. If that succeeds, this will attempt to delete the
medium's storage on disk. Since theIMedium.close()
call will fail if the medium is still
in use, e.g. because it is still attached to a second machine; in that case the
storage will not be deleted.
media
- List of media to be closed and whose storage files will be deleted.
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Machine is registered but not write-locked. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Could not delete the settings file. |
getSettingsModified()
will return true after this
method successfully returns.public IVirtualSystemDescription exportTo(IAppliance appliance, java.lang.String location)
IAppliance
for the
steps required to export VirtualBox machines to OVF.
appliance
- Appliance to export this machine to.location
- The target location.
public ISnapshot findSnapshot(java.lang.String nameOrId)
ISnapshot.getChildren()
attribute and recurse over those children.
nameOrId
- What to search for. Name or UUID of the snapshot to find
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | Virtual machine has no snapshots or snapshot not found. |
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 read-only.automount
- Whether the share gets automatically mounted by the guest
or not.
Expected result codes:
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USE | Shared folder already exists. |
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Shared folder hostPath 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 is not mutable. |
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | Shared folder name does not exist. |
public java.lang.Boolean canShowConsoleWindow()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Machine session is not open. |
public java.lang.Long showConsoleWindow()
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Machine session is not open. |
public void getGuestProperty(java.lang.String name, Holder<java.lang.String> value, Holder<java.lang.Long> timestamp, Holder<java.lang.String> flags)
name
- The name of the property to read.value
- The value of the property. If the property does not exist then this
will be empty.timestamp
- The time at which the property was last modified, as seen by the
server process.flags
- Additional property parameters, passed as a comma-separated list of
"name=value" type entries.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Machine session is not open. |
public java.lang.String getGuestPropertyValue(java.lang.String property)
property
- The name of the property to read.
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Machine session is not open. |
public java.lang.Long getGuestPropertyTimestamp(java.lang.String property)
property
- The name of the property to read.
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Machine session is not open. |
public void setGuestProperty(java.lang.String property, java.lang.String value, java.lang.String flags)
property
- The name of the property to set, change or delete.value
- The new value of the property to set, change or delete. If the
property does not yet exist and value is non-empty, it will be
created. If the value is null or empty, the property will be
deleted if it exists.flags
- Additional property parameters, passed as a comma-separated list of
"name=value" type entries.
Expected result codes:
E_ACCESSDENIED | Property cannot be changed. |
E_INVALIDARG | Invalid flags. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine is not mutable or session not open. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Cannot set transient property when machine not running. |
public void setGuestPropertyValue(java.lang.String property, java.lang.String value)
property
- The name of the property to set or change.value
- The new value of the property to set or change. If the
property does not yet exist and value is non-empty, it will be
created.
Expected result codes:
E_ACCESSDENIED | Property cannot be changed. |
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine is not mutable or session not open. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Cannot set transient property when machine not running. |
public void deleteGuestProperty(java.lang.String name)
name
- The name of the property to delete.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Machine session is not open. |
public void enumerateGuestProperties(java.lang.String patterns, Holder<java.util.List<java.lang.String>> names, Holder<java.util.List<java.lang.String>> values, Holder<java.util.List<java.lang.Long>> timestamps, Holder<java.util.List<java.lang.String>> flags)
patterns
- The patterns to match the properties against, separated by '|'
characters. If this is empty or null, all properties will match.names
- The names of the properties returned.values
- The values of the properties returned. The array entries match the
corresponding entries in the name array.timestamps
- The time stamps of the properties returned. The array entries match
the corresponding entries in the name array.flags
- The flags of the properties returned. The array entries match the
corresponding entries in the name array.public void querySavedGuestScreenInfo(java.lang.Long screenId, Holder<java.lang.Long> originX, Holder<java.lang.Long> originY, Holder<java.lang.Long> width, Holder<java.lang.Long> height, Holder<java.lang.Boolean> enabled)
screenId
- Saved guest screen to query info from.originX
- The X position of the guest monitor top left corner.originY
- The Y position of the guest monitor top left corner.width
- Guest width at the time of the saved state was taken.height
- Guest height at the time of the saved state was taken.enabled
- Whether the monitor is enabled in the guest.public byte[] readSavedThumbnailToArray(java.lang.Long screenId, BitmapFormat bitmapFormat, Holder<java.lang.Long> width, Holder<java.lang.Long> height)
screenId
- Saved guest screen to read from.bitmapFormat
- The requested format.width
- Bitmap width.height
- Bitmap height.
public java.util.List<BitmapFormat> querySavedScreenshotInfo(java.lang.Long screenId, Holder<java.lang.Long> width, Holder<java.lang.Long> height)
screenId
- Saved guest screen to query info from.width
- Image width.height
- Image height.
public byte[] readSavedScreenshotToArray(java.lang.Long screenId, BitmapFormat bitmapFormat, Holder<java.lang.Long> width, Holder<java.lang.Long> height)
screenId
- Saved guest screen to read from.bitmapFormat
- The requested format.width
- Image width.height
- Image height.
public void hotPlugCPU(java.lang.Long cpu)
cpu
- The CPU id to insert.public void hotUnplugCPU(java.lang.Long cpu)
cpu
- The CPU id to remove.public java.lang.Boolean getCPUStatus(java.lang.Long cpu)
cpu
- The CPU id to check for.
public ParavirtProvider getEffectiveParavirtProvider()
public java.lang.String queryLogFilename(java.lang.Long idx)
idx
- Which log file name to query. 0=current log file.
public byte[] readLog(java.lang.Long idx, java.lang.Long offset, java.lang.Long size)
idx
- Which log file to read. 0=current log file.offset
- Offset in the log file.size
- Chunk size to read in the log file.
public IProgress cloneTo(IMachine target, CloneMode mode, java.util.List<CloneOptions> options)
IVirtualBox.createMachine(String,String,List,String,String)
, and all the settings will be
transferred except the VM name and the hardware UUID. You can set the
VM name and the new hardware UUID when creating the target machine. The
network MAC addresses are newly created for all network adapters. You
can change that behaviour with the options parameter. The operation is
performed asynchronously, so the machine object will be not be usable
until the progress object signals completion.
target
- Target machine object.mode
- Which states should be cloned.options
- Options for the cloning operation.
E_INVALIDARG | target is null. |
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. |
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,Boolean,Holder)
public void adoptSavedState(java.lang.String savedStateFile)
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 usingadoptSavedState(String)
.
The location of the file can be found in thegetStateFilePath()
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 IProgress takeSnapshot(java.lang.String name, java.lang.String description, java.lang.Boolean pause, Holder<java.lang.String> id)
ISnapshot
for an introduction to snapshots.
This method can be called for a PoweredOff, Saved (seesaveState()
), 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 thegetCurrentSnapshot()
of the associated virtual machine and becomes a new current snapshot.
name
- Short name for the snapshot.description
- Optional description of the snapshot.pause
- Whether the VM should be paused while taking the snapshot. Only
relevant when the VM is running, and distinguishes between online
( true) and live ( false) snapshots. When the VM is not running
the result is always an offline snapshot.id
- UUID of the snapshot which will be created. Useful for follow-up
operations after the snapshot has been created.
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine currently changing state. |
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 callsaveSettings()
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.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 withdeleteSnapshot(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)
. SeeISnapshot
for an introduction to snapshots. The
conditions and many details are the same as withdeleteSnapshot(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
theMachineState.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 ifdiscardSavedState(Boolean)
were
called).public void applyDefaults(java.lang.String flags)
flags
- Additional flags, to be defined later.
Expected result codes:
E_NOTIMPL | This method is not implemented yet. |
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |