Public Member Functions | |
void | composeMachineFilename (in wstring name, in wstring baseFolder,[retval] out wstring file) |
Returns a recommended full path of the settings file name for a new virtual machine. | |
void | createMachine (in wstring settingsFile, in wstring name, in wstring osTypeId, in wstringUUID id, in boolean forceOverwrite,[retval] out IMachine machine) |
Creates a new virtual machine by creating a machine settings file at the given location. | |
void | openMachine (in wstring settingsFile,[retval] out IMachine machine) |
Opens a virtual machine from the existing settings file. | |
void | registerMachine (in IMachine machine) |
Registers the machine previously created using createMachine or opened using openMachine within this VirtualBox installation. | |
void | findMachine (in wstring nameOrId,[retval] out IMachine machine) |
Attempts to find a virtual machine given its name or UUID. | |
void | createAppliance ([retval] out IAppliance appliance) |
Creates a new appliance object, which represents an appliance in the Open Virtual Machine Format (OVF). | |
void | createHardDisk (in wstring format, in wstring location,[retval] out IMedium medium) |
Creates a new base medium object that will use the given storage format and location for medium data. | |
void | openMedium (in wstring location, in DeviceType deviceType, in AccessMode accessMode,[retval] out IMedium medium) |
Opens a medium from an existing storage location. | |
void | findMedium (in wstring location, in DeviceType type,[retval] out IMedium medium) |
Returns a medium of the given type that uses the given fully qualified location or UUID to store medium data. | |
void | getGuestOSType (in wstringUUID id,[retval] out IGuestOSType type) |
Returns an object describing the specified guest OS type. | |
void | createSharedFolder (in wstring name, in wstring hostPath, in boolean writable, in 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. | |
void | removeSharedFolder (in wstring name) |
Removes the global shared folder with the given name previously created by createSharedFolder from the collection of shared folders and stops sharing it. | |
void | getExtraDataKeys ([retval] out wstring[] value) |
Returns an array representing the global extra data keys which currently have values defined. | |
void | getExtraData (in wstring key,[retval] out wstring value) |
Returns associated global extra data. | |
void | setExtraData (in wstring key, in wstring value) |
Sets associated global extra data. | |
void | createDHCPServer (in wstring name,[retval] out IDHCPServer server) |
Creates a dhcp server settings to be used for the given internal network name. | |
void | findDHCPServerByNetworkName (in wstring name,[retval] out IDHCPServer server) |
Searches a dhcp server settings to be used for the given internal network name. | |
void | removeDHCPServer (in IDHCPServer server) |
Removes the dhcp server settings. | |
void | checkFirmwarePresent (in FirmwareType firmwareType, in wstring version, out wstring url, out wstring file,[retval] out boolean result) |
Check if this VirtualBox installation has a firmware of the given type available, either system-wide or per-user. | |
Public Attributes | |
readonly attribute wstring | version |
A string representing the version number of the product. | |
readonly attribute unsigned long | revision |
The internal build revision number of the product. | |
readonly attribute wstring | packageType |
A string representing the package type of this product. | |
readonly attribute wstring | homeFolder |
Full path to the directory where the global settings file, VirtualBox.xml , is stored. | |
readonly attribute wstring | settingsFilePath |
Full name of the global settings file. | |
readonly attribute IHost | host |
Associated host object. | |
readonly attribute ISystemProperties | systemProperties |
Associated system information object. | |
readonly attribute IMachine[] | machines |
Array of machine objects registered within this VirtualBox instance. | |
readonly attribute IMedium[] | hardDisks |
Array of medium objects known to this VirtualBox installation. | |
readonly attribute IMedium[] | DVDImages |
Array of CD/DVD image objects currently in use by this VirtualBox instance. | |
readonly attribute IMedium[] | floppyImages |
Array of floppy image objects currently in use by this VirtualBox instance. | |
readonly attribute IProgress[] | progressOperations |
readonly attribute IGuestOSType[] | guestOSTypes |
readonly attribute ISharedFolder[] | sharedFolders |
Collection of global shared folders. | |
readonly attribute IPerformanceCollector | performanceCollector |
Associated performance collector object. | |
readonly attribute IDHCPServer[] | DHCPServers |
DHCP servers. | |
readonly attribute IEventSource | eventSource |
Event source for VirtualBox events. | |
readonly attribute IExtPackManager | extensionPackManager |
The extension pack manager. |
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 IVirtualBox::machines attribute.
{D2DE270C-1D4B-4C9E-843F-BBB9B47269FF}
void IVirtualBox::composeMachineFilename | ( | in wstring | name, | |
in wstring | baseFolder, | |||
[retval] out wstring | file | |||
) |
Returns a recommended full path of the settings file name for a new virtual machine.
This API serves two purposes:
See IMachine::name and createMachine 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::defaultMachineFolder) 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). | |
file | Fully qualified path where the machine would be created. |
void IVirtualBox::createMachine | ( | in wstring | settingsFile, | |
in wstring | name, | |||
in wstring | osTypeId, | |||
in wstringUUID | id, | |||
in boolean | forceOverwrite, | |||
[retval] out IMachine | machine | |||
) |
Creates a new virtual machine by creating a machine settings file at the given location.
VirtualBox machine settings files use a custom XML dialect. Starting with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced, and machine files can be created at arbitrary locations.
However, it is is recommended that machines be created in the default machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see ISystemProperties::defaultMachineFolder). If you specify NULL for the settingsFile argument, composeMachineFilename 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:
The specified guest OS type identifier must match an ID of one of known guest OS types listed in the IVirtualBox::guestOSTypes 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). | |
name | Machine name. | |
osTypeId | Guest OS Type ID. | |
id | Machine UUID (optional). | |
forceOverwrite | If true, an existing machine settings file will be overwritten. | |
machine | Created machine object. |
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 . |
void IVirtualBox::openMachine | ( | in wstring | settingsFile, | |
[retval] out IMachine | machine | |||
) |
Opens a virtual machine from the existing settings file.
The opened machine remains unregistered until you call registerMachine.
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. | |
machine | Opened machine object. |
VBOX_E_FILE_ERROR | Settings file name invalid, not found or sharing violation. |
void IVirtualBox::registerMachine | ( | in IMachine | machine | ) |
Registers the machine previously created using createMachine or opened using openMachine within this VirtualBox installation.
After successful method invocation, the IMachineRegisteredEvent 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. |
void IVirtualBox::findMachine | ( | in wstring | nameOrId, | |
[retval] out IMachine | machine | |||
) |
Attempts to find a virtual machine given its name or UUID.
nameOrId | What to search for. This can either be the UUID or the name of a virtual machine. | |
machine | Machine object, if found. |
VBOX_E_OBJECT_NOT_FOUND | Could not find registered machine matching nameOrId. |
void IVirtualBox::createAppliance | ( | [retval] out IAppliance | appliance | ) |
Creates a new appliance object, which represents an appliance in the Open Virtual Machine Format (OVF).
This can then be used to import an OVF appliance into VirtualBox or to export machines as an OVF appliance; see the documentation for IAppliance for details.
appliance | New appliance. |
void IVirtualBox::createHardDisk | ( | in wstring | format, | |
in wstring | location, | |||
[retval] out IMedium | medium | |||
) |
Creates a new base medium object that will use the given storage format and location for medium data.
Note that the actual storage unit is not created by this method. In order to do it, and before you are able to attach the created medium to virtual machines, you must call one of the following methods to allocate a format-specific storage unit at the specified location:
Some medium attributes, such as IMedium::id, 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 method and can be found in the hardDisks array.
The list of all storage formats supported by this VirtualBox installation can be obtained using ISystemProperties::mediumFormats. If the format attribute is empty or null
then the default storage format specified by ISystemProperties::defaultHardDiskFormat 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::location 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. | |
medium | Created medium object. |
VBOX_E_OBJECT_NOT_FOUND | format identifier is invalid. See ISystemProperties::mediumFormats. |
VBOX_E_FILE_ERROR | location is a not valid file name (for file-based formats only). |
void IVirtualBox::openMedium | ( | in wstring | location, | |
in DeviceType | deviceType, | |||
in AccessMode | accessMode, | |||
[retval] out IMedium | medium | |||
) |
Opens a medium from an existing storage location.
Once a medium has been opened, it can be passed to other VirtualBox methods, in particular to IMachine::attachDevice.
Depending on the given device type, the file at the storage location must be in one of the media formats understood by VirtualBox:
After having been opened, the medium can be found by the findMedium 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.
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 when the image will be closed again soon.
The format of the location string is storage format specific. See IMedium::location 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. | |
medium | Opened medium object. |
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. |
void IVirtualBox::findMedium | ( | in wstring | location, | |
in DeviceType | type, | |||
[retval] out IMedium | medium | |||
) |
Returns a medium of the given type that uses the given fully qualified location or UUID to store medium data.
The given medium must be known to this VirtualBox installation, i.e. it must be previously created by createHardDisk or opened by openMedium.
The search is done by comparing the value of the location argument to the IMedium::location and IMedium::id 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) | |
medium | Medium object, if found. |
VBOX_E_OBJECT_NOT_FOUND | No medium object matching location found. |
void IVirtualBox::getGuestOSType | ( | in wstringUUID | id, | |
[retval] out IGuestOSType | type | |||
) |
Returns an object describing the specified guest OS type.
The requested guest OS type is specified using a string which is a mnemonic identifier of the guest operating system, such as "win31"
or "ubuntu"
. The guest OS type ID of a particular virtual machine can be read or set using the IMachine::OSTypeId attribute.
The IVirtualBox::guestOSTypes collection contains all available guest OS type objects. Each object has an IGuestOSType::id attribute which contains an identifier of the guest OS this object describes.
id | Guest OS type ID string. | |
type | Guest OS type object. |
E_INVALIDARG | id is not a valid Guest OS type. |
void IVirtualBox::createSharedFolder | ( | in wstring | name, | |
in wstring | hostPath, | |||
in boolean | writable, | |||
in 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.
Refer to the description of 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 readonly | |
automount | Whether the share gets automatically mounted by the guest or not. |
void IVirtualBox::removeSharedFolder | ( | in wstring | name | ) |
Removes the global shared folder with the given name previously created by createSharedFolder from the collection of shared folders and stops sharing it.
name | Logical name of the shared folder to remove. |
void IVirtualBox::getExtraDataKeys | ( | [retval] out wstring[] | value | ) |
Returns an array representing the global extra data keys which currently have values defined.
value | Array of extra data keys. |
void IVirtualBox::getExtraData | ( | in wstring | key, | |
[retval] out wstring | value | |||
) |
Returns associated global extra data.
If the requested data key does not exist, this function will succeed and return an empty string in the value argument.
key | Name of the data key to get. | |
value | Value of the requested data key. |
VBOX_E_FILE_ERROR | Settings file not accessible. |
VBOX_E_XML_ERROR | Could not parse the settings file. |
void IVirtualBox::setExtraData | ( | in wstring | key, | |
in wstring | value | |||
) |
Sets associated global extra data.
If you pass null
or empty string as a key value, the given key will be deleted.
key | Name of the data key to set. | |
value | Value to assign to the key. |
VBOX_E_FILE_ERROR | Settings file not accessible. |
VBOX_E_XML_ERROR | Could not parse the settings file. |
E_ACCESSDENIED | Modification request refused. |
On success, the IExtraDataChangedEvent notification is called to inform all registered listeners about a successful data change.
void IVirtualBox::createDHCPServer | ( | in wstring | name, | |
[retval] out IDHCPServer | server | |||
) |
Creates a dhcp server settings to be used for the given internal network name.
name | server name | |
server | Dhcp server settings |
E_INVALIDARG | Host network interface name already exists. |
void IVirtualBox::findDHCPServerByNetworkName | ( | in wstring | name, | |
[retval] out IDHCPServer | server | |||
) |
Searches a dhcp server settings to be used for the given internal network name.
name | server name | |
server | Dhcp server settings |
E_INVALIDARG | Host network interface name already exists. |
void IVirtualBox::removeDHCPServer | ( | in IDHCPServer | server | ) |
Removes the dhcp server settings.
server | Dhcp server settings to be removed |
E_INVALIDARG | Host network interface name already exists. |
void IVirtualBox::checkFirmwarePresent | ( | in FirmwareType | firmwareType, | |
in wstring | version, | |||
out wstring | url, | |||
out wstring | file, | |||
[retval] out boolean | result | |||
) |
Check if this VirtualBox installation has a firmware of the given type available, either system-wide or per-user.
Optionally, this may return a hint where this firmware can be downloaded from.
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. | |
result | If firmware of this type and version is available. |
readonly attribute wstring IVirtualBox::version |
A string representing the version number of the product.
The format is 3 integer numbers divided by dots (e.g. 1.0.1). The last number represents the build number and will frequently change.
readonly attribute unsigned long IVirtualBox::revision |
The internal build revision number of the product.
readonly attribute wstring IVirtualBox::packageType |
A string representing the package type of this product.
The format is OS_ARCH_DIST where OS is either WINDOWS, LINUX, SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST is either GENERIC, UBUNTU_606, UBUNTU_710, or something like this.
readonly attribute wstring IVirtualBox::homeFolder |
Full path to the directory where the global settings file, 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).
readonly attribute wstring IVirtualBox::settingsFilePath |
Full name of the global settings file.
The value of this property corresponds to the value of homeFolder plus /VirtualBox.xml
.
readonly attribute IHost IVirtualBox::host |
Associated host object.
readonly attribute ISystemProperties IVirtualBox::systemProperties |
Associated system information object.
readonly attribute IMachine [] IVirtualBox::machines |
Array of machine objects registered within this VirtualBox instance.
readonly attribute IMedium [] IVirtualBox::hardDisks |
Array of medium objects known to this VirtualBox installation.
This array contains only base media. All differencing media of the given base medium can be enumerated using IMedium::children.
readonly attribute IMedium [] IVirtualBox::DVDImages |
Array of CD/DVD image objects currently in use by this VirtualBox instance.
readonly attribute IMedium [] IVirtualBox::floppyImages |
Array of floppy image objects currently in use by this VirtualBox instance.
readonly attribute IProgress [] IVirtualBox::progressOperations |
readonly attribute IGuestOSType [] IVirtualBox::guestOSTypes |
readonly attribute ISharedFolder [] IVirtualBox::sharedFolders |
Collection of global shared folders.
Global shared folders are available to all virtual machines.
New shared folders are added to the collection using createSharedFolder. Existing shared folders can be removed using removeSharedFolder.
readonly attribute IPerformanceCollector IVirtualBox::performanceCollector |
Associated performance collector object.
readonly attribute IDHCPServer [] IVirtualBox::DHCPServers |
DHCP servers.
readonly attribute IEventSource IVirtualBox::eventSource |
Event source for VirtualBox events.
readonly attribute IExtPackManager IVirtualBox::extensionPackManager |
The extension pack manager.