|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.virtualbox_5_0.IUnknown
org.virtualbox_5_0.IVirtualBox
public class IVirtualBox
The IVirtualBox interface represents the main interface exposed by the
product that provides virtual machine management.
An instance of IVirtualBox is required for the product to do anything
useful. Even though the interface does not expose this, internally,
IVirtualBox is implemented as a singleton and actually lives in the
process of the VirtualBox server (VBoxSVC.exe). This makes sure that
IVirtualBox can track the state of all virtual machines on a particular
host, regardless of which frontend started them.
To enumerate all the virtual machines on the host, use thegetMachines()
attribute.
Interface ID: {0169423F-46B4-CDE9-91AF-1E9D5B6CD945}
Field Summary |
---|
Fields inherited from class org.virtualbox_5_0.IUnknown |
---|
obj, objMgr, port |
Constructor Summary | |
---|---|
IVirtualBox(java.lang.String wrapped,
org.virtualbox_5_0.ObjectRefManager objMgr,
org.virtualbox_5_0.jaxws.VboxPortType port)
|
Method Summary | |
---|---|
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). |
IDHCPServer |
createDHCPServer(java.lang.String name)
Creates a DHCP server settings to be used for the given internal network name |
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)
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)
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. |
IDHCPServer |
findDHCPServerByNetworkName(java.lang.String name)
Searches a DHCP server settings to be used for the given internal network name |
IMachine |
findMachine(java.lang.String nameOrId)
Attempts to find a virtual machine given its name or UUID. |
INATNetwork |
findNATNetworkByName(java.lang.String networkName)
|
java.lang.Long |
getAPIRevision()
To be defined exactly, but we need something that the Validation Kit can use to figure which methods and attributes can safely be used on a continuously changing trunk (and occasional branch). |
java.lang.String |
getAPIVersion()
A string representing the VirtualBox API version number. |
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<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)
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) or opened usingopenMachine(String) within this VirtualBox installation. |
void |
removeDHCPServer(IDHCPServer server)
Removes the DHCP server settings |
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) 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. |
Methods inherited from class org.virtualbox_5_0.IUnknown |
---|
getObjMgr, getRemoteWSPort, getWrapped, releaseRemote |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public IVirtualBox(java.lang.String wrapped, org.virtualbox_5_0.ObjectRefManager objMgr, org.virtualbox_5_0.jaxws.VboxPortType port)
Method Detail |
---|
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()
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()
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)
. 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<java.lang.String> getGenericNetworkDrivers()
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)
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)
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)
(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)
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_5_0.IMachine)
to add the machine to the list
of machines known to VirtualBox.getGuestOSTypes()
array.
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=1to overwrite an existing machine settings
file,UUID=<uuid>to specify a machine UUID anddirectoryIncludesUUID=1to switch to a special VM directory
naming scheme which should not be used unless necessary.
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | osTypeId is invalid. |
@link ::VBOX_E_FILE_ERROR 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. |
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)
registerMachine(org.virtualbox_5_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.
settingsFile
- Name of the machine settings file.
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Settings file name invalid, not found or sharing violation. |
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)
or opened usingopenMachine(String)
within this VirtualBox installation. After
successful method invocation, theIMachineRegisteredEvent
event is fired.
Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | No matching virtual machine found. |
@link ::VBOX_E_INVALID_OBJECT_STATE 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)
nameOrId
- What to search for. This can either be the UUID or the name of a virtual machine.
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | Could not find registered machine matching nameOrId. |
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 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.
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".
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | format identifier is invalid. SeeISystemProperties.getMediumFormats() . |
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | location is a not valid file name (for file-based formats only). |
public IMedium openMedium(java.lang.String location, DeviceType deviceType, AccessMode accessMode, java.lang.Boolean forceNewUuid)
IMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_0.DeviceType,org.virtualbox_5_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_5_0.IMedium,List,org.virtualbox_5_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.
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.
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Invalid medium storage file location or could not find the medium at the specified location. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Could not get medium storage format. |
E_INVALIDARG | Invalid medium storage format. |
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE | Medium has already been added to a media registry. |
public IGuestOSType getGuestOSType(java.lang.String id)
IMachine.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.
id
- Guest OS type ID string.
E_INVALIDARG | id is not a valid Guest OS type. |
public void createSharedFolder(java.lang.String name, java.lang.String hostPath, java.lang.Boolean writable, java.lang.Boolean automount)
ISharedFolder
to read more about logical names.
name
- Unique logical name of the shared folder.hostPath
- Full path to the shared folder in the host file system.writable
- Whether the share is writable or readonlyautomount
- Whether the share gets automatically mounted by the guest
or not.
NOTE: In the current implementation, this operation is not
implemented.public void removeSharedFolder(java.lang.String name)
createSharedFolder(String,String,Boolean,Boolean)
from the collection of
shared folders and stops sharing it.
name
- Logical name of the shared folder to remove.
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)
key
- Name of the data key to get.
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Settings file not accessible. |
@link ::VBOX_E_XML_ERROR VBOX_E_XML_ERROR | Could not parse the settings file. |
public void setExtraData(java.lang.String key, java.lang.String value)
key
- Name of the data key to set.value
- Value to assign to the key.
Expected result codes:
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERROR | Settings file not accessible. |
@link ::VBOX_E_XML_ERROR VBOX_E_XML_ERROR | Could not parse the settings file. |
E_ACCESSDENIED | Modification request refused. |
IExtraDataCanChangeEvent
notification for a permission. If one of the listeners refuses the
new value, the change will not be performed.
NOTE: On success, theIExtraDataChangedEvent
notification
is called to inform all registered listeners about a successful data
change.public void setSettingsSecret(java.lang.String password)
password
- The cipher key.
Expected result codes:
@link ::VBOX_E_INVALID_VM_STATE VBOX_E_INVALID_VM_STATE | Virtual machine is not mutable. |
public IDHCPServer createDHCPServer(java.lang.String name)
name
- server name
E_INVALIDARG | Host network interface name already exists. |
public IDHCPServer findDHCPServerByNetworkName(java.lang.String name)
name
- server name
E_INVALIDARG | Host network interface name already exists. |
public void removeDHCPServer(IDHCPServer server)
server
- DHCP server settings to be removed
Expected result codes:
E_INVALIDARG | Host network interface name already exists. |
public INATNetwork createNATNetwork(java.lang.String networkName)
public INATNetwork findNATNetworkByName(java.lang.String networkName)
public void removeNATNetwork(INATNetwork 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.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |