|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.virtualbox_4_1.IUnknown
org.virtualbox_4_1.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 the
getMachines()
attribute.
Interface ID: {C28BE65F-1A8F-43B4-81F1-EB60CB516E66}
Field Summary |
---|
Fields inherited from class org.virtualbox_4_1.IUnknown |
---|
obj, port |
Constructor Summary | |
---|---|
IVirtualBox(java.lang.String wrapped,
org.virtualbox_4_1.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 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 |
IMedium |
createHardDisk(java.lang.String format,
java.lang.String location)
Creates a new base medium object that will use the given storage format and location for medium data. |
IMachine |
createMachine(java.lang.String settingsFile,
java.lang.String name,
java.lang.String osTypeId,
java.lang.String id,
java.lang.Boolean forceOverwrite)
Creates a new virtual machine by creating a machine settings file at the given location. |
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. |
IMedium |
findMedium(java.lang.String location,
DeviceType type)
Returns a medium of the given type that uses the given fully qualified location or UUID to store medium data. |
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<IMachine> |
getMachines()
Array of machine objects registered within this VirtualBox instance. |
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. |
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)
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,String,String,Boolean) or opened using
openMachine(String) within this VirtualBox installation. |
void |
removeDHCPServer(IDHCPServer server)
Removes the dhcp server settings |
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. |
Methods inherited from class org.virtualbox_4_1.IUnknown |
---|
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_4_1.jaxws.VboxPortType port)
Method Detail |
---|
public java.lang.String getVersion()
public java.lang.Long getRevision()
public java.lang.String getPackageType()
public java.lang.String getAPIVersion()
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<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 using removeSharedFolder(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 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 baseFolder)
createMachine(String,String,String,String,Boolean)
if NULL is specified
for the settingsFile argument there, which means that API should use
a recommended default file name.IMachine.getName()
and createMachine(String,String,String,String,Boolean)
for more
details about the machine name.
If baseFolder is a null or empty string (which is recommended), the
default machine settings folder
(see ISystemProperties.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 of this name already exists.
name
- Suggested machine name.baseFolder
- Base machine folder (optional).
public IMachine createMachine(java.lang.String settingsFile, java.lang.String name, java.lang.String osTypeId, java.lang.String id, java.lang.Boolean forceOverwrite)
ISystemProperties.getDefaultMachineFolder()
). If you specify
NULL for the settingsFile argument, composeMachineFilename(String,String)
is called automatically to have such a recommended name composed based
on the machine name given in the name argument.
If the resulting settings file already exists, this method will fail,
unless forceOverwrite 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_4_1.IMachine)
to add the machine to the list
of machines known to VirtualBox.
getGuestOSTypes()
array.
Optionally, you may specify an UUID of to assign to the created machine.
However, this is not recommended and you should normally pass an empty
( null) UUID to this method so that a new UUID will be automatically
generated for every created machine. You can use UUID
00000000-0000-0000-0000-000000000000 as null value.
settingsFile
- Fully qualified path where the settings file should be created,
or NULL for a default folder and file based on the name argument
(see composeMachineFilename(String,String)
).name
- Machine name.osTypeId
- Guest OS Type ID.id
- Machine UUID (optional).forceOverwrite
- If true, an existing machine settings file will be overwritten.
@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. |
public IMachine openMachine(java.lang.String settingsFile)
registerMachine(org.virtualbox_4_1.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. |
public void registerMachine(IMachine machine)
createMachine(String,String,String,String,Boolean)
or opened using
openMachine(String)
within this VirtualBox installation. After
successful method invocation, the
IMachineRegisteredEvent
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 IAppliance createAppliance()
IAppliance
for details.
public IMedium createHardDisk(java.lang.String format, java.lang.String location)
IMedium.getId()
, may
remain uninitialized until the medium storage unit is successfully
created by one of the above methods.
After the storage unit is successfully created, it will be
accessible through the findMedium(String,org.virtualbox_4_1.DeviceType)
method and can
be found in the getHardDisks()
array.
The list of all storage formats supported by this VirtualBox
installation can be obtained using
ISystemProperties.getMediumFormats()
. If the format
attribute is empty or null then the default storage format
specified by ISystemProperties.getDefaultHardDiskFormat()
will
be used for creating a storage unit of the medium.
Note that the format of the location string is storage format specific.
See IMedium.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.
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND |
format identifier is invalid. See
ISystemProperties.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_4_1.DeviceType,org.virtualbox_4_1.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 the getHardDisks()
array attribute. getDVDImages()
array attribute.getFloppyImages()
array attribute.findMedium(String,org.virtualbox_4_1.DeviceType)
method and can be attached to virtual machines. See 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, use
IMedium.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 (see IMedium.cloneTo(org.virtualbox_4_1.IMedium,Long,org.virtualbox_4_1.IMedium)
when the image will be closed
again soon.
The format of the location string is storage format specific. See
IMedium.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 IMedium findMedium(java.lang.String location, DeviceType type)
createHardDisk(String,String)
or opened
by openMedium(String,org.virtualbox_4_1.DeviceType,org.virtualbox_4_1.AccessMode,Boolean)
.
The search is done by comparing the value of the location argument to
the IMedium.getLocation()
and IMedium.getId()
attributes of each known medium.
On case sensitive file systems, a case sensitive comparison is performed,
otherwise the case of symbols in the file path is ignored.
location
- What to search for. This can either be the UUID or the location string of an open medium.type
- Device type (must be HardDisk, DVD or Floppy)
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | No medium object matching location found. |
public IGuestOSType getGuestOSType(java.lang.String id)
IMachine.getOSTypeId()
attribute.
The getGuestOSTypes()
collection contains all
available guest OS type objects. Each object has an
IGuestOSType.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, the
IExtraDataChangedEvent
notification
is called to inform all registered listeners about a successful data
change.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 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 |