public class IVirtualBox extends IUnknown
getMachines()
attribute.
Error information handling is a bit special with IVirtualBox: creating
an instance will always succeed. The return of the actual error
code/information is postponed to any attribute or method call. The
reason for this is that COM likes to mutilate the error code and lose
the detailed error information returned by instance creation.
Interface ID: {7682D5EB-F00E-44F1-8CA2-99D08B1CD607}
Constructor and Description |
---|
IVirtualBox(java.lang.String wrapped,
org.virtualbox_7_0.ObjectRefManager objMgr,
org.virtualbox_7_0.jaxws.VboxPortType port) |
Modifier and Type | Method and Description |
---|---|
java.lang.Boolean |
checkFirmwarePresent(FirmwareType firmwareType,
java.lang.String version,
Holder<java.lang.String> url,
Holder<java.lang.String> file)
Check if this VirtualBox installation has a firmware
of the given type available, either system-wide or per-user.
|
java.lang.String |
composeMachineFilename(java.lang.String name,
java.lang.String group,
java.lang.String createFlags,
java.lang.String baseFolder)
Returns a recommended full path of the settings file name for a new virtual
machine.
|
IAppliance |
createAppliance()
Creates a new appliance object, which represents an appliance in the Open Virtual Machine
Format (OVF).
|
ICloudNetwork |
createCloudNetwork(java.lang.String networkName) |
IDHCPServer |
createDHCPServer(java.lang.String name)
Creates a DHCP server settings to be used for the given internal network name
|
IHostOnlyNetwork |
createHostOnlyNetwork(java.lang.String networkName) |
IMachine |
createMachine(java.lang.String settingsFile,
java.lang.String name,
java.util.List<java.lang.String> groups,
java.lang.String osTypeId,
java.lang.String flags,
java.lang.String cipher,
java.lang.String passwordId,
java.lang.String password)
Creates a new virtual machine by creating a machine settings file at
the given location.
|
IMedium |
createMedium(java.lang.String format,
java.lang.String location,
AccessMode accessMode,
DeviceType aDeviceTypeType)
Creates a new base medium object that will use the given storage
format and location for medium data.
|
INATNetwork |
createNATNetwork(java.lang.String networkName) |
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 global 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.
|
IUnattended |
createUnattendedInstaller()
Creates a new
IUnattended guest installation object. |
ICloudNetwork |
findCloudNetworkByName(java.lang.String networkName) |
IDHCPServer |
findDHCPServerByNetworkName(java.lang.String name)
Searches a DHCP server settings to be used for the given internal network name
|
IHostOnlyNetwork |
findHostOnlyNetworkById(java.lang.String id)
Searches through all host networks for one with
the given GUID.
|
IHostOnlyNetwork |
findHostOnlyNetworkByName(java.lang.String networkName) |
IMachine |
findMachine(java.lang.String nameOrId)
Attempts to find a virtual machine given its name or UUID.
|
INATNetwork |
findNATNetworkByName(java.lang.String networkName) |
IProgress |
findProgressById(java.lang.String id)
Searches through all progress objects known to VBoxSVC for an
instance with the given GUID.
|
java.lang.Long |
getAPIRevision()
This is mainly intended for the VBox Validation Kit so it can fluently
deal with incompatible API changes and new functionality during
development (i.e.
|
java.lang.String |
getAPIVersion()
A string representing the VirtualBox API version number.
|
java.util.List<ICloudNetwork> |
getCloudNetworks()
Names of all configured cloud networks.
|
ICloudProviderManager |
getCloudProviderManager()
The cloud provider manager (singleton).
|
java.util.List<IDHCPServer> |
getDHCPServers()
DHCP servers.
|
java.util.List<IMedium> |
getDVDImages()
Array of CD/DVD image objects currently in use by this VirtualBox instance.
|
IEventSource |
getEventSource()
Event source for VirtualBox events.
|
java.lang.String |
getExtraData(java.lang.String key)
Returns associated global extra data.
|
java.util.List<java.lang.String> |
getExtraDataKeys()
Returns an array representing the global extra data keys which currently
have values defined.
|
java.util.List<IMedium> |
getFloppyImages()
Array of floppy image objects currently in use by this VirtualBox instance.
|
java.util.List<java.lang.String> |
getGenericNetworkDrivers()
Names of all generic network drivers.
|
IGuestOSType |
getGuestOSType(java.lang.String id)
Returns an object describing the specified guest OS type.
|
java.util.List<IGuestOSType> |
getGuestOSTypes() |
java.util.List<IMedium> |
getHardDisks()
Array of medium objects known to this VirtualBox installation.
|
java.lang.String |
getHomeFolder()
Full path to the directory where the global settings file,
VirtualBox.xml , is stored. |
IHost |
getHost()
Associated host object.
|
java.util.List<IHostOnlyNetwork> |
getHostOnlyNetworks()
Names of all host-only networks.
|
java.util.List<java.lang.String> |
getInternalNetworks()
Names of all internal networks.
|
java.util.List<java.lang.String> |
getMachineGroups()
Array of all machine group names which are used by the machines which
are accessible.
|
java.util.List<IMachine> |
getMachines()
Array of machine objects registered within this VirtualBox instance.
|
java.util.List<IMachine> |
getMachinesByGroups(java.util.List<java.lang.String> groups)
Gets all machine references which are in one of the specified groups.
|
java.util.List<MachineState> |
getMachineStates(java.util.List<IMachine> machines)
Gets the state of several machines in a single operation.
|
java.util.List<INATNetwork> |
getNATNetworks() |
java.lang.String |
getPackageType()
A string representing the package type of this product.
|
IPerformanceCollector |
getPerformanceCollector()
Associated performance collector object.
|
java.util.List<IProgress> |
getProgressOperations() |
java.lang.Long |
getRevision()
The internal build revision number of the product.
|
java.lang.String |
getSettingsFilePath()
Full name of the global settings file.
|
java.util.List<ISharedFolder> |
getSharedFolders()
Collection of global shared folders.
|
ISystemProperties |
getSystemProperties()
Associated system information object.
|
java.lang.String |
getVersion()
A string representing the version number of the product.
|
java.lang.String |
getVersionNormalized()
A string representing the version number of the product,
without the publisher information (but still with other tags).
|
IMachine |
openMachine(java.lang.String settingsFile,
java.lang.String password)
Opens a virtual machine from the existing settings file.
|
IMedium |
openMedium(java.lang.String location,
DeviceType deviceType,
AccessMode accessMode,
java.lang.Boolean forceNewUuid)
Finds existing media or opens a medium from an existing storage location.
|
static IVirtualBox |
queryInterface(IUnknown obj) |
void |
registerMachine(IMachine machine)
Registers the machine previously created using
createMachine(String,String,List,String,String,String,String,String) or opened usingopenMachine(String,String) within this VirtualBox installation. |
void |
removeCloudNetwork(ICloudNetwork network) |
void |
removeDHCPServer(IDHCPServer server)
Removes the DHCP server settings
|
void |
removeHostOnlyNetwork(IHostOnlyNetwork network) |
void |
removeNATNetwork(INATNetwork network) |
void |
removeSharedFolder(java.lang.String name)
Removes the global shared folder with the given name previously
created by
createSharedFolder(String,String,Boolean,Boolean,String) from the collection of
shared folders and stops sharing it. |
void |
setExtraData(java.lang.String key,
java.lang.String value)
Sets associated global extra data.
|
void |
setSettingsSecret(java.lang.String password)
Unlocks the secret data by passing the unlock password to the
server.
|
getObjMgr, getRemoteWSPort, getWrapped, releaseRemote
public IVirtualBox(java.lang.String wrapped, org.virtualbox_7_0.ObjectRefManager objMgr, org.virtualbox_7_0.jaxws.VboxPortType port)
public java.lang.String getVersion()
public java.lang.String getVersionNormalized()
getVersion()
.public java.lang.Long getRevision()
public java.lang.String getPackageType()
public java.lang.String getAPIVersion()
public java.lang.Long getAPIRevision()
public java.lang.String getHomeFolder()
VirtualBox.xml
, is stored.
In this version of VirtualBox, the value of this property is
always<user_dir>/.VirtualBox
(where<user_dir>
is the path to the user directory,
as determined by the host OS), and cannot be changed.
This path is also used as the base to resolve relative paths in
places where relative paths are allowed (unless otherwise
expressly indicated).public java.lang.String getSettingsFilePath()
getHomeFolder()
plus/VirtualBox.xml
.public IHost getHost()
public ISystemProperties getSystemProperties()
public java.util.List<IMachine> getMachines()
public java.util.List<java.lang.String> getMachineGroups()
"/"
,"/group/subgroup"
is a valid result).public java.util.List<IMedium> getHardDisks()
IMedium.getChildren()
.public java.util.List<IMedium> getDVDImages()
public java.util.List<IMedium> getFloppyImages()
public java.util.List<IProgress> getProgressOperations()
public java.util.List<IGuestOSType> getGuestOSTypes()
public java.util.List<ISharedFolder> getSharedFolders()
createSharedFolder(String,String,Boolean,Boolean,String)
. Existing shared folders can be
removed usingremoveSharedFolder(String)
.
NOTE: In the current version of the product, global shared folders are not
implemented and therefore this collection is always empty.public IPerformanceCollector getPerformanceCollector()
public java.util.List<IDHCPServer> getDHCPServers()
public java.util.List<INATNetwork> getNATNetworks()
public IEventSource getEventSource()
public java.util.List<java.lang.String> getInternalNetworks()
public java.util.List<IHostOnlyNetwork> getHostOnlyNetworks()
public java.util.List<java.lang.String> getGenericNetworkDrivers()
public java.util.List<ICloudNetwork> getCloudNetworks()
public ICloudProviderManager getCloudProviderManager()
public static IVirtualBox queryInterface(IUnknown obj)
public java.lang.String composeMachineFilename(java.lang.String name, java.lang.String group, java.lang.String createFlags, java.lang.String baseFolder)
createMachine(String,String,List,String,String,String,String,String)
if null or
empty string (which is recommended) is specified for the
settingsFile argument there, which means that API should use
a recommended default file name.IMachine.getName()
andcreateMachine(String,String,List,String,String,String,String,String)
for more
details about the machine name.
groupName defines which additional subdirectory levels should be
included. It must be either a valid group name or null or empty
string which designates that the machine will not be related to a
machine group.
If baseFolder is a null or empty string (which is recommended), the
default machine settings folder
(seeISystemProperties.getDefaultMachineFolder()
) will be used as
a base folder for the created machine, resulting in a file name like
"/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder
will be used.
This method does not access the host disks. In particular, it does not check
for whether a machine with this name already exists.name
- Suggested machine name.group
- Machine group name for the new machine or machine group. It is
used to determine the right subdirectory.createFlags
- Machine creation flags, seecreateMachine(String,String,List,String,String,String,String,String)
(optional).baseFolder
- Base machine folder (optional).public IMachine createMachine(java.lang.String settingsFile, java.lang.String name, java.util.List<java.lang.String> groups, java.lang.String osTypeId, java.lang.String flags, java.lang.String cipher, java.lang.String passwordId, java.lang.String password)
ISystemProperties.getDefaultMachineFolder()
). If you specify
null or empty string (which is recommended) for the settingsFile
argument,composeMachineFilename(String,String,String,String)
is called automatically
to have such a recommended name composed based on the machine name
given in the name argument and the primary group.
If the resulting settings file already exists, this method will fail,
unless the forceOverwrite flag is set.
The new machine is created unregistered, with the initial configuration
set according to the specified guest OS type. A typical sequence of
actions to create a new virtual machine is as follows:IMachine.saveSettings()
to write the settings
to the machine's XML settings file. The configuration of the newly
created machine will not be saved to disk until this method is
called.registerMachine(org.virtualbox_7_0.IMachine)
to add the machine to the list
of machines known to VirtualBox.getGuestOSTypes()
array.
VBOX_E_OBJECT_NOT_FOUND
- osTypeId is invalid.VBOX_E_FILE_ERROR
- Resulting settings file name is invalid or the settings file already
exists or could not be created due to an I/O error.E_INVALIDARG
- name is empty or null.settingsFile
- Fully qualified path where the settings file should be created,
empty string or null for a default folder and file based on the
name argument and the primary group.
(seecomposeMachineFilename(String,String,String,String)
).name
- Machine name.groups
- Array of group names. null or an empty array have the same
meaning as an array with just the empty string or"/"
, i.e.
create a machine without group association.osTypeId
- Guest OS Type ID.flags
- Additional property parameters, passed as a comma-separated list of
"name=value" type entries. The following ones are recognized:forceOverwrite=1
to overwrite an existing machine settings
file,UUID=<uuid>
to specify a machine UUID anddirectoryIncludesUUID=1
to switch to a special VM directory
naming scheme which should not be used unless necessary.cipher
- The cipher. It should be empty if encryption is not required.passwordId
- The password id. It should be empty if encryption is not required.password
- The password. It should be empty if encryption is not required.IMachine.getSettingsModified()
will return
false for the created machine, until any of machine settings
are changed.
NOTE: There is no way to change the name of the settings file or
subfolder of the created machine directly.public IMachine openMachine(java.lang.String settingsFile, java.lang.String password)
registerMachine(org.virtualbox_7_0.IMachine)
.
The specified settings file name must be fully qualified.
The file must exist and be a valid machine XML settings file
whose contents will be used to construct the machine object.
VBOX_E_FILE_ERROR
- Settings file name invalid, not found or sharing violation.settingsFile
- Name of the machine settings file.password
- The password. If the machine is not encrypted the parameter is
ignored.IMachine.getAccessible()
andIMachine.getAccessError()
properties to determine the
real machine state.
NOTE: IMachine.getSettingsModified()
will return
false for the opened machine, until any of machine settings
are changed.public void registerMachine(IMachine machine)
createMachine(String,String,List,String,String,String,String,String)
or opened usingopenMachine(String,String)
within this VirtualBox installation. After
successful method invocation, theIMachineRegisteredEvent
event is fired.
VBOX_E_OBJECT_NOT_FOUND
- No matching virtual machine found.VBOX_E_INVALID_OBJECT_STATE
- Virtual machine was not created within this VirtualBox instance.IMachine.saveSettings()
to save all current machine settings before registering it.public IMachine findMachine(java.lang.String nameOrId)
VBOX_E_OBJECT_NOT_FOUND
- Could not find registered machine matching nameOrId.nameOrId
- What to search for. This can either be the UUID or the name of a virtual machine.public java.util.List<IMachine> getMachinesByGroups(java.util.List<java.lang.String> groups)
groups
- What groups to match. The usual group list rules apply, i.e.
passing an empty list will match VMs in the toplevel group, likewise
the empty string.public java.util.List<MachineState> getMachineStates(java.util.List<IMachine> machines)
machines
- Array with the machine references.public IAppliance createAppliance()
IAppliance
for details.public IUnattended createUnattendedInstaller()
IUnattended
guest installation object. This can be used to
analyze an installation ISO to create and configure a new machine for it to be installed
on. It can also be used to (re)install an existing machine.public IMedium createMedium(java.lang.String format, java.lang.String location, AccessMode accessMode, DeviceType aDeviceTypeType)
IMedium.getId()
, may
remain uninitialized until the medium storage unit is successfully
created by one of the above methods.
Depending on the given device type, the file at the storage location
must be in one of the media formats understood by VirtualBox:ISystemProperties.getMediumFormats()
).
After the storage unit is successfully created and this method succeeds,
if the medium is a base medium, it
will be added to thegetHardDisks()
array attribute.getDVDImages()
array attribute.getFloppyImages()
array attribute.ISystemProperties.getMediumFormats()
. If the format
attribute is empty or null then the default storage format
specified byISystemProperties.getDefaultHardDiskFormat()
will
be used for disks r creating a storage unit of the medium.
Note that the format of the location string is storage format specific.
SeeIMedium.getLocation()
and IMedium for more details.
VBOX_E_OBJECT_NOT_FOUND
- format identifier is invalid. SeeISystemProperties.getMediumFormats()
.VBOX_E_FILE_ERROR
- location is a not valid file name (for file-based formats only).format
- Identifier of the storage format to use for the new medium.location
- Location of the storage unit for the new medium.accessMode
- Whether to open the image in read/write or read-only mode. For
a "DVD" device type, this is ignored and read-only mode is always assumed.aDeviceTypeType
- Must be one of "HardDisk", "DVD" or "Floppy".public IMedium openMedium(java.lang.String location, DeviceType deviceType, AccessMode accessMode, java.lang.Boolean forceNewUuid)
IMachine.attachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_0.IMedium)
.
Depending on the given device type, the file at the storage location
must be in one of the media formats understood by VirtualBox:ISystemProperties.getMediumFormats()
).
After this method succeeds, if the medium is a base medium, it
will be added to thegetHardDisks()
array attribute.getDVDImages()
array attribute.getFloppyImages()
array attribute.IMedium
for
more details.
The UUID of the newly opened medium will either be retrieved from the
storage location, if the format supports it (e.g. for hard disk images),
or a new UUID will be randomly generated (e.g. for ISO and RAW files).
If for some reason you need to change the medium's UUID, useIMedium.setIds(Boolean,String,Boolean,String)
.
If a differencing hard disk medium is to be opened by this method, the
operation will succeed only if its parent medium and all ancestors,
if any, are already known to this VirtualBox installation (for example,
were opened by this method before).
This method attempts to guess the storage format of the specified medium
by reading medium data at the specified location.
If accessMode is ReadWrite (which it should be for hard disks and floppies),
the image is opened for read/write access and must have according permissions,
as VirtualBox may actually write status information into the disk's metadata
sections.
Note that write access is required for all typical hard disk usage in VirtualBox,
since VirtualBox may need to write metadata such as a UUID into the image.
The only exception is opening a source image temporarily for copying and
cloning (seeIMedium.cloneTo(org.virtualbox_7_0.IMedium,List,org.virtualbox_7_0.IMedium)
when the image will be closed
again soon.
The format of the location string is storage format specific. SeeIMedium.getLocation()
and IMedium for more details.
VBOX_E_FILE_ERROR
- Invalid medium storage file location or could not find the medium
at the specified location.VBOX_E_IPRT_ERROR
- Could not get medium storage format.E_INVALIDARG
- Invalid medium storage format.VBOX_E_INVALID_OBJECT_STATE
- Medium has already been added to a media registry.location
- Location of the storage unit that contains medium data in one of
the supported storage formats.deviceType
- Must be one of "HardDisk", "DVD" or "Floppy".accessMode
- Whether to open the image in read/write or read-only mode. For
a "DVD" device type, this is ignored and read-only mode is always assumed.forceNewUuid
- Allows the caller to request a completely new medium UUID for
the image which is to be opened. Useful if one intends to open an exact
copy of a previously opened image, as this would normally fail due to
the duplicate UUID.public IGuestOSType getGuestOSType(java.lang.String id)
"win31"
or"ubuntu"
. The guest OS type ID of a
particular virtual machine can be read or set using theIMachine.getOSTypeId()
attribute.
ThegetGuestOSTypes()
collection contains all
available guest OS type objects. Each object has anIGuestOSType.getId()
attribute which contains an identifier of
the guest OS this object describes.
While this function returns an error for unknown guest OS types, they
can be still used without serious problems (if one accepts the fact
that there is no default VM config information).
E_INVALIDARG
- id is not a valid Guest OS type.id
- Guest OS type ID string.public void createSharedFolder(java.lang.String name, java.lang.String hostPath, java.lang.Boolean writable, java.lang.Boolean automount, java.lang.String autoMountPoint)
ISharedFolder
to read more about logical names.name
- Unique logical name of the shared folder.hostPath
- Full path to the shared folder in the host file system.writable
- Whether the share is writable or readonlyautomount
- Whether the share gets automatically mounted by the guest
or not.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.
NOTE: In the current implementation, this operation is not
implemented.public void removeSharedFolder(java.lang.String name)
createSharedFolder(String,String,Boolean,Boolean,String)
from the collection of
shared folders and stops sharing it.name
- Logical name of the shared folder to remove.
NOTE: In the current implementation, this operation is not
implemented.public java.util.List<java.lang.String> getExtraDataKeys()
public java.lang.String getExtraData(java.lang.String key)
VBOX_E_FILE_ERROR
- Settings file not accessible.VBOX_E_XML_ERROR
- Could not parse the settings file.key
- Name of the data key to get.public void setExtraData(java.lang.String key, java.lang.String value)
VBOX_E_FILE_ERROR
- Settings file not accessible.VBOX_E_XML_ERROR
- Could not parse the settings file.E_ACCESSDENIED
- Modification request refused.E_INVALIDARG
- Key contains invalid characters.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 theIExtraDataCanChangeEvent
notification for a permission. If one of the listeners refuses the
new value, the change will not be performed.
NOTE: On success, theIExtraDataChangedEvent
notification
is called to inform all registered listeners about a successful data
change.public void setSettingsSecret(java.lang.String password)
VBOX_E_INVALID_VM_STATE
- Virtual machine is not mutable.password
- The cipher key.public IDHCPServer createDHCPServer(java.lang.String name)
E_INVALIDARG
- Host network interface name already exists.name
- server namepublic IDHCPServer findDHCPServerByNetworkName(java.lang.String name)
E_INVALIDARG
- Host network interface name already exists.name
- server namepublic void removeDHCPServer(IDHCPServer server)
E_INVALIDARG
- Host network interface name already exists.server
- DHCP server settings to be removedpublic INATNetwork createNATNetwork(java.lang.String networkName)
public INATNetwork findNATNetworkByName(java.lang.String networkName)
public void removeNATNetwork(INATNetwork network)
public IHostOnlyNetwork createHostOnlyNetwork(java.lang.String networkName)
public IHostOnlyNetwork findHostOnlyNetworkByName(java.lang.String networkName)
public IHostOnlyNetwork findHostOnlyNetworkById(java.lang.String id)
id
- GUID of the host-only network to search for.public void removeHostOnlyNetwork(IHostOnlyNetwork network)
public ICloudNetwork createCloudNetwork(java.lang.String networkName)
public ICloudNetwork findCloudNetworkByName(java.lang.String networkName)
public void removeCloudNetwork(ICloudNetwork network)
public java.lang.Boolean checkFirmwarePresent(FirmwareType firmwareType, java.lang.String version, Holder<java.lang.String> url, Holder<java.lang.String> file)
firmwareType
- Type of firmware to check.version
- Expected version number, usually empty string (presently ignored).url
- Suggested URL to download this firmware from.file
- Filename of firmware, only valid if result == TRUE.public IProgress findProgressById(java.lang.String id)
id
- GUID of the progress object to search for.