IVirtualBox Interface Reference

The IVirtualBox interface represents the main interface exposed by the product that provides virtual machine management. More...

Inheritance diagram for IVirtualBox:

Public Member Functions
void	composeMachineFilename (in wstring name, in wstring group, in wstring createFlags, in wstring baseFolder, [retval] out wstring file)
	Returns a recommended full path of the settings file name for a new virtual machine.
void	getPlatformProperties (in PlatformArchitecture architecture, [retval] out IPlatformProperties properties)
	Gets the associated properties object for the given VM platform architecture.
void	createMachine (in wstring settingsFile, in wstring name, in PlatformArchitecture platform, in wstring[] groups, in wstring osTypeId, in wstring flags, in wstring cipher, in wstring passwordId, in wstring password, [retval] out IMachine machine)
	Creates a new virtual machine by creating a machine settings file at the given location.
void	openMachine (in wstring settingsFile, in wstring password, [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	getMachinesByGroups (in wstring[] groups, [retval] out IMachine[] machines)
	Gets all machine references which are in one of the specified groups.
void	getMachineStates (in IMachine[] machines, [retval] out MachineState[] states)
	Gets the state of several machines in a single operation.
void	createAppliance ([retval] out IAppliance appliance)
	Creates a new appliance object, which represents an appliance in the Open Virtual Machine Format (OVF).
void	createUnattendedInstaller ([retval] out IUnattended unattended)
	Creates a new IUnattended guest installation object.
void	createMedium (in wstring format, in wstring location, in AccessMode accessMode, in DeviceType aDeviceTypeType, [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, in boolean forceNewUuid, [retval] out IMedium medium)
	Finds existing media or opens a medium from an existing storage location.
void	getGuestOSType (in wstring id, [retval] out IGuestOSType type)
	Returns an object describing the specified guest OS type.
void	getGuestOSSubtypesByFamilyId (in wstring family, [retval] out wstring[] OSsubtypes)
	Returns a list of guest OS family subtypes for a corresponding guest OS family ID type.
void	getGuestOSDescsBySubtype (in wstring OSSubtype, [retval] out wstring[] GuestOSDescs)
	Returns a list of guest OS family descriptions for a corresponding guest OS family subtype.
void	createSharedFolder (in wstring name, in wstring hostPath, in boolean writable, in boolean automount, in wstring 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.
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[] keys)
	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	setSettingsSecret (in wstring password)
	Unlocks the secret data by passing the unlock password to the server.
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	createNATNetwork (in wstring networkName, [retval] out INATNetwork network)
void	findNATNetworkByName (in wstring networkName, [retval] out INATNetwork network)
void	removeNATNetwork (in INATNetwork network)
void	createHostOnlyNetwork (in wstring networkName, [retval] out IHostOnlyNetwork network)
void	findHostOnlyNetworkByName (in wstring networkName, [retval] out IHostOnlyNetwork network)
void	findHostOnlyNetworkById (in wstringUUID id, [retval] out IHostOnlyNetwork network)
	Searches through all host networks for one with the given GUID.
void	removeHostOnlyNetwork (in IHostOnlyNetwork network)
void	createCloudNetwork (in wstring networkName, [retval] out ICloudNetwork network)
void	findCloudNetworkByName (in wstring networkName, [retval] out ICloudNetwork network)
void	removeCloudNetwork (in ICloudNetwork network)
void	checkFirmwarePresent (in PlatformArchitecture platformArchitecture, 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.
void	findProgressById (in wstringUUID id, [retval] out IProgress progressObject)
	Searches through all progress objects known to VBoxSVC for an instance with the given GUID.

Public Attributes
readonly attribute wstring	version
	A string representing the version number of the product.
readonly attribute wstring	versionNormalized
	A string representing the version number of the product, without the publisher information (but still with other tags).
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	APIVersion
	A string representing the VirtualBox API version number.
readonly attribute long long	APIRevision
	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.
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 wstring[]	machineGroups
	Array of all machine group names which are used by the machines which are accessible.
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
	Array of all guest OS type objects known to this VirtualBox installation.
readonly attribute wstring[]	guestOSFamilies
	Array of guest OS family identifiers known to this VirtualBox installation.
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 INATNetwork[]	NATNetworks
readonly attribute IEventSource	eventSource
	Event source for VirtualBox events.
readonly attribute IExtPackManager	extensionPackManager
	The extension pack manager.
readonly attribute wstring[]	internalNetworks
	Names of all internal networks.
readonly attribute IHostOnlyNetwork[]	hostOnlyNetworks
	Names of all host-only networks.
readonly attribute wstring[]	genericNetworkDrivers
	Names of all generic network drivers.
readonly attribute ICloudNetwork[]	cloudNetworks
	Names of all configured cloud networks.
readonly attribute ICloudProviderManager	cloudProviderManager
	The cloud provider manager (singleton).

Detailed Description

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 IVirtualBox::machines 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:

{D644AD1E-C501-4FC7-9AB6-AA6D763BC540}

Member Function Documentation

composeMachineFilename()

void IVirtualBox::composeMachineFilename	(	in wstring	name,
		in wstring	group,
		in wstring	createFlags,
		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:

• It gets called by createMachine 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.
• It can be called manually by a client software before creating a machine, e.g. if that client wants to pre-create the machine directory to create virtual hard disks in that directory together with the new machine settings file. In that case, the file name should be stripped from the full settings file path returned by this function to obtain the machine directory.

See IMachine::name and createMachine 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 (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 with this name already exists.

Parameters

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, see createMachine (optional).
baseFolder	Base machine folder (optional).
file	Fully qualified path where the machine would be created.

getPlatformProperties()

void IVirtualBox::getPlatformProperties	(	in PlatformArchitecture	architecture,
		[retval] out IPlatformProperties	properties
	)

Gets the associated properties object for the given VM platform architecture.

Parameters

architecture	The platform architecture to return the platform properties for.
properties	Returned platform properties.

createMachine()

void IVirtualBox::createMachine	(	in wstring	settingsFile,
		in wstring	name,
		in PlatformArchitecture	platform,
		in wstring[]	groups,
		in wstring	osTypeId,
		in wstring	flags,
		in wstring	cipher,
		in wstring	passwordId,
		in wstring	password,
		[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 recommended that machines are created in the default machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see ISystemProperties::defaultMachineFolder). If you specify null or empty string (which is recommended) 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 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:

1. Call this method to have a new machine created. The returned machine object will be "mutable" allowing to change any machine property.
2. Configure the machine using the appropriate attributes and methods.
3. Call 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.
4. Call registerMachine to add the machine to the list of machines known to VirtualBox.

The specified guest OS type identifier must match an ID of one of known guest OS types listed in the IVirtualBox::guestOSTypes array.

Parameters

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. (see composeMachineFilename).
name	Machine name.
platform	The platform architecture for the new VM.
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 and directoryIncludesUUID=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.
machine	Created machine object.

Expected result codes:

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.

Note

IMachine::settingsModified will return false for the created machine, until any of machine settings are changed.

There is no way to change the name of the settings file or subfolder of the created machine directly.

openMachine()

void IVirtualBox::openMachine	(	in wstring	settingsFile,
		in wstring	password,
		[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.

Parameters

settingsFile	Name of the machine settings file.
password	The password. If the machine is not encrypted the parameter is ignored.
machine	Opened machine object.

Expected result codes:

VBOX_E_FILE_ERROR

Settings file name invalid, not found or sharing violation.

Note

If the VM is encrypted and password is incorrect the method returns success allowing you to register the encrypted machine but it remains in inaccessible state. You can check IMachine::accessible and IMachine::accessError properties to determine the real machine state.

IMachine::settingsModified will return false for the opened machine, until any of machine settings are changed.

registerMachine()

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.

Expected result codes:

VBOX_E_OBJECT_NOT_FOUND	No matching virtual machine found.
VBOX_E_INVALID_OBJECT_STATE	Virtual machine was not created within this VirtualBox instance.

Note

This method implicitly calls IMachine::saveSettings to save all current machine settings before registering it.

findMachine()

void IVirtualBox::findMachine	(	in wstring	nameOrId,
		[retval] out IMachine	machine
	)

Attempts to find a virtual machine given its name or UUID.

Parameters

nameOrId	What to search for. This can either be the UUID or the name of a virtual machine.
machine	Machine object, if found.

Expected result codes:

VBOX_E_OBJECT_NOT_FOUND

Could not find registered machine matching nameOrId.

Note

Inaccessible machines cannot be found by name, only by UUID, because their name cannot safely be determined.

getMachinesByGroups()

void IVirtualBox::getMachinesByGroups	(	in wstring[]	groups,
		[retval] out IMachine[]	machines
	)

Gets all machine references which are in one of the specified groups.

Parameters

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.
machines	All machines which matched.

getMachineStates()

void IVirtualBox::getMachineStates	(	in IMachine[]	machines,
		[retval] out MachineState[]	states
	)

Gets the state of several machines in a single operation.

Parameters

machines	Array with the machine references.
states	Machine states, corresponding to the machines.

createAppliance()

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.

Parameters

appliance

New appliance.

createUnattendedInstaller()

void IVirtualBox::createUnattendedInstaller

(

[retval] out IUnattended

unattended

)

Creates a new 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.

Parameters

unattended

New unattended object.

createMedium()

void IVirtualBox::createMedium	(	in wstring	format,
		in wstring	location,
		in AccessMode	accessMode,
		in DeviceType	aDeviceTypeType,
		[retval] out IMedium	medium
	)

Creates a new base medium object that will use the given storage format and location for medium data.

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:

• IMedium::createBaseStorage
• IMedium::createDiffStorage

Some medium attributes, such as IMedium::id, 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:

• With a "HardDisk" device type, the file must be a hard disk image in one of the formats supported by VirtualBox (see ISystemProperties::mediumFormats). After the storage unit is successfully created and this method succeeds, if the medium is a base medium, it will be added to the hardDisks array attribute.
• With a "DVD" device type, the file must be an ISO 9960 CD/DVD image. After this method succeeds, the medium will be added to the DVDImages array attribute.
• With a "Floppy" device type, the file must be an RAW floppy image. After this method succeeds, the medium will be added to the floppyImages array attribute.

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 disks r 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.

Parameters

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".
medium	Created medium object.

Expected result codes:

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

openMedium()

void IVirtualBox::openMedium	(	in wstring	location,
		in DeviceType	deviceType,
		in AccessMode	accessMode,
		in boolean	forceNewUuid,
		[retval] out IMedium	medium
	)

Finds existing media or 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:

• With a "HardDisk" device type, the file must be a hard disk image in one of the formats supported by VirtualBox (see ISystemProperties::mediumFormats). After this method succeeds, if the medium is a base medium, it will be added to the hardDisks array attribute.
• With a "DVD" device type, the file must be an ISO 9960 CD/DVD image. After this method succeeds, the medium will be added to the DVDImages array attribute.
• With a "Floppy" device type, the file must be an RAW floppy image. After this method succeeds, the medium will be added to the floppyImages array attribute.

After having been opened, the medium can be re-found by this 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.

Parameters

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.
medium	Opened medium object.

Expected result codes:

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.

getGuestOSType()

void IVirtualBox::getGuestOSType	(	in wstring	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.

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

Parameters

id	Guest OS type ID string.
type	Guest OS type object.

Expected result codes:

E_INVALIDARG

id is not a valid Guest OS type.

getGuestOSSubtypesByFamilyId()

void IVirtualBox::getGuestOSSubtypesByFamilyId	(	in wstring	family,
		[retval] out wstring[]	OSsubtypes
	)

Returns a list of guest OS family subtypes for a corresponding guest OS family ID type.

The IVirtualBox::guestOSTypes collection contains all available guest OS type objects. Each object has an IGuestOSType::familyId attribute which contains a the guest OS family this object describes. The guest OS family subtype is contained in the IGuestOSType::subtype attribute.

Parameters

family	Guest OS type ID string.
OSsubtypes	Array of guest OS family subtypes associated with the specified guest OS family ID.

Expected result codes:

E_INVALIDARG

family is not a valid guest OS family identifier.

getGuestOSDescsBySubtype()

void IVirtualBox::getGuestOSDescsBySubtype	(	in wstring	OSSubtype,
		[retval] out wstring[]	GuestOSDescs
	)

Returns a list of guest OS family descriptions for a corresponding guest OS family subtype.

The IVirtualBox::guestOSTypes collection contains all available guest OS type objects. Each object has an IGuestOSType::subtype attribute which contains a human readable description of the guest OS subtype this object describes. The guest OS family description is contained in the IGuestOSType::familyDescription attribute.

Parameters

OSSubtype	Guest OS subtype.
GuestOSDescs	Array of guest OS descriptions associated with the specified guest OS subtype.

Expected result codes:

E_INVALIDARG

OSSubtype is not a valid guest OS subtype.

createSharedFolder()

void IVirtualBox::createSharedFolder	(	in wstring	name,
		in wstring	hostPath,
		in boolean	writable,
		in boolean	automount,
		in wstring	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.

Refer to the description of ISharedFolder to read more about logical names.

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

Note

In the current implementation, this operation is not implemented.

removeSharedFolder()

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.

Parameters

name	Logical name of the shared folder to remove.

Note

In the current implementation, this operation is not implemented.

getExtraDataKeys()

void IVirtualBox::getExtraDataKeys

(

[retval] out wstring[]

keys

)

Returns an array representing the global extra data keys which currently have values defined.

Parameters

keys	Array of extra data keys.

getExtraData()

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.

Parameters

key	Name of the data key to get.
value	Value of the requested data key.

Expected result codes:

VBOX_E_FILE_ERROR	Settings file not accessible.
VBOX_E_XML_ERROR	Could not parse the settings file.

setExtraData()

void IVirtualBox::setExtraData	(	in wstring	key,
		in wstring	value
	)

Sets associated global extra data.

If you pass null or an empty string as a key value, the given key will be deleted.

Parameters

key	Name of the data key to set.
value	Value to assign to the key.

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.
E_INVALIDARG	Key contains invalid characters.

Note

Key must contain printable (non-control) UTF-8 characters only.

Before performing the actual data change, this method will ask all registered event listeners using the IExtraDataCanChangeEvent notification for a permission. If one of the listeners refuses the new value, the change will not be performed.

On success, the IExtraDataChangedEvent notification is called to inform all registered listeners about a successful data change.

setSettingsSecret()

void IVirtualBox::setSettingsSecret

(

in wstring

password

)

Unlocks the secret data by passing the unlock password to the server.

The server will cache the password for that machine.

Parameters

password

The cipher key.

Expected result codes:

VBOX_E_INVALID_VM_STATE

Virtual machine is not mutable.

createDHCPServer()

void IVirtualBox::createDHCPServer	(	in wstring	name,
		[retval] out IDHCPServer	server
	)

Creates a DHCP server settings to be used for the given internal network name.

Parameters

name	server name
server	DHCP server settings

Expected result codes:

E_INVALIDARG

Host network interface name already exists.

findDHCPServerByNetworkName()

void IVirtualBox::findDHCPServerByNetworkName	(	in wstring	name,
		[retval] out IDHCPServer	server
	)

Searches a DHCP server settings to be used for the given internal network name.

Parameters

name	server name
server	DHCP server settings

Expected result codes:

E_INVALIDARG

Host network interface name already exists.

removeDHCPServer()

void IVirtualBox::removeDHCPServer

(

in IDHCPServer

server

)

Removes the DHCP server settings.

Parameters

server

DHCP server settings to be removed

Expected result codes:

E_INVALIDARG

Host network interface name already exists.

createNATNetwork()

void IVirtualBox::createNATNetwork	(	in wstring	networkName,
		[retval] out INATNetwork	network
	)

findNATNetworkByName()

void IVirtualBox::findNATNetworkByName	(	in wstring	networkName,
		[retval] out INATNetwork	network
	)

removeNATNetwork()

void IVirtualBox::removeNATNetwork

(

in INATNetwork

network

)

createHostOnlyNetwork()

void IVirtualBox::createHostOnlyNetwork	(	in wstring	networkName,
		[retval] out IHostOnlyNetwork	network
	)

findHostOnlyNetworkByName()

void IVirtualBox::findHostOnlyNetworkByName	(	in wstring	networkName,
		[retval] out IHostOnlyNetwork	network
	)

findHostOnlyNetworkById()

void IVirtualBox::findHostOnlyNetworkById	(	in wstringUUID	id,
		[retval] out IHostOnlyNetwork	network
	)

Searches through all host networks for one with the given GUID.

Parameters

id	GUID of the host-only network to search for.
network	Found host-only network object.

Note

The method returns an error if the given GUID does not correspond to any host network.

removeHostOnlyNetwork()

void IVirtualBox::removeHostOnlyNetwork

(

in IHostOnlyNetwork

network

)

createCloudNetwork()

void IVirtualBox::createCloudNetwork	(	in wstring	networkName,
		[retval] out ICloudNetwork	network
	)

findCloudNetworkByName()

void IVirtualBox::findCloudNetworkByName	(	in wstring	networkName,
		[retval] out ICloudNetwork	network
	)

removeCloudNetwork()

void IVirtualBox::removeCloudNetwork

(

in ICloudNetwork

network

)

checkFirmwarePresent()

void IVirtualBox::checkFirmwarePresent	(	in PlatformArchitecture	platformArchitecture,
		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.

Parameters

platformArchitecture	Architecture of firmware to check.
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.

findProgressById()

void IVirtualBox::findProgressById	(	in wstringUUID	id,
		[retval] out IProgress	progressObject
	)

Searches through all progress objects known to VBoxSVC for an instance with the given GUID.

Parameters

id	GUID of the progress object to search for.
progressObject	Found progress object.

Note

The method returns an error if the given GUID does not correspond to any currently known progress object.

Member Data Documentation

version

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.

This may be followed by a _ALPHA[0-9]*, _BETA[0-9]* or _RC[0-9]* tag in prerelease builds. Non-Oracle builds may (/shall) also have a publisher tag, at the end. The publisher tag starts with an underscore just like the prerelease build type tag.

versionNormalized

readonly attribute wstring IVirtualBox::versionNormalized

A string representing the version number of the product, without the publisher information (but still with other tags).

See version.

revision

readonly attribute unsigned long IVirtualBox::revision

The internal build revision number of the product.

packageType

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.

APIVersion

readonly attribute wstring IVirtualBox::APIVersion

A string representing the VirtualBox API version number.

The format is 2 integer numbers divided by an underscore (e.g. 1_0). After the first public release of packages with a particular API version the API will not be changed in an incompatible way. Note that this guarantee does not apply to development builds, and also there is no guarantee that this version is identical to the first two integer numbers of the package version.

APIRevision

readonly attribute long long IVirtualBox::APIRevision

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.

on trunk).

The high 7 bits (62:56) is the major version number, the next 8 bits (55:48) are the minor version number, the next 8 bits (47:40) are the build number, and the rest (39:0) is the API revision number.

The API revision number is manually increased on trunk when making incompatible changes that the validation kit or others needs to be able to detect and cope with dynamically. It can also be used to indicate the presence of new features on both trunk and branches.

homeFolder

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

settingsFilePath

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.

host

readonly attribute IHost IVirtualBox::host

Associated host object.

systemProperties

readonly attribute ISystemProperties IVirtualBox::systemProperties

Associated system information object.

machines

readonly attribute IMachine [] IVirtualBox::machines

Array of machine objects registered within this VirtualBox instance.

machineGroups

readonly attribute wstring [] IVirtualBox::machineGroups

Array of all machine group names which are used by the machines which are accessible.

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/subgroup" is a valid result).

hardDisks

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.

DVDImages

readonly attribute IMedium [] IVirtualBox::DVDImages

Array of CD/DVD image objects currently in use by this VirtualBox instance.

floppyImages

readonly attribute IMedium [] IVirtualBox::floppyImages

Array of floppy image objects currently in use by this VirtualBox instance.

progressOperations

readonly attribute IProgress [] IVirtualBox::progressOperations

guestOSTypes

readonly attribute IGuestOSType [] IVirtualBox::guestOSTypes

Array of all guest OS type objects known to this VirtualBox installation.

guestOSFamilies

readonly attribute wstring [] IVirtualBox::guestOSFamilies

Array of guest OS family identifiers known to this VirtualBox installation.

The guest OS family identifier corrresponds to the IGuestOSType::familyId attribute.

sharedFolders

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.

Note

In the current version of the product, global shared folders are not implemented and therefore this collection is always empty.

performanceCollector

readonly attribute IPerformanceCollector IVirtualBox::performanceCollector

Associated performance collector object.

DHCPServers

readonly attribute IDHCPServer [] IVirtualBox::DHCPServers

DHCP servers.

NATNetworks

readonly attribute INATNetwork [] IVirtualBox::NATNetworks

eventSource

readonly attribute IEventSource IVirtualBox::eventSource

Event source for VirtualBox events.

extensionPackManager

readonly attribute IExtPackManager IVirtualBox::extensionPackManager

The extension pack manager.

internalNetworks

readonly attribute wstring [] IVirtualBox::internalNetworks

Names of all internal networks.

hostOnlyNetworks

readonly attribute IHostOnlyNetwork [] IVirtualBox::hostOnlyNetworks

Names of all host-only networks.

genericNetworkDrivers

readonly attribute wstring [] IVirtualBox::genericNetworkDrivers

Names of all generic network drivers.

cloudNetworks

readonly attribute ICloudNetwork [] IVirtualBox::cloudNetworks

Names of all configured cloud networks.

cloudProviderManager

readonly attribute ICloudProviderManager IVirtualBox::cloudProviderManager

The cloud provider manager (singleton).