org.virtualbox_7_0
Class IMachine

java.lang.Object
  extended by org.virtualbox_7_0.IUnknown
      extended by org.virtualbox_7_0.IMachine

public class IMachine
extends IUnknown

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; seeISessionfor 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_7_0.ISession,org.virtualbox_7_0.LockType)orlaunchVMProcess(org.virtualbox_7_0.ISession,String,List)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 theISessioninterface 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.

See Also:
ISession, Interface ID: {300763AF-5D6B-46E6-AA96-273EAC15538A}

Field Summary
 
Fields inherited from class org.virtualbox_7_0.IUnknown
obj, objMgr, port
 
Constructor Summary
IMachine(java.lang.String wrapped, org.virtualbox_7_0.ObjectRefManager objMgr, org.virtualbox_7_0.jaxws.VboxPortType port)
           
 
Method Summary
 void addEncryptionPassword(java.lang.String id, java.lang.String password)
          Adds a password used for encryption.
 void addEncryptionPasswords(java.util.List<java.lang.String> ids, java.util.List<java.lang.String> passwords)
          Adds passwords used for encryption.
 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 ofIStorageController.
 IUSBController addUSBController(java.lang.String name, USBControllerType type)
          Adds a new USB controller to the machine and returns it as an instance ofIUSBController.
 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 changeEncryption(java.lang.String currentPassword, java.lang.String cipher, java.lang.String newPassword, java.lang.String newPasswordId, java.lang.Boolean force)
          Starts encryption of this VM.
 void checkEncryptionPassword(java.lang.String password)
          Checks whether the supplied password is correct for the VM.
 void clearAllEncryptionPasswords()
          Clears all provided VM passwords.
 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, java.lang.String autoMountPoint)
          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 bysaveState()) or in the "AbortedSaved" state.
 void discardSettings()
          Discards any changes to the machine settings made since the session has been opened or since the last call tosaveSettings()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, timestamps 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.
 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.
 IAudioSettings getAudioSettings()
          The machine's audio settings.
 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.
 java.lang.Boolean getClipboardFileTransfersEnabled()
          Sets or retrieves whether clipboard file transfers are allowed or not.
 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 idx, java.lang.Long idxSub, 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.
 void getCPUIDLeafByOrdinal(java.lang.Long ordinal, Holder<java.lang.Long> idx, Holder<java.lang.Long> idxSub, Holder<java.lang.Long> valEax, Holder<java.lang.Long> valEbx, Holder<java.lang.Long> valEcx, Holder<java.lang.Long> valEdx)
          Used to enumerate CPUID information override values.
 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.String getCPUProfile()
          Experimental feature to select the guest CPU profile.
 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 thelaunchVMProcess(org.virtualbox_7_0.ISession,String,List)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()
           
 void getEncryptionSettings(Holder<java.lang.String> cipher, Holder<java.lang.String> passwordId)
          Returns the encryption settings for this VM.
 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.
 FirmwareType getFirmwareType()
          Type of firmware (such as legacy BIOS or EFI), used for initial bootstrap in this VM.
 IGraphicsAdapter getGraphicsAdapter()
          Graphics adapter object.
 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.
 IGuestDebugControl getGuestDebugControl()
          Guest debugging configuration.
 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.
 IommuType getIommuType()
          IOMMU type used in this VM.
 KeyboardHIDType getKeyboardHIDType()
          Type of keyboard HID used in this VM.
 java.lang.Long getLastStateChange()
          Timestamp 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.
 java.lang.String getLogKeyId()
          Key Id of the password used for encrypting the log files.
 java.lang.String getLogKeyStore()
          Key store used for encrypting the log files.
 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.String getName()
          Name of the virtual machine.
 INetworkAdapter getNetworkAdapter(java.lang.Long slot)
          Returns the network adapter associated with the given slot.
 INvramStore getNonVolatileStore()
          Object to manipulate data in the non volatile storage file.
 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.
 java.lang.String getParavirtDebug()
          Debug parameters for the paravirtualized guest interface provider.
 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 useIConsole.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.
 IRecordingSettings getRecordingSettings()
          Object containing all recording settings.
 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 getSettingsAuxFilePath()
          Full name of the file containing auxiliary machine settings data.
 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 either theMachineState.SavedorMachineState.AbortedSavedstate.
 java.lang.String getStateKeyId()
          Key Id of the password used for encrypting the state file.
 java.lang.String getStateKeyStore()
          Key store used for encrypting the state file.
 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 whengetTracingEnabled()is true.
 java.lang.Boolean getTracingEnabled()
          Enables the tracing facility in the VMM (including PDM devices + drivers).
 ITrustedPlatformModule getTrustedPlatformModule()
          Object containing all TPM settings.
 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 a USB proxy available.
 VMProcPriority getVMProcessPriority()
          Sets the priority of the VM process.
 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.util.List<java.lang.String> environmentChanges)
          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.
 IProgress moveTo(java.lang.String folder, java.lang.String type)
          Move machine on to new place/folder
 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 idx, java.lang.Long idxSub)
          Removes the virtual CPU cpuid leaf for the specified index
 void removeEncryptionPassword(java.lang.String id)
          Removes a password used for the VM encryption/decryption.
 void removeSharedFolder(java.lang.String name)
          Removes the permanent shared folder with the given name previously created bycreateSharedFolder(String,String,Boolean,Boolean,String)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 tosaveSettings()ordiscardSettings().
 IProgress saveState()
          Saves the current execution state of a running virtual machine and stops its execution.
 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 setClipboardFileTransfersEnabled(java.lang.Boolean value)
          Sets or retrieves whether clipboard file transfers are allowed or not.
 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 idx, java.lang.Long idxSub, 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 setCPUProfile(java.lang.String value)
          Experimental feature to select the guest CPU profile.
 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 thelaunchVMProcess(org.virtualbox_7_0.ISession,String,List)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 setFirmwareType(FirmwareType value)
          Type of firmware (such as legacy BIOS or EFI), used for initial bootstrap in this VM.
 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 setIommuType(IommuType value)
          IOMMU type used in this VM.
 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 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 setParavirtDebug(java.lang.String value)
          Debug parameters for the paravirtualized guest interface provider.
 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 whengetTracingEnabled()is true.
 void setTracingEnabled(java.lang.Boolean value)
          Enables the tracing facility in the VMM (including PDM devices + drivers).
 void setVMProcessPriority(VMProcPriority value)
          Sets the priority of the VM process.
 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 withIVirtualBox.registerMachine(org.virtualbox_7_0.IMachine)and optionally do additional cleanup before the machine is unregistered.
 
Methods inherited from class org.virtualbox_7_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

IMachine

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

getParent

public IVirtualBox getParent()
Associated parent object.

Returns:
org.virtualbox_7_0.IVirtualBox

getIcon

public byte[] getIcon()
Overridden VM Icon details.

Returns:
byte[]

setIcon

public void setIcon(byte[] value)
Overridden VM Icon details.

Parameters:
value - byte[]

getAccessible

public java.lang.Boolean getAccessible()
Whether this virtual machine is currently accessible or not. A machine is always deemed accessible unless it is registeredandits settings file cannot be read or parsed (either because the file itself is unavailable or has invalid XML contents). Every time this property is read, the accessibility state of this machine is re-evaluated. If the returned value is false, thegetAccessError()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_7_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.

Returns:
Boolean

getAccessError

public IVirtualBoxErrorInfo getAccessError()
Error information describing the reason of machine inaccessibility. Reading this property is only valid after the last call togetAccessible()returned false (i.e. the machine is currently inaccessible). Otherwise, a null IVirtualBoxErrorInfo object will be returned.

Returns:
org.virtualbox_7_0.IVirtualBoxErrorInfo

getName

public java.lang.String getName()
Name of the virtual machine. Besides being used for human-readable identification purposes everywhere in VirtualBox, the virtual machine name is also used as a name of the machine's settings file and as a name of the subdirectory this settings file resides in. Thus, every time you change the value of this property, the settings file will be renamed once you callsaveSettings()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:If any of the above limitations are hit,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.)

Returns:
String

setName

public void setName(java.lang.String value)
Name of the virtual machine. Besides being used for human-readable identification purposes everywhere in VirtualBox, the virtual machine name is also used as a name of the machine's settings file and as a name of the subdirectory this settings file resides in. Thus, every time you change the value of this property, the settings file will be renamed once you callsaveSettings()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:If any of the above limitations are hit,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.)

Parameters:
value - String

getDescription

public java.lang.String getDescription()
Description of the virtual machine. The description attribute can contain any text and is typically used to describe the hardware and software configuration of the virtual machine in detail (i.e. network settings, versions of the installed software and so on).

Returns:
String

setDescription

public void setDescription(java.lang.String value)
Description of the virtual machine. The description attribute can contain any text and is typically used to describe the hardware and software configuration of the virtual machine in detail (i.e. network settings, versions of the installed software and so on).

Parameters:
value - String

getId

public java.lang.String getId()
UUID of the virtual machine.

Returns:
String

getGroups

public 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. Each group is only listed once, however they are listed in no particular order and there is no guarantee that there are no gaps in the group hierarchy (i.e."/group","/group/subgroup/subsubgroup"is a valid result).

Returns:
List<String>

setGroups

public 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. Each group is only listed once, however they are listed in no particular order and there is no guarantee that there are no gaps in the group hierarchy (i.e."/group","/group/subgroup/subsubgroup"is a valid result).

Parameters:
value - List<String>

getOSTypeId

public java.lang.String getOSTypeId()
User-defined identifier of the Guest OS type. You may useIVirtualBox.getGuestOSType(String)to obtain an IGuestOSType object representing details about the given Guest OS type. All Guest OS types are considered valid, even those which are not known toIVirtualBox.getGuestOSType(String). NOTE: This value may differ from the value returned byIGuest.getOSTypeId()if Guest Additions are installed to the guest OS.

Returns:
String

setOSTypeId

public void setOSTypeId(java.lang.String value)
User-defined identifier of the Guest OS type. You may useIVirtualBox.getGuestOSType(String)to obtain an IGuestOSType object representing details about the given Guest OS type. All Guest OS types are considered valid, even those which are not known toIVirtualBox.getGuestOSType(String). NOTE: This value may differ from the value returned byIGuest.getOSTypeId()if Guest Additions are installed to the guest OS.

Parameters:
value - String

getHardwareVersion

public java.lang.String getHardwareVersion()
Hardware version identifier. Internal use only for now.

Returns:
String

setHardwareVersion

public void setHardwareVersion(java.lang.String value)
Hardware version identifier. Internal use only for now.

Parameters:
value - String

getHardwareUUID

public java.lang.String getHardwareUUID()
The UUID presented to the guest via memory tables, hardware and guest properties. For most VMs this is the same as the id, but for VMs which have been cloned or teleported it may be the same as the source VM. The latter is because the guest shouldn't notice that it was cloned or teleported.

Returns:
String

setHardwareUUID

public void setHardwareUUID(java.lang.String value)
The UUID presented to the guest via memory tables, hardware and guest properties. For most VMs this is the same as the id, but for VMs which have been cloned or teleported it may be the same as the source VM. The latter is because the guest shouldn't notice that it was cloned or teleported.

Parameters:
value - String

getCPUCount

public java.lang.Long getCPUCount()
Number of virtual CPUs in the VM.

Returns:
Long

setCPUCount

public void setCPUCount(java.lang.Long value)
Number of virtual CPUs in the VM.

Parameters:
value - Long

getCPUHotPlugEnabled

public java.lang.Boolean getCPUHotPlugEnabled()
This setting determines whether VirtualBox allows CPU hotplugging for this machine.

Returns:
Boolean

setCPUHotPlugEnabled

public void setCPUHotPlugEnabled(java.lang.Boolean value)
This setting determines whether VirtualBox allows CPU hotplugging for this machine.

Parameters:
value - Boolean

getCPUExecutionCap

public java.lang.Long getCPUExecutionCap()
Means to limit the number of CPU cycles a guest can use. The unit is percentage of host CPU cycles per second. The valid range is 1 - 100. 100 (the default) implies no limit.

Returns:
Long

setCPUExecutionCap

public void setCPUExecutionCap(java.lang.Long value)
Means to limit the number of CPU cycles a guest can use. The unit is percentage of host CPU cycles per second. The valid range is 1 - 100. 100 (the default) implies no limit.

Parameters:
value - Long

getCPUIDPortabilityLevel

public 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). The default level of zero (0) means that all virtualized features supported by the host is pass thru to the guest. While the three (3) is currently the level supressing the most features. Exactly which of the CPUID features are left out by the VMM at which level is subject to change with each major version.

Returns:
Long

setCPUIDPortabilityLevel

public 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). The default level of zero (0) means that all virtualized features supported by the host is pass thru to the guest. While the three (3) is currently the level supressing the most features. Exactly which of the CPUID features are left out by the VMM at which level is subject to change with each major version.

Parameters:
value - Long

getMemorySize

public java.lang.Long getMemorySize()
System memory size in megabytes.

Returns:
Long

setMemorySize

public void setMemorySize(java.lang.Long value)
System memory size in megabytes.

Parameters:
value - Long

getMemoryBalloonSize

public java.lang.Long getMemoryBalloonSize()
Memory balloon size in megabytes.

Returns:
Long

setMemoryBalloonSize

public void setMemoryBalloonSize(java.lang.Long value)
Memory balloon size in megabytes.

Parameters:
value - Long

getPageFusionEnabled

public java.lang.Boolean getPageFusionEnabled()
This setting determines whether VirtualBox allows page fusion for this machine (64-bit hosts only).

Returns:
Boolean

setPageFusionEnabled

public void setPageFusionEnabled(java.lang.Boolean value)
This setting determines whether VirtualBox allows page fusion for this machine (64-bit hosts only).

Parameters:
value - Boolean

getGraphicsAdapter

public IGraphicsAdapter getGraphicsAdapter()
Graphics adapter object.

Returns:
org.virtualbox_7_0.IGraphicsAdapter

getBIOSSettings

public IBIOSSettings getBIOSSettings()
Object containing all BIOS settings.

Returns:
org.virtualbox_7_0.IBIOSSettings

getTrustedPlatformModule

public ITrustedPlatformModule getTrustedPlatformModule()
Object containing all TPM settings.

Returns:
org.virtualbox_7_0.ITrustedPlatformModule

getNonVolatileStore

public INvramStore getNonVolatileStore()
Object to manipulate data in the non volatile storage file.

Returns:
org.virtualbox_7_0.INvramStore

getRecordingSettings

public IRecordingSettings getRecordingSettings()
Object containing all recording settings.

Returns:
org.virtualbox_7_0.IRecordingSettings

getFirmwareType

public FirmwareType getFirmwareType()
Type of firmware (such as legacy BIOS or EFI), used for initial bootstrap in this VM.

Returns:
org.virtualbox_7_0.FirmwareType

setFirmwareType

public void setFirmwareType(FirmwareType value)
Type of firmware (such as legacy BIOS or EFI), used for initial bootstrap in this VM.

Parameters:
value - org.virtualbox_7_0.FirmwareType

getPointingHIDType

public PointingHIDType getPointingHIDType()
Type of pointing HID (such as mouse or tablet) used in this VM. The default is typically "PS2Mouse" but can vary depending on the requirements of the guest operating system.

Returns:
org.virtualbox_7_0.PointingHIDType

setPointingHIDType

public void setPointingHIDType(PointingHIDType value)
Type of pointing HID (such as mouse or tablet) used in this VM. The default is typically "PS2Mouse" but can vary depending on the requirements of the guest operating system.

Parameters:
value - org.virtualbox_7_0.PointingHIDType

getKeyboardHIDType

public KeyboardHIDType getKeyboardHIDType()
Type of keyboard HID used in this VM. The default is typically "PS2Keyboard" but can vary depending on the requirements of the guest operating system.

Returns:
org.virtualbox_7_0.KeyboardHIDType

setKeyboardHIDType

public void setKeyboardHIDType(KeyboardHIDType value)
Type of keyboard HID used in this VM. The default is typically "PS2Keyboard" but can vary depending on the requirements of the guest operating system.

Parameters:
value - org.virtualbox_7_0.KeyboardHIDType

getHPETEnabled

public java.lang.Boolean getHPETEnabled()
This attribute controls if High Precision Event Timer (HPET) is enabled in this VM. Use this property if you want to provide guests with additional time source, or if guest requires HPET to function correctly. Default is false.

Returns:
Boolean

setHPETEnabled

public void setHPETEnabled(java.lang.Boolean value)
This attribute controls if High Precision Event Timer (HPET) is enabled in this VM. Use this property if you want to provide guests with additional time source, or if guest requires HPET to function correctly. Default is false.

Parameters:
value - Boolean

getChipsetType

public ChipsetType getChipsetType()
Chipset type used in this VM.

Returns:
org.virtualbox_7_0.ChipsetType

setChipsetType

public void setChipsetType(ChipsetType value)
Chipset type used in this VM.

Parameters:
value - org.virtualbox_7_0.ChipsetType

getIommuType

public IommuType getIommuType()
IOMMU type used in this VM.

Returns:
org.virtualbox_7_0.IommuType

setIommuType

public void setIommuType(IommuType value)
IOMMU type used in this VM.

Parameters:
value - org.virtualbox_7_0.IommuType

getSnapshotFolder

public java.lang.String getSnapshotFolder()
Full path to the directory used to store snapshot data (differencing media and saved state files) of this machine. The initial value of this property is<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.

Returns:
String

setSnapshotFolder

public 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. The initial value of this property is<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.

Parameters:
value - String

getVRDEServer

public IVRDEServer getVRDEServer()
VirtualBox Remote Desktop Extension (VRDE) server object.

Returns:
org.virtualbox_7_0.IVRDEServer

getEmulatedUSBCardReaderEnabled

public java.lang.Boolean getEmulatedUSBCardReaderEnabled()

setEmulatedUSBCardReaderEnabled

public void setEmulatedUSBCardReaderEnabled(java.lang.Boolean value)

getMediumAttachments

public java.util.List<IMediumAttachment> getMediumAttachments()
Array of media attached to this machine.

Returns:
List<org.virtualbox_7_0.IMediumAttachment>

getUSBControllers

public java.util.List<IUSBController> getUSBControllers()
Array of USB controllers attached to this machine. NOTE: If USB functionality is not available in the given edition of VirtualBox, this method will set the result code to E_NOTIMPL.

Returns:
List<org.virtualbox_7_0.IUSBController>

getUSBDeviceFilters

public IUSBDeviceFilters getUSBDeviceFilters()
Associated USB device filters object. NOTE: If USB functionality is not available in the given edition of VirtualBox, this method will set the result code to E_NOTIMPL.

Returns:
org.virtualbox_7_0.IUSBDeviceFilters

getAudioSettings

public IAudioSettings getAudioSettings()
The machine's audio settings.

Returns:
org.virtualbox_7_0.IAudioSettings

getStorageControllers

public java.util.List<IStorageController> getStorageControllers()
Array of storage controllers attached to this machine.

Returns:
List<org.virtualbox_7_0.IStorageController>

getSettingsFilePath

public java.lang.String getSettingsFilePath()
Full name of the file containing machine settings data.

Returns:
String

getSettingsAuxFilePath

public java.lang.String getSettingsAuxFilePath()
Full name of the file containing auxiliary machine settings data.

Returns:
String

getSettingsModified

public java.lang.Boolean getSettingsModified()
Whether the settings of this machine have been modified (but neither yet saved nor discarded). NOTE: Reading this property is only valid on instances returned byISession.getMachine()and on new machines created byIVirtualBox.createMachine(String,String,List,String,String,String,String,String)or opened byIVirtualBox.openMachine(String,String)but not yet registered, or on unregistered machines after callingunregister(org.virtualbox_7_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).

Returns:
Boolean

getSessionState

public SessionState getSessionState()
Current session state for this machine.

Returns:
org.virtualbox_7_0.SessionState

getSessionName

public java.lang.String getSessionName()
Name of the session. IfgetSessionState()is Spawning or Locked, this attribute contains the same value as passed to thelaunchVMProcess(org.virtualbox_7_0.ISession,String,List)method in the name parameter. If the session was established withlockMachine(org.virtualbox_7_0.ISession,org.virtualbox_7_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.

Returns:
String

getSessionPID

public java.lang.Long getSessionPID()
Identifier of the session process. This attribute contains the platform-dependent identifier of the process whose session was used withlockMachine(org.virtualbox_7_0.ISession,org.virtualbox_7_0.LockType)call. The returned value is only valid ifgetSessionState()is Locked or Unlocking by the time this property is read.

Returns:
Long

getState

public MachineState getState()
Current execution state of this machine.

Returns:
org.virtualbox_7_0.MachineState

getLastStateChange

public java.lang.Long getLastStateChange()
Timestamp of the last execution state change, in milliseconds since 1970-01-01 UTC.

Returns:
Long

getStateFilePath

public java.lang.String getStateFilePath()
Full path to the file that stores the execution state of the machine when it is in either theMachineState.SavedorMachineState.AbortedSavedstate. NOTE: When the machine is not in the Saved or AbortedSaved state, this attribute is an empty string.

Returns:
String

getLogFolder

public java.lang.String getLogFolder()
Full path to the folder that stores a set of rotated log files recorded during machine execution. The most recent log file is namedVBox.log, the previous log file is namedVBox.log.1and so on (up toVBox.log.3in the current version).

Returns:
String

getCurrentSnapshot

public ISnapshot getCurrentSnapshot()
Current snapshot of this machine. This is null if the machine currently has no snapshots. If it is not null, then it was set by one oftakeSnapshot(String,String,Boolean,Holder),deleteSnapshot(String)orrestoreSnapshot(org.virtualbox_7_0.ISnapshot), depending on which was called last. SeeISnapshotfor details.

Returns:
org.virtualbox_7_0.ISnapshot

getSnapshotCount

public java.lang.Long getSnapshotCount()
Number of snapshots taken on this machine. Zero means the machine doesn't have any snapshots.

Returns:
Long

getCurrentStateModified

public java.lang.Boolean getCurrentStateModified()
Returns true if the current state of the machine is not identical to the state stored in the current snapshot. The current state is identical to the current snapshot only directly after one of the following calls are made:The current state remains identical until one of the following happens: NOTE: For machines that don't have snapshots, this property is always false.

Returns:
Boolean

getSharedFolders

public java.util.List<ISharedFolder> getSharedFolders()
Collection of shared folders for this machine (permanent shared folders). These folders are shared automatically at machine startup and available only to the guest OS installed within this machine. New shared folders are added to the collection usingcreateSharedFolder(String,String,Boolean,Boolean,String). Existing shared folders can be removed usingremoveSharedFolder(String).

Returns:
List<org.virtualbox_7_0.ISharedFolder>

getClipboardMode

public ClipboardMode getClipboardMode()
Synchronization mode between the host OS clipboard and the guest OS clipboard.

Returns:
org.virtualbox_7_0.ClipboardMode

setClipboardMode

public void setClipboardMode(ClipboardMode value)
Synchronization mode between the host OS clipboard and the guest OS clipboard.

Parameters:
value - org.virtualbox_7_0.ClipboardMode

getClipboardFileTransfersEnabled

public java.lang.Boolean getClipboardFileTransfersEnabled()
Sets or retrieves whether clipboard file transfers are allowed or not. When set to true, clipboard file transfers between supported host and guest OSes are allowed.

Returns:
Boolean

setClipboardFileTransfersEnabled

public void setClipboardFileTransfersEnabled(java.lang.Boolean value)
Sets or retrieves whether clipboard file transfers are allowed or not. When set to true, clipboard file transfers between supported host and guest OSes are allowed.

Parameters:
value - Boolean

getDnDMode

public DnDMode getDnDMode()
Sets or retrieves the current drag'n drop mode.

Returns:
org.virtualbox_7_0.DnDMode

setDnDMode

public void setDnDMode(DnDMode value)
Sets or retrieves the current drag'n drop mode.

Parameters:
value - org.virtualbox_7_0.DnDMode

getTeleporterEnabled

public java.lang.Boolean getTeleporterEnabled()
When set to true, the virtual machine becomes a target teleporter the next time it is powered on. This can only set to true when the VM is in the PoweredOff or Aborted state.

Returns:
Boolean

setTeleporterEnabled

public void setTeleporterEnabled(java.lang.Boolean value)
When set to true, the virtual machine becomes a target teleporter the next time it is powered on. This can only set to true when the VM is in the PoweredOff or Aborted state.

Parameters:
value - Boolean

getTeleporterPort

public java.lang.Long getTeleporterPort()
The TCP port the target teleporter will listen for incoming teleportations on. 0 means the port is automatically selected upon power on. The actual value can be read from this property while the machine is waiting for incoming teleportations.

Returns:
Long

setTeleporterPort

public void setTeleporterPort(java.lang.Long value)
The TCP port the target teleporter will listen for incoming teleportations on. 0 means the port is automatically selected upon power on. The actual value can be read from this property while the machine is waiting for incoming teleportations.

Parameters:
value - Long

getTeleporterAddress

public java.lang.String getTeleporterAddress()
The address the target teleporter will listen on. If set to an empty string, it will listen on all addresses.

Returns:
String

setTeleporterAddress

public void setTeleporterAddress(java.lang.String value)
The address the target teleporter will listen on. If set to an empty string, it will listen on all addresses.

Parameters:
value - String

getTeleporterPassword

public java.lang.String getTeleporterPassword()
The password to check for on the target teleporter. This is just a very basic measure to prevent simple hacks and operators accidentally beaming a virtual machine to the wrong place. Note that you SET a plain text password while reading back a HASHED password. Setting a hashed password is currently not supported.

Returns:
String

setTeleporterPassword

public void setTeleporterPassword(java.lang.String value)
The password to check for on the target teleporter. This is just a very basic measure to prevent simple hacks and operators accidentally beaming a virtual machine to the wrong place. Note that you SET a plain text password while reading back a HASHED password. Setting a hashed password is currently not supported.

Parameters:
value - String

getParavirtProvider

public ParavirtProvider getParavirtProvider()
The paravirtualized guest interface provider.

Returns:
org.virtualbox_7_0.ParavirtProvider

setParavirtProvider

public void setParavirtProvider(ParavirtProvider value)
The paravirtualized guest interface provider.

Parameters:
value - org.virtualbox_7_0.ParavirtProvider

getRTCUseUTC

public java.lang.Boolean getRTCUseUTC()
When set to true, the RTC device of the virtual machine will run in UTC time, otherwise in local time. Especially Unix guests prefer the time in UTC.

Returns:
Boolean

setRTCUseUTC

public 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. Especially Unix guests prefer the time in UTC.

Parameters:
value - Boolean

getIOCacheEnabled

public java.lang.Boolean getIOCacheEnabled()
When set to true, the builtin I/O cache of the virtual machine will be enabled.

Returns:
Boolean

setIOCacheEnabled

public void setIOCacheEnabled(java.lang.Boolean value)
When set to true, the builtin I/O cache of the virtual machine will be enabled.

Parameters:
value - Boolean

getIOCacheSize

public java.lang.Long getIOCacheSize()
Maximum size of the I/O cache in MB.

Returns:
Long

setIOCacheSize

public void setIOCacheSize(java.lang.Long value)
Maximum size of the I/O cache in MB.

Parameters:
value - Long

getPCIDeviceAssignments

public java.util.List<IPCIDeviceAttachment> getPCIDeviceAssignments()
Array of PCI devices assigned to this machine, to get list of all PCI devices attached to the machine useIConsole.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.

Returns:
List<org.virtualbox_7_0.IPCIDeviceAttachment>

getBandwidthControl

public IBandwidthControl getBandwidthControl()
Bandwidth control manager.

Returns:
org.virtualbox_7_0.IBandwidthControl

getTracingEnabled

public java.lang.Boolean getTracingEnabled()
Enables the tracing facility in the VMM (including PDM devices + drivers). The VMM will consume about 0.5MB of more memory when enabled and there may be some extra overhead from tracepoints that are always enabled.

Returns:
Boolean

setTracingEnabled

public void setTracingEnabled(java.lang.Boolean value)
Enables the tracing facility in the VMM (including PDM devices + drivers). The VMM will consume about 0.5MB of more memory when enabled and there may be some extra overhead from tracepoints that are always enabled.

Parameters:
value - Boolean

getTracingConfig

public java.lang.String getTracingConfig()
Tracepoint configuration to apply at startup whengetTracingEnabled()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.

Returns:
String

setTracingConfig

public void setTracingConfig(java.lang.String value)
Tracepoint configuration to apply at startup whengetTracingEnabled()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.

Parameters:
value - String

getAllowTracingToAccessVM

public java.lang.Boolean getAllowTracingToAccessVM()
Enables tracepoints in PDM devices and drivers to use the VMCPU or VM structures when firing off trace points. This is especially useful with DTrace tracepoints, as it allows you to use the VMCPU or VM pointer to obtain useful information such as guest register state. This is disabled by default because devices and drivers normally has no business accessing the VMCPU or VM structures, and are therefore unable to get any pointers to these.

Returns:
Boolean

setAllowTracingToAccessVM

public 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. This is especially useful with DTrace tracepoints, as it allows you to use the VMCPU or VM pointer to obtain useful information such as guest register state. This is disabled by default because devices and drivers normally has no business accessing the VMCPU or VM structures, and are therefore unable to get any pointers to these.

Parameters:
value - Boolean

getAutostartEnabled

public java.lang.Boolean getAutostartEnabled()
Enables autostart of the VM during system boot.

Returns:
Boolean

setAutostartEnabled

public void setAutostartEnabled(java.lang.Boolean value)
Enables autostart of the VM during system boot.

Parameters:
value - Boolean

getAutostartDelay

public java.lang.Long getAutostartDelay()
Number of seconds to wait until the VM should be started during system boot.

Returns:
Long

setAutostartDelay

public void setAutostartDelay(java.lang.Long value)
Number of seconds to wait until the VM should be started during system boot.

Parameters:
value - Long

getAutostopType

public AutostopType getAutostopType()
Action type to do when the system is shutting down.

Returns:
org.virtualbox_7_0.AutostopType

setAutostopType

public void setAutostopType(AutostopType value)
Action type to do when the system is shutting down.

Parameters:
value - org.virtualbox_7_0.AutostopType

getDefaultFrontend

public java.lang.String getDefaultFrontend()
Selects which VM frontend should be used by default when launching this VM through thelaunchVMProcess(org.virtualbox_7_0.ISession,String,List)method. Empty or null strings do not define a particular default, it is up tolaunchVMProcess(org.virtualbox_7_0.ISession,String,List)to select one. See the description oflaunchVMProcess(org.virtualbox_7_0.ISession,String,List)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_7_0.ISession,String,List).

Returns:
String

setDefaultFrontend

public void setDefaultFrontend(java.lang.String value)
Selects which VM frontend should be used by default when launching this VM through thelaunchVMProcess(org.virtualbox_7_0.ISession,String,List)method. Empty or null strings do not define a particular default, it is up tolaunchVMProcess(org.virtualbox_7_0.ISession,String,List)to select one. See the description oflaunchVMProcess(org.virtualbox_7_0.ISession,String,List)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_7_0.ISession,String,List).

Parameters:
value - String

getUSBProxyAvailable

public java.lang.Boolean getUSBProxyAvailable()
Returns whether there is a USB proxy available.

Returns:
Boolean

getVMProcessPriority

public VMProcPriority getVMProcessPriority()
Sets the priority of the VM process. It is a VM setting which can be changed both before starting the VM and at runtime. The default value is 'Default', which selects the default process priority.

Expected result codes:
E_NOTIMPL - This attribute is currently not implemented.

Returns:
org.virtualbox_7_0.VMProcPriority

setVMProcessPriority

public void setVMProcessPriority(VMProcPriority value)
Sets the priority of the VM process. It is a VM setting which can be changed both before starting the VM and at runtime. The default value is 'Default', which selects the default process priority.

Expected result codes:
E_NOTIMPL - This attribute is currently not implemented.

Parameters:
value - org.virtualbox_7_0.VMProcPriority

getParavirtDebug

public java.lang.String getParavirtDebug()
Debug parameters for the paravirtualized guest interface provider.

Returns:
String

setParavirtDebug

public void setParavirtDebug(java.lang.String value)
Debug parameters for the paravirtualized guest interface provider.

Parameters:
value - String

getCPUProfile

public java.lang.String getCPUProfile()
Experimental feature to select the guest CPU profile. The default is "host", which indicates the host CPU. All other names are subject to change. Use theISystemProperties.getCPUProfiles(org.virtualbox_7_0.CPUArchitecture,String)method to get currently available CPU profiles.

Returns:
String

setCPUProfile

public void setCPUProfile(java.lang.String value)
Experimental feature to select the guest CPU profile. The default is "host", which indicates the host CPU. All other names are subject to change. Use theISystemProperties.getCPUProfiles(org.virtualbox_7_0.CPUArchitecture,String)method to get currently available CPU profiles.

Parameters:
value - String

getStateKeyId

public java.lang.String getStateKeyId()
Key Id of the password used for encrypting the state file. Internal use only for now.

Returns:
String

getStateKeyStore

public java.lang.String getStateKeyStore()
Key store used for encrypting the state file. Internal use only for now.

Returns:
String

getLogKeyId

public java.lang.String getLogKeyId()
Key Id of the password used for encrypting the log files. Internal use only for now.

Returns:
String

getLogKeyStore

public java.lang.String getLogKeyStore()
Key store used for encrypting the log files. Internal use only for now.

Returns:
String

getGuestDebugControl

public IGuestDebugControl getGuestDebugControl()
Guest debugging configuration.

Returns:
org.virtualbox_7_0.IGuestDebugControl

queryInterface

public static IMachine queryInterface(IUnknown obj)

lockMachine

public 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. There are two ways to lock a machine for such uses:In either case, you can get access to theIConsoleobject 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:
  1. Call this method to obtain an exclusive write lock for the current session.
  2. Obtain a mutable IMachine object fromISession.getMachine().
  3. Change the settings of the machine by invoking IMachine methods.
  4. CallsaveSettings().
  5. Release the write lock by callingISession.unlockMachine().

Expected result codes:
E_UNEXPECTED - Virtual machine not registered.
E_ACCESSDENIED - Process not started bylaunchVMProcess(org.virtualbox_7_0.ISession,String,List).
VBOX_E_INVALID_OBJECT_STATE - Session already open or being opened.
VBOX_E_VM_ERROR - Failed to assign machine to session.

Parameters:
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.

launchVMProcess

public IProgress launchVMProcess(ISession session,
                                 java.lang.String name,
                                 java.util.List<java.lang.String> environmentChanges)
Spawns a new process that will execute the virtual machine and obtains a shared lock on the machine for the calling session. If launching the VM succeeds, the new VM process will create its own session and write-lock the machine for it, preventing conflicting changes from other processes. If the machine is already locked (because it is already running or because another session has a write lock), launching the VM process will therefore fail. Reversely, future attempts to obtain a write lock will also fail while the machine is running. The caller's session object remains separate from the session opened by the new VM process. It receives its ownIConsoleobject 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_7_0.ISession,org.virtualbox_7_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, anIProgressobject 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 environmentChanges argument is a list of strings where every string contains environment variable in the putenv style, i.e. "VAR=VALUE" for setting/replacing and "VAR" for unsetting. These environment variables will be applied 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 list is empty, the server environment is inherited by the started process as is.

Expected result codes:
E_UNEXPECTED - Virtual machine not registered.
E_INVALIDARG - Invalid session type type.
VBOX_E_OBJECT_NOT_FOUND - No machine matching machineId found.
VBOX_E_INVALID_OBJECT_STATE - Session already open or being opened.
VBOX_E_IPRT_ERROR - Launching process for machine failed.
VBOX_E_VM_ERROR - Failed to assign machine to session.

Parameters:
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:
  • "gui": VirtualBox Qt GUI front-end
  • "headless": VBoxHeadless (VRDE Server) front-end
  • "sdl": VirtualBox SDL front-end
  • "emergencystop": reserved value, used for aborting the currently running VM or session owner. In this case the session parameter may be null (if it is non-null it isn't used in any way), and the progress return value will be always null. The operation completes immediately.
  • "": use the per-VM default frontend if set, otherwise the global default defined in the system properties. If neither are set, the API will launch a"gui"session, which may fail if there is no windowing environment available. SeegetDefaultFrontend()andISystemProperties.getDefaultFrontend().
environmentChanges - The list of putenv-style changes to the VM process environment.
Returns:
Progress object to track the operation completion.

setBootOrder

public void setBootOrder(java.lang.Long position,
                         DeviceType device)
Puts the given device to the specified position in the boot order. To indicate that no device is associated with the given position,DeviceType.Nullshould be used. TODO setHardDiskBootOrder(), setNetworkBootOrder()

Expected result codes:
E_INVALIDARG - Boot position out of range.
E_NOTIMPL - Booting from USB device currently not supported.

Parameters:
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.

getBootOrder

public DeviceType getBootOrder(java.lang.Long position)
Returns the device type that occupies the specified position in the boot order. TODO [remove?] If the machine can have more than one device of the returned type (such as hard disks), then a separate method should be used to retrieve the individual device that occupies the given position. If here are no devices at the given position, thenDeviceType.Nullis returned. TODO getHardDiskBootOrder(), getNetworkBootOrder()

Expected result codes:
E_INVALIDARG - Boot position out of range.

Parameters:
position - Position in the boot order ( 1 to the total number of devices the machine can boot from, as returned byISystemProperties.getMaxBootPosition()).
Returns:
Device at the given position.

attachDevice

public 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. 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:In a VM's default configuration of virtual machines, the secondary master of the IDE controller is used for a CD/DVD drive. After calling this returns successfully, a new instance ofIMediumAttachmentwill appear in the machine's list of medium attachments (seegetMediumAttachments()). SeeIMediumandIMediumAttachmentfor more information about attaching media. The specified device slot must not have a device attached to it, or this method will fail.

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range, or file or UUID not found.
VBOX_E_INVALID_OBJECT_STATE - Machine must be registered before media can be attached.
VBOX_E_INVALID_VM_STATE - Invalid machine state.
VBOX_E_OBJECT_IN_USE - A medium is already attached to this or another virtual machine.

Parameters:
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_7_0.DeviceType,org.virtualbox_7_0.AccessMode,Boolean), this must match the device type specified there.
medium - Medium to mount or null for an empty drive. NOTE: You cannot attach a device to a newly created machine until this machine's settings are saved to disk usingsaveSettings(). 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.

attachDeviceWithoutMedium

public 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. 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:In a VM's default configuration of virtual machines, the secondary master of the IDE controller is used for a CD/DVD drive.IMediumAttachmentwill appear in the machine's list of medium attachments (seegetMediumAttachments()). SeeIMediumandIMediumAttachmentfor more information about attaching media. The specified device slot must not have a device attached to it, or this method will fail.

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range, or file or UUID not found.
VBOX_E_INVALID_OBJECT_STATE - Machine must be registered before media can be attached.
VBOX_E_INVALID_VM_STATE - Invalid machine state.
VBOX_E_OBJECT_IN_USE - A medium is already attached to this or another virtual machine.

Parameters:
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_7_0.DeviceType,org.virtualbox_7_0.AccessMode,Boolean), this must match the device type specified there. NOTE: You cannot attach a device to a newly created machine until this machine's settings are saved to disk usingsaveSettings(). 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.

detachDevice

public 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. Detaching the device from the virtual machine is deferred. This means that the medium remains associated with the machine when this method returns and gets actually de-associated only after a successfulsaveSettings()call. SeeIMediumfor more detailed information about attaching media.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Attempt to detach medium from a running virtual machine.
VBOX_E_OBJECT_NOT_FOUND - No medium attached to given slot/bus.
VBOX_E_NOT_SUPPORTED - Medium format does not support storage deletion (only for implicitly created differencing media, should not happen).

Parameters:
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. NOTE: You cannot detach a device from a running machine. NOTE: Detaching differencing media implicitly created byattachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_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.

passthroughDevice

public 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. Changing the setting while the VM is running is forbidden. The setting is only used if at VM start the device is configured as a host DVD drive, in all other cases it is ignored. The device must already exist; seeattachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_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_7_0.DeviceType,org.virtualbox_7_0.IMedium).

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range.
VBOX_E_INVALID_OBJECT_STATE - Attempt to modify an unregistered virtual machine.
VBOX_E_INVALID_VM_STATE - Invalid machine state.

Parameters:
name - Name of the storage controller.
controllerPort - Storage controller port.
device - Device slot in the given port.
passthrough - New value for the passthrough setting.

temporaryEjectDevice

public 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. In some situations it is desirable that such ejects update the VM configuration, and in others the eject should keep the VM configuration. The device must already exist; seeattachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_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_7_0.DeviceType,org.virtualbox_7_0.IMedium).

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range.
VBOX_E_INVALID_OBJECT_STATE - Attempt to modify an unregistered virtual machine.
VBOX_E_INVALID_VM_STATE - Invalid machine state.

Parameters:
name - Name of the storage controller.
controllerPort - Storage controller port.
device - Device slot in the given port.
temporaryEject - New value for the eject behavior.

nonRotationalDevice

public 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. that the access times are more or less independent of the position on the medium. This may or may not be supported by a particular drive, and is silently ignored in the latter case. At the moment only hard disks (which is a misnomer in this context) accept this setting. Changing the setting while the VM is running is forbidden. The device must already exist; seeattachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_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_7_0.DeviceType,org.virtualbox_7_0.IMedium).

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range.
VBOX_E_INVALID_OBJECT_STATE - Attempt to modify an unregistered virtual machine.
VBOX_E_INVALID_VM_STATE - Invalid machine state.

Parameters:
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.

setAutoDiscardForDevice

public 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. At the moment only hard disks (which is a misnomer in this context) accept this setting. Changing the setting while the VM is running is forbidden. The device must already exist; seeattachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_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_7_0.DeviceType,org.virtualbox_7_0.IMedium).

Expected result codes:
E_INVALIDARG - SATA device, SATA port, SCSI port out of range.
VBOX_E_INVALID_OBJECT_STATE - Attempt to modify an unregistered virtual machine.
VBOX_E_INVALID_VM_STATE - Invalid machine state.

Parameters:
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.

setHotPluggableForDevice

public 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. This may or may not be supported by a particular controller and/or drive, and is silently ignored in the latter case. Changing the setting while the VM is running is forbidden. The device must already exist; seeattachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_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_7_0.DeviceType,org.virtualbox_7_0.IMedium).

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range.
VBOX_E_INVALID_OBJECT_STATE - Attempt to modify an unregistered virtual machine.
VBOX_E_INVALID_VM_STATE - Invalid machine state.
VBOX_E_NOT_SUPPORTED - Controller doesn't support hot plugging.

Parameters:
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.

setBandwidthGroupForDevice

public 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. The device must already exist; seeattachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_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_7_0.DeviceType,org.virtualbox_7_0.IMedium).

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range.
VBOX_E_INVALID_OBJECT_STATE - Attempt to modify an unregistered virtual machine.
VBOX_E_INVALID_VM_STATE - Invalid machine state.

Parameters:
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.

setNoBandwidthGroupForDevice

public void setNoBandwidthGroupForDevice(java.lang.String name,
                                         java.lang.Integer controllerPort,
                                         java.lang.Integer device)
Sets no bandwidth group for an existing storage device. The device must already exist; seeattachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_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_7_0.DeviceType,org.virtualbox_7_0.IMedium).

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range.
VBOX_E_INVALID_OBJECT_STATE - Attempt to modify an unregistered virtual machine.
VBOX_E_INVALID_VM_STATE - Invalid machine state.

Parameters:
name - Name of the storage controller.
controllerPort - Storage controller port.
device - Device slot in the given port.

unmountMedium

public 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. 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_7_0.DeviceType,org.virtualbox_7_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. SeeIMediumfor more detailed information about attaching/unmounting media.

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range.
VBOX_E_INVALID_OBJECT_STATE - Attempt to unmount medium that is not removable - not DVD or floppy.
VBOX_E_INVALID_VM_STATE - Invalid machine state.
VBOX_E_OBJECT_IN_USE - Medium already attached to this or another virtual machine.
VBOX_E_OBJECT_NOT_FOUND - Medium not attached to specified port, device, controller.

Parameters:
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.

mountMedium

public 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. The device must already exist; seeattachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_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_7_0.DeviceType,org.virtualbox_7_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. SeeIMediumfor more detailed information about attaching media.

Expected result codes:
E_INVALIDARG - SATA device, SATA port, IDE port or IDE slot out of range.
VBOX_E_INVALID_OBJECT_STATE - Attempt to attach medium to an unregistered virtual machine.
VBOX_E_INVALID_VM_STATE - Invalid machine state.
VBOX_E_OBJECT_IN_USE - Medium already attached to this or another virtual machine.

Parameters:
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.

getMedium

public 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. Note that if the medium was indirectly attached bymountMedium(String,Integer,Integer,org.virtualbox_7_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_7_0.IMedium,Boolean)call. SeeIMediumfor more detailed information about mounting a medium.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - No medium attached to given slot/bus.

Parameters:
name - Name of the storage controller the medium is attached to.
controllerPort - Port to query.
device - Device slot in the given port to query.
Returns:
Attached medium object.

getMediumAttachmentsOfController

public 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.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - A storage controller with given name doesn't exist.


getMediumAttachment

public 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.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - No attachment exists for the given controller/port/device combination.


attachHostPCIDevice

public 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. Please note, that this operation is two phase, as real attachment will happen when VM will start, and most information will be delivered as IHostPCIDevicePlugEvent on IVirtualBox event source.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Virtual machine state is not stopped (PCI hotplug not yet implemented).
VBOX_E_PDM_ERROR - Virtual machine does not have a PCI controller allowing attachment of physical devices.
VBOX_E_NOT_SUPPORTED - Hardware or host OS doesn't allow PCI device passthrough.

Parameters:
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.
See Also:
IHostPCIDevicePlugEvent

detachHostPCIDevice

public void detachHostPCIDevice(java.lang.Integer hostAddress)
Detach host PCI device from the virtual machine. Also HostPCIDevicePlugEvent on IVirtualBox event source will be delivered. As currently we don't support hot device unplug, IHostPCIDevicePlugEvent event is delivered immediately.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Virtual machine state is not stopped (PCI hotplug not yet implemented).
VBOX_E_OBJECT_NOT_FOUND - This host device is not attached to this machine.
VBOX_E_PDM_ERROR - Virtual machine does not have a PCI controller allowing attachment of physical devices.
VBOX_E_NOT_SUPPORTED - Hardware or host OS doesn't allow PCI device passthrough.

Parameters:
hostAddress - Address of the host PCI device.
See Also:
IHostPCIDevicePlugEvent

getNetworkAdapter

public INetworkAdapter getNetworkAdapter(java.lang.Long slot)
Returns the network adapter associated with the given slot. Slots are numbered sequentially, starting with zero. The total number of adapters per machine is defined by theISystemProperties.getMaxNetworkAdapters(org.virtualbox_7_0.ChipsetType)property, so the maximum slot number is one less than that property's value.

Expected result codes:
E_INVALIDARG - Invalid slot number.


addStorageController

public 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 ofIStorageController. name identifies the controller for subsequent calls such asgetStorageControllerByName(String),getStorageControllerByInstance(org.virtualbox_7_0.StorageBus,Long),removeStorageController(String),attachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_0.IMedium)ormountMedium(String,Integer,Integer,org.virtualbox_7_0.IMedium,Boolean). After the controller has been added, you can set its exact type by setting theIStorageController.getControllerType().

Expected result codes:
VBOX_E_OBJECT_IN_USE - A storage controller with given name exists already.
E_INVALIDARG - Invalid controllerType.


getStorageControllerByName

public IStorageController getStorageControllerByName(java.lang.String name)
Returns a storage controller with the given name.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - A storage controller with given name doesn't exist.


getStorageControllerByInstance

public IStorageController getStorageControllerByInstance(StorageBus connectionType,
                                                         java.lang.Long instance)
Returns a storage controller of a specific storage bus with the given instance number.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - A storage controller with given instance number doesn't exist.


removeStorageController

public void removeStorageController(java.lang.String name)
Removes a storage controller from the machine with all devices attached to it.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - A storage controller with given name doesn't exist.
VBOX_E_NOT_SUPPORTED - Medium format does not support storage deletion (only for implicitly created differencing media, should not happen).


setStorageControllerBootable

public void setStorageControllerBootable(java.lang.String name,
                                         java.lang.Boolean bootable)
Sets the bootable flag of the storage controller with the given name.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - A storage controller with given name doesn't exist.
VBOX_E_OBJECT_IN_USE - Another storage controller is marked as bootable already.


addUSBController

public IUSBController addUSBController(java.lang.String name,
                                       USBControllerType type)
Adds a new USB controller to the machine and returns it as an instance ofIUSBController.

Expected result codes:
VBOX_E_OBJECT_IN_USE - A USB controller with given type exists already.
E_INVALIDARG - Invalid controllerType.


removeUSBController

public void removeUSBController(java.lang.String name)
Removes a USB controller from the machine.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - A USB controller with given type doesn't exist.


getUSBControllerByName

public IUSBController getUSBControllerByName(java.lang.String name)
Returns a USB controller with the given type.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - A USB controller with given name doesn't exist.


getUSBControllerCountByType

public java.lang.Long getUSBControllerCountByType(USBControllerType type)
Returns the number of USB controllers of the given type attached to the VM.


getSerialPort

public ISerialPort getSerialPort(java.lang.Long slot)
Returns the serial port associated with the given slot. Slots are numbered sequentially, starting with zero. The total number of serial ports per machine is defined by theISystemProperties.getSerialPortCount()property, so the maximum slot number is one less than that property's value.

Expected result codes:
E_INVALIDARG - Invalid slot number.


getParallelPort

public IParallelPort getParallelPort(java.lang.Long slot)
Returns the parallel port associated with the given slot. Slots are numbered sequentially, starting with zero. The total number of parallel ports per machine is defined by theISystemProperties.getParallelPortCount()property, so the maximum slot number is one less than that property's value.

Expected result codes:
E_INVALIDARG - Invalid slot number.


getExtraDataKeys

public java.util.List<java.lang.String> getExtraDataKeys()
Returns an array representing the machine-specific extra data keys which currently have values defined.

Returns:
Array of extra data keys.

getExtraData

public java.lang.String getExtraData(java.lang.String key)
Returns associated machine-specific extra data. If the requested data key does not exist, this function will succeed and return an empty string in the value argument.

Expected result codes:
VBOX_E_FILE_ERROR - Settings file not accessible.
VBOX_E_XML_ERROR - Could not parse the settings file.

Parameters:
key - Name of the data key to get.
Returns:
Value of the requested data key.

setExtraData

public void setExtraData(java.lang.String key,
                         java.lang.String value)
Sets associated machine-specific extra data. If you pass null or an empty string as a key value, the given key will be deleted.

Expected result codes:
VBOX_E_FILE_ERROR - Settings file not accessible.
VBOX_E_XML_ERROR - Could not parse the settings file.
E_INVALIDARG - Key contains invalid characters.

Parameters:
key - Name of the data key to set.
value - Value to assign to the key. NOTE: Key must contain printable (non-control) UTF-8 characters only. NOTE: Before performing the actual data change, this method will ask all registered event listeners using theIExtraDataCanChangeEventnotification for a permission. If one of the listeners refuses the new value, the change will not be performed. NOTE: On success, theIExtraDataChangedEventnotification 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.

getCPUProperty

public java.lang.Boolean getCPUProperty(CPUPropertyType property)
Returns the virtual CPU boolean value of the specified property.

Expected result codes:
E_INVALIDARG - Invalid property.

Parameters:
property - Property type to query.
Returns:
Property value.

setCPUProperty

public void setCPUProperty(CPUPropertyType property,
                           java.lang.Boolean value)
Sets the virtual CPU boolean value of the specified property.

Expected result codes:
E_INVALIDARG - Invalid property.

Parameters:
property - Property type to query.
value - Property value.

getCPUIDLeafByOrdinal

public void getCPUIDLeafByOrdinal(java.lang.Long ordinal,
                                  Holder<java.lang.Long> idx,
                                  Holder<java.lang.Long> idxSub,
                                  Holder<java.lang.Long> valEax,
                                  Holder<java.lang.Long> valEbx,
                                  Holder<java.lang.Long> valEcx,
                                  Holder<java.lang.Long> valEdx)
Used to enumerate CPUID information override values.

Expected result codes:
E_INVALIDARG - Invalid ordinal number is out of range.

Parameters:
ordinal - The ordinal number of the leaf to get.
idx - CPUID leaf index.
idxSub - CPUID leaf sub-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.

getCPUIDLeaf

public void getCPUIDLeaf(java.lang.Long idx,
                         java.lang.Long idxSub,
                         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. Currently supported index values for cpuid: Standard CPUID leaves: 0 - 0x1f Extended CPUID leaves: 0x80000000 - 0x8000001f VIA CPUID leaves: 0xc0000000 - 0xc000000f See the Intel, AMD and VIA programmer's manuals for detailed information about the CPUID instruction and its leaves.

Expected result codes:
E_INVALIDARG - Invalid index.

Parameters:
idx - CPUID leaf index.
idxSub - CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable.
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.

setCPUIDLeaf

public void setCPUIDLeaf(java.lang.Long idx,
                         java.lang.Long idxSub,
                         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. Note that these values are not passed unmodified. VirtualBox clears features that it doesn't support. Currently supported index values for cpuid: Standard CPUID leaves: 0 - 0x1f Extended CPUID leaves: 0x80000000 - 0x8000001f VIA CPUID leaves: 0xc0000000 - 0xc000000f The subleaf index is only applicable to certain leaves (see manuals as this is subject to change). See the Intel, AMD and VIA programmer's manuals for detailed information about the cpuid instruction and its leaves. Do not use this method unless you know exactly what you're doing. Misuse can lead to random crashes inside VMs.

Expected result codes:
E_INVALIDARG - Invalid index.

Parameters:
idx - CPUID leaf index.
idxSub - CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. The 0xffffffff causes it to remove all other subleaves before adding one with sub-index 0.
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.

removeCPUIDLeaf

public void removeCPUIDLeaf(java.lang.Long idx,
                            java.lang.Long idxSub)
Removes the virtual CPU cpuid leaf for the specified index

Expected result codes:
E_INVALIDARG - Invalid index.

Parameters:
idx - CPUID leaf index.
idxSub - CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. The 0xffffffff value works like a wildcard.

removeAllCPUIDLeaves

public void removeAllCPUIDLeaves()
Removes all the virtual CPU cpuid leaves


getHWVirtExProperty

public java.lang.Boolean getHWVirtExProperty(HWVirtExPropertyType property)
Returns the value of the specified hardware virtualization boolean property.

Expected result codes:
E_INVALIDARG - Invalid property.

Parameters:
property - Property type to query.
Returns:
Property value.

setHWVirtExProperty

public void setHWVirtExProperty(HWVirtExPropertyType property,
                                java.lang.Boolean value)
Sets a new value for the specified hardware virtualization boolean property.

Expected result codes:
E_INVALIDARG - Invalid property.

Parameters:
property - Property type to set.
value - New property value.

setSettingsFilePath

public IProgress setSettingsFilePath(java.lang.String settingsFilePath)
Currently, it is an error to change this property on any machine. Later this will allow setting a new path for the settings file, with automatic relocation of all files (including snapshots and disk images) which are inside the base directory. This operation is only allowed when there are no pending unsaved settings.

Expected result codes:
E_NOTIMPL - The operation is not implemented yet.

Parameters:
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.
Returns:
Progress object to track the operation completion. NOTE: Setting this property to null or to an empty string is forbidden. When setting this property, the specified path must be absolute. The specified path may not exist, it will be created when necessary.

saveSettings

public 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 tosaveSettings()ordiscardSettings(). For registered machines, new settings become visible to all other VirtualBox clients after successful invocation of this method.

Expected result codes:
VBOX_E_FILE_ERROR - Settings file not accessible.
VBOX_E_XML_ERROR - Could not parse the settings file.
E_ACCESSDENIED - Modification request refused.
NOTE: The method sendsIMachineDataChangedEventnotification 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,String,String,String)but not yet registered, or on unregistered machines after callingunregister(org.virtualbox_7_0.CleanupMode).


discardSettings

public void discardSettings()
Discards any changes to the machine settings made since the session has been opened or since the last call tosaveSettings()ordiscardSettings().

Expected result codes:
VBOX_E_INVALID_VM_STATE - Virtual machine is not mutable.
NOTE: Calling this method is only valid on instances returned byISession.getMachine()and on new machines created byIVirtualBox.createMachine(String,String,List,String,String,String,String,String)or opened byIVirtualBox.openMachine(String,String)but not yet registered, or on unregistered machines after callingunregister(org.virtualbox_7_0.CleanupMode).


unregister

public java.util.List<IMedium> unregister(CleanupMode cleanupMode)
Unregisters a machine previously registered withIVirtualBox.registerMachine(org.virtualbox_7_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.A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the resulting IMedium array todeleteConfig(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 (seeIMediumfor 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, theIMachineRegisteredEventevent is fired. The call will fail if the machine is currently locked (seeISession).

Expected result codes:
VBOX_E_INVALID_OBJECT_STATE - Machine is currently locked for a session.

Parameters:
cleanupMode - How to clean up after the machine has been unregistered.
Returns:
List of media detached from the machine, depending on the cleanupMode parameter. NOTE: If the given machine is inaccessible (seegetAccessible()), 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.

deleteConfig

public IProgress deleteConfig(java.util.List<IMedium> media)
Deletes the files associated with this machine from disk. If medium objects are passed in with the aMedia argument, they are closed and, if closing was successful, their storage files are deleted as well. For convenience, this array of media files can be the same as the one returned from a previousunregister(org.virtualbox_7_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,String,String,String)or opened byIVirtualBox.openMachine(String,String), or after having calledunregister(org.virtualbox_7_0.CleanupMode)). The following files will be deleted by this method:Since deleting large disk image files can be a time-consuming I/O operation, this method operates asynchronously and returns an IProgress object to allow the caller to monitor the progress. There will be one sub-operation for each file that is being deleted (saved state or medium storage file).

Expected result codes:
VBOX_E_INVALID_VM_STATE - Machine is registered but not write-locked.
VBOX_E_IPRT_ERROR - Could not delete the settings file.

Parameters:
media - List of media to be closed and whose storage files will be deleted.
Returns:
Progress object to track the operation completion. NOTE: getSettingsModified()will return true after this method successfully returns.

exportTo

public IVirtualSystemDescription exportTo(IAppliance appliance,
                                          java.lang.String location)
Exports the machine to an OVF appliance. SeeIAppliancefor the steps required to export VirtualBox machines to OVF.

Parameters:
appliance - Appliance to export this machine to.
location - The target location.
Returns:
VirtualSystemDescription object which is created for this machine.

findSnapshot

public ISnapshot findSnapshot(java.lang.String nameOrId)
Returns a snapshot of this machine with the given name or UUID. Returns a snapshot of this machine with the given UUID. A null argument can be used to obtain the first snapshot taken on this machine. To traverse the whole tree of snapshots starting from the root, inspect the root snapshot'sISnapshot.getChildren()attribute and recurse over those children.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND - Virtual machine has no snapshots or snapshot not found.

Parameters:
nameOrId - What to search for. Name or UUID of the snapshot to find
Returns:
Snapshot object with the given name.

createSharedFolder

public void createSharedFolder(java.lang.String name,
                               java.lang.String hostPath,
                               java.lang.Boolean writable,
                               java.lang.Boolean automount,
                               java.lang.String autoMountPoint)
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. Refer to the description ofISharedFolderto read more about logical names.

Expected result codes:
VBOX_E_OBJECT_IN_USE - Shared folder already exists.
VBOX_E_FILE_ERROR - Shared folder hostPath not accessible.

Parameters:
name - Unique logical name of the shared folder.
hostPath - Full path to the shared folder in the host file system.
writable - Whether the share is writable or read-only.
automount - Whether the share gets automatically mounted by the guest or not.
autoMountPoint - Where the guest should automatically mount the folder, if possible. For Windows and OS/2 guests this should be a drive letter, while other guests it should be a absolute directory.

removeSharedFolder

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

Expected result codes:
VBOX_E_INVALID_VM_STATE - Virtual machine is not mutable.
VBOX_E_OBJECT_NOT_FOUND - Shared folder name does not exist.

Parameters:
name - Logical name of the shared folder to remove.

canShowConsoleWindow

public 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.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Machine session is not open.

Returns:
true if the console window can be shown and false otherwise. NOTE: This method will fail if a session for this machine is not currently open.

showConsoleWindow

public java.lang.Long showConsoleWindow()
Activates the console window and brings it to foreground on the desktop of the host PC. Many modern window managers on many platforms implement some sort of focus stealing prevention logic, so that it may be impossible to activate a window without the help of the currently active application. In this case, this method will return a non-zero identifier that represents the top-level window of the VM console process. The caller, if it represents a currently active process, is responsible to use this identifier (in a platform-dependent manner) to perform actual window activation.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Machine session is not open.

Returns:
Platform-dependent identifier of the top-level VM console window, or zero if this method has performed all actions necessary to implement theshow windowsemantics for the given platform and/or VirtualBox front-end. NOTE: This method will fail if a session for this machine is not currently open.

getGuestProperty

public 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.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Machine session is not open.

Parameters:
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.

getGuestPropertyValue

public java.lang.String getGuestPropertyValue(java.lang.String property)
Reads a value from the machine's guest property store.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Machine session is not open.

Parameters:
property - The name of the property to read.
Returns:
The value of the property. If the property does not exist then this will be empty.

getGuestPropertyTimestamp

public java.lang.Long getGuestPropertyTimestamp(java.lang.String property)
Reads a property timestamp from the machine's guest property store.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Machine session is not open.

Parameters:
property - The name of the property to read.
Returns:
The timestamp. If the property does not exist then this will be empty.

setGuestProperty

public 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.

Expected result codes:
E_ACCESSDENIED - Property cannot be changed.
E_INVALIDARG - Invalid flags.
VBOX_E_INVALID_VM_STATE - Virtual machine is not mutable or session not open.
VBOX_E_INVALID_OBJECT_STATE - Cannot set transient property when machine not running.

Parameters:
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.

setGuestPropertyValue

public void setGuestPropertyValue(java.lang.String property,
                                  java.lang.String value)
Sets or changes a value in the machine's guest property store. The flags field will be left unchanged or created empty for a new property.

Expected result codes:
E_ACCESSDENIED - Property cannot be changed.
VBOX_E_INVALID_VM_STATE - Virtual machine is not mutable or session not open.
VBOX_E_INVALID_OBJECT_STATE - Cannot set transient property when machine not running.

Parameters:
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.

deleteGuestProperty

public void deleteGuestProperty(java.lang.String name)
Deletes an entry from the machine's guest property store.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Machine session is not open.

Parameters:
name - The name of the property to delete.

enumerateGuestProperties

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)
Return a list of the guest properties matching a set of patterns along with their values, timestamps and flags.

Parameters:
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 timestamps 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.

querySavedGuestScreenInfo

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)
Returns the guest dimensions from the saved state.

Parameters:
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.

readSavedThumbnailToArray

public 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.

Parameters:
screenId - Saved guest screen to read from.
bitmapFormat - The requested format.
width - Bitmap width.
height - Bitmap height.
Returns:
Array with resulting bitmap data.

querySavedScreenshotInfo

public 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.

Parameters:
screenId - Saved guest screen to query info from.
width - Image width.
height - Image height.
Returns:
Formats supported by readSavedScreenshotToArray.

readSavedScreenshotToArray

public 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.

Parameters:
screenId - Saved guest screen to read from.
bitmapFormat - The requested format.
width - Image width.
height - Image height.
Returns:
Array with resulting image data.

hotPlugCPU

public void hotPlugCPU(java.lang.Long cpu)
Plugs a CPU into the machine.

Parameters:
cpu - The CPU id to insert.

hotUnplugCPU

public void hotUnplugCPU(java.lang.Long cpu)
Removes a CPU from the machine.

Parameters:
cpu - The CPU id to remove.

getCPUStatus

public java.lang.Boolean getCPUStatus(java.lang.Long cpu)
Returns the current status of the given CPU.

Parameters:
cpu - The CPU id to check for.
Returns:
Status of the CPU.

getEffectiveParavirtProvider

public ParavirtProvider getEffectiveParavirtProvider()
Returns the effective paravirtualization provider for this VM.

Returns:
The effective paravirtualization provider for this VM.

queryLogFilename

public java.lang.String queryLogFilename(java.lang.Long idx)
Queries for the VM log file name of an given index. Returns an empty string if a log file with that index doesn't exists.

Parameters:
idx - Which log file name to query. 0=current log file.
Returns:
On return the full path to the log file or an empty string on error.

readLog

public byte[] readLog(java.lang.Long idx,
                      java.lang.Long offset,
                      java.lang.Long size)
Reads the VM log file. The chunk size is limited, so even if you ask for a big piece there might be less data returned.

Parameters:
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.
Returns:
Data read from the log file. A data size of 0 means end of file if the requested chunk size was not 0. This is the unprocessed file data, i.e. the line ending style depends on the platform of the system the server is running on.

cloneTo

public 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). The target machine object must have been created previously withIVirtualBox.createMachine(String,String,List,String,String,String,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 enabled 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.

Expected result codes:
E_INVALIDARG - target is null.

Parameters:
target - Target machine object.
mode - Which states should be cloned.
options - Options for the cloning operation.
Returns:
Progress object to track the operation completion.

moveTo

public IProgress moveTo(java.lang.String folder,
                        java.lang.String type)
Move machine on to new place/folder

Parameters:
folder - Target folder where machine is moved. May be the same folder where the VM already is located or the empty string, in which case the machine is kept in this location and the disk images and other files which are stored elsewhere are moved.
type - Type of moving. Possible values: basic - Only the files which belong solely to this machine are moved from the original machine's folder to a new folder.
Returns:
Progress object to track the operation completion.

saveState

public IProgress saveState()
Saves the current execution state of a running virtual machine and stops its execution. After this operation completes, the machine will go to the Saved state. The next time it is powered up this state will be restored and the machine will continue its execution from the place where it was saved. This operation differs from taking a snapshot to the effect that it doesn't create new differencing media. Also, once the machine is powered up from the state saved using this method, the saved state is deleted, so it will be impossible to return to this state later.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Virtual machine state neither Running nor Paused.
VBOX_E_FILE_ERROR - Failed to create directory for saved state file.

Returns:
Progress object to track the operation completion. NOTE: On success, this method implicitly callssaveSettings()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.
See Also:
takeSnapshot(String,String,Boolean,Holder)

adoptSavedState

public void adoptSavedState(java.lang.String savedStateFile)
Associates the given saved state file to the virtual machine. On success, the machine will go to the Saved state. The next time it is powered up it will be restored from the adopted saved state and continue execution from the place where the saved state file was created. The specified saved state file path may be absolute or relative to the folder the VM normally saves the state to (usually,getSnapshotFolder()).

Expected result codes:
VBOX_E_INVALID_VM_STATE - Virtual machine state neither PoweredOff nor Aborted.

Parameters:
savedStateFile - Path to the saved state file to adopt. NOTE: It's a caller's responsibility to make sure the given saved state file is compatible with the settings of this virtual machine that represent its virtual hardware (memory size, storage disk configuration etc.). If there is a mismatch, the behavior of the virtual machine is undefined.

discardSavedState

public void discardSavedState(java.lang.Boolean fRemoveFile)
Forcibly resets the machine to "Powered Off" state if it is currently in the "Saved" state previously created bysaveState()) or in the "AbortedSaved" state. The 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.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Virtual machine not in either the Saved or AbortedSaved state.

Parameters:
fRemoveFile - Whether to also remove the saved state file. NOTE: This operation is equivalent to resetting or powering off the machine without doing a proper shutdown of the guest operating system; as with resetting a running phyiscal computer, it can can lead to data loss.

takeSnapshot

public 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. SeeISnapshotfor an introduction to snapshots. This method can be called for a PoweredOff, Saved (seesaveState()), AbortedSaved, 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.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Virtual machine currently changing state.

Parameters:
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.
Returns:
Progress object to track the operation completion. NOTE: This method implicitly callssaveSettings()to save all current machine settings before taking an offline snapshot.

deleteSnapshot

public IProgress deleteSnapshot(java.lang.String id)
Starts deleting the specified snapshot asynchronously. SeeISnapshotfor 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:The virtual machine'sgetState()is changed to "DeletingSnapshot", "DeletingSnapshotOnline" or "DeletingSnapshotPaused" while this operation is in progress.

Expected result codes:
VBOX_E_INVALID_VM_STATE - The running virtual machine prevents deleting this snapshot. This happens only in very specific situations, usually snapshots can be deleted without trouble while a VM is running. The error message text explains the reason for the failure.

Parameters:
id - UUID of the snapshot to delete.
Returns:
Progress object to track the operation completion. NOTE: Merging medium contents can be very time and disk space consuming, if these media are big in size and have many children. However, if the snapshot being deleted is the last (head) snapshot on the branch, the operation will be rather quick.

deleteSnapshotAndAllChildren

public IProgress deleteSnapshotAndAllChildren(java.lang.String id)
Starts deleting the specified snapshot and all its children asynchronously. SeeISnapshotfor 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.

Expected result codes:
VBOX_E_INVALID_VM_STATE - The running virtual machine prevents deleting this snapshot. This happens only in very specific situations, usually snapshots can be deleted without trouble while a VM is running. The error message text explains the reason for the failure.
E_NOTIMPL - The method is not implemented yet.

Parameters:
id - UUID of the snapshot to delete, including all its children.
Returns:
Progress object to track the operation completion. NOTE: This API method is right now not implemented!

deleteSnapshotRange

public IProgress deleteSnapshotRange(java.lang.String startId,
                                     java.lang.String endId)
Starts deleting the specified snapshot range. This is limited to linear snapshot lists, which means there may not be any other child snapshots other than the direct sequence between the start and end snapshot. If the start and end snapshot point to the same snapshot this method is completely equivalent todeleteSnapshot(String). SeeISnapshotfor 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.

Expected result codes:
VBOX_E_INVALID_VM_STATE - The running virtual machine prevents deleting this snapshot. This happens only in very specific situations, usually snapshots can be deleted without trouble while a VM is running. The error message text explains the reason for the failure.
E_NOTIMPL - The method is not implemented yet.

Parameters:
startId - UUID of the first snapshot to delete.
endId - UUID of the last snapshot to delete.
Returns:
Progress object to track the operation completion. NOTE: This API method is right now not implemented!

restoreSnapshot

public IProgress restoreSnapshot(ISnapshot snapshot)
Starts resetting the machine's current state to the state contained in the given snapshot, asynchronously. All current settings of the machine will be reset and changes stored in differencing media will be lost. SeeISnapshotfor 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.Savedstate, so that the next time it is powered on, the execution state will be restored from the state of the snapshot.

Expected result codes:
VBOX_E_INVALID_VM_STATE - Virtual machine is running.

Parameters:
snapshot - The snapshot to restore the VM state from.
Returns:
Progress object to track the operation completion. NOTE: The machine must not be running, otherwise the operation will fail. NOTE: If the machine is in theMachineState.Savedstate prior to this operation, the saved state file will be implicitly deleted (as ifdiscardSavedState(Boolean)were called).

applyDefaults

public void applyDefaults(java.lang.String flags)
Applies the defaults for the configured guest OS type. This is primarily for getting sane settings straight after creating a new VM, but it can also be applied later.

Expected result codes:
E_FAIL - General error.
VBOX_E_INVALID_VM_STATE - The machine is in invalid state.
VBOX_E_OBJECT_IN_USE - Some of the applied objects already exist. The method has been called to already configured machine.

Parameters:
flags - Additional flags, to be defined later. NOTE: This is primarily a shortcut, centralizing the tedious job of getting the recommended settings and translating them into settings updates. The settings are made at the end of the call, but not saved.

changeEncryption

public IProgress changeEncryption(java.lang.String currentPassword,
                                  java.lang.String cipher,
                                  java.lang.String newPassword,
                                  java.lang.String newPasswordId,
                                  java.lang.Boolean force)
Starts encryption of this VM. This means that the stored data of the VM is encrypted. Please note that the results can be either returned straight away, or later as the result of the background operation via the object returned via the progress parameter.

Expected result codes:
VBOX_E_NOT_SUPPORTED - Encryption is not supported for various reasons e.g. unsupported cipher.

Parameters:
currentPassword - The current password the VM is protected with. Use an empty string to indicate that the VM isn't encrypted.
cipher - The cipher to use for encryption. An empty string indicates no encryption for the result.
newPassword - The new password the VM should be protected with. An empty password and password ID will result in the VM being encrypted with the current password.
newPasswordId - The ID of the new password when unlocking the VM.
force - Force reencryption of the data if just password is changed. Otherwise, if data already encrypted and cipher doesn't changed only the password is changed.
Returns:
Progress object to track the operation completion.

getEncryptionSettings

public void getEncryptionSettings(Holder<java.lang.String> cipher,
                                  Holder<java.lang.String> passwordId)
Returns the encryption settings for this VM.

Expected result codes:
VBOX_E_NOT_SUPPORTED - Encryption is not configured for this VM.

Parameters:
cipher - The cipher used for encryption.
passwordId - The ID of the password when unlocking the VM.

checkEncryptionPassword

public void checkEncryptionPassword(java.lang.String password)
Checks whether the supplied password is correct for the VM.

Expected result codes:
VBOX_E_NOT_SUPPORTED - Encryption is not configured for this VM.
VBOX_E_PASSWORD_INCORRECT - The given password is incorrect.

Parameters:
password - The password to check.

addEncryptionPassword

public void addEncryptionPassword(java.lang.String id,
                                  java.lang.String password)
Adds a password used for encryption. Updates the accesibility state if password used the VM encryption.

Expected result codes:
VBOX_E_PASSWORD_INCORRECT - The password provided wasn't correct for the VM using the provided ID.

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

addEncryptionPasswords

public void addEncryptionPasswords(java.util.List<java.lang.String> ids,
                                   java.util.List<java.lang.String> passwords)
Adds passwords used for encryption. Updates the accesibility state if the list contains password used the VM encryption.

Expected result codes:
VBOX_E_PASSWORD_INCORRECT - The password provided wasn't correct for the VM using the provided ID.
E_INVALIDARG - Id and passwords arrays have different size.

Parameters:
ids - List of identifiers for the passwords. Must match the identifier used when the encrypted VM was created.
passwords - List of passwords.

removeEncryptionPassword

public void removeEncryptionPassword(java.lang.String id)
Removes a password used for the VM encryption/decryption. The password can be removed only if the VM is powered off. Removing the password causes the VM goes to the inaccessible state and the password must be provided again.

Parameters:
id - The identifier used for the password. Must match the identifier used when the encrypted VM was created. NOTE: If machine becomes inaccessible all passwords are purged. One has to add required passwords again using eitheraddEncryptionPassword(String,String)oraddEncryptionPasswords(List,List)methods.

clearAllEncryptionPasswords

public void clearAllEncryptionPasswords()
Clears all provided VM passwords. The passwords can be removed only if the VM is powered off. Removing the passwords causes the VM goes to the inaccessible state and the password must be provided again.