# IVirtualBox Interface Reference

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

List of all members.

## Public Member Functions
void | createMachine (in wstring baseFolder, in wstring name, in uuid id,[retval] out IMachine machine)
| Creates a new virtual machine.
void | createLegacyMachine (in wstring settingsFile, in wstring name, in uuid id,[retval] out IMachine machine)
| Creates a new virtual machine in "legacy" mode, using the specified settings file to store machine settings.
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 | getMachine (in uuid id,[retval] out IMachine machine)
| Attempts to find a virtual machine given its UUID.
void | findMachine (in wstring name,[retval] out IMachine machine)
| Attempts to find a virtual machine given its name.
void | unregisterMachine (in uuid id,[retval] out IMachine machine)
| Unregisters the machine previously registered using registerMachine.
void | createHardDisk (in HardDiskStorageType storageType,[retval] out IHardDisk hardDisk)
| Creates a new unregistered hard disk that will use the given storage type.
void | openHardDisk (in wstring location,[retval] out IHardDisk hardDisk)
| Opens a hard disk from an existing location.
void | openVirtualDiskImage (in wstring filePath,[retval] out IVirtualDiskImage image)
| Opens a hard disk from an existing Virtual Disk Image file.
void | registerHardDisk (in IHardDisk hardDisk)
| Registers the given hard disk within this VirtualBox installation.
void | getHardDisk (in uuid id,[retval] out IHardDisk hardDisk)
| Returns the registered hard disk with the given UUID.
void | findHardDisk (in wstring location,[retval] out IHardDisk hardDisk)
| Returns a registered hard disk that uses the given location to store data.
void | findVirtualDiskImage (in wstring filePath,[retval] out IVirtualDiskImage image)
| Returns a registered hard disk that uses the given image file.
void | unregisterHardDisk (in uuid id,[retval] out IHardDisk hardDisk)
| Unregisters a hard disk previously registered using registerHardDisk().
void | openDVDImage (in wstring filePath, in uuid id,[retval] out IDVDImage image)
| Opens the CD/DVD image contained in the specified file of the supported format and assigns it the given UUID.
void | registerDVDImage (in IDVDImage image)
| Registers a CD/DVD image within this VirtualBox installation.
void | getDVDImage (in uuid id,[retval] out IDVDImage image)
| Returns a registered CD/DVD image with the given UUID.
void | findDVDImage (in wstring filePath,[retval] out IDVDImage image)
| Returns a registered CD/DVD image with the given image file.
void | getDVDImageUsage (in uuid id, in ResourceUsage usage,[retval] out wstring machineIDs)
| Returns the list of of UUIDs of all virtual machines that use the given CD/DVD image.
void | unregisterDVDImage (in uuid id,[retval] out IDVDImage image)
| Unregisters the CD/DVD image previously registered using registerDVDImage().
void | openFloppyImage (in wstring filePath, in uuid id,[retval] out IFloppyImage image)
| Opens a floppy image contained in the specified file of the supported format and assigns it the given UUID.
void | registerFloppyImage (in IFloppyImage image)
| Registers a floppy image within this VirtualBox installation.
void | getFloppyImage (in uuid id,[retval] out IFloppyImage image)
| Returns a registered floppy image with the given UUID.
void | findFloppyImage (in wstring filePath,[retval] out IFloppyImage image)
| Returns a registered floppy image with the given image file.
void | getFloppyImageUsage (in uuid id, in ResourceUsage usage,[retval] out wstring machineIDs)
| Returns the list of of UUIDs of all virtual machines that use the given floppy image.
void | unregisterFloppyImage (in uuid id,[retval] out IFloppyImage image)
| Unregisters the floppy image previously registered using registerFloppyImage().
void | getGuestOSType (in wstring 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)
| 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 | getNextExtraDataKey (in wstring key, out wstring nextKey, out wstring nextValue)
| Returns the global extra data key name following the supplied key.
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 | openSession (in ISession session, in uuid machineId)
| Opens a new direct session with the given virtual machine.
void | openRemoteSession (in ISession session, in uuid machineId, in wstring type, in wstring environment,[retval] out IProgress progress)
| Spawns a new process that executes a virtual machine (called a "remote session").
void | openExistingSession (in ISession session, in uuid machineId)
| Opens a new remote session with the virtual machine for which a direct session is already open.
void | registerCallback (in IVirtualBoxCallback callback)
| Registers a new global VirtualBox callback.
void | unregisterCallback (in IVirtualBoxCallback callback)
| Unregisters the previously registered global VirtualBox callback.
void | waitForPropertyChange (in wstring what, in unsigned long timeout, out wstring changed, out wstring values)
| Blocks the caller until any of the properties represented by the what argument changes the value or until the given timeout interval expires.
void | saveSettings ()
| Saves the global settings to the global settings file (settingsFilePath).
void | saveSettingsWithBackup ([retval] out wstring bakFileName)
| Creates a backup copy of the global settings file (settingsFilePath) in case of auto-conversion, and then calls saveSettings().
## 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 wstring | settingsFileVersion
| Current version of the format of the global VirtualBox settings file (`VirtualBox.xml`).
readonly attribute wstring | settingsFormatVersion
| Most recent version of the settings file format.
readonly attribute IHost | host
| Associated host object.
readonly attribute ISystemProperties | systemProperties
| Associated system information object.
readonly attribute IMachineCollection | machines
| Collection of machine objects registered within this VirtualBox instance.
readonly attribute IMachine[] | machines2
| Array of machine objects registered within this VirtualBox instance.
readonly attribute IHardDiskCollection | hardDisks
| Collection of hard disk objects registered within this VirtualBox instance.
readonly attribute IDVDImageCollection | DVDImages
readonly attribute IFloppyImageCollection | FloppyImages
readonly attribute IProgressCollection | progressOperations
readonly attribute IGuestOSTypeCollection | guestOSTypes
readonly attribute ISharedFolderCollection | sharedFolders
| Collection of global shared folders.
readonly attribute IPerformanceCollector | performanceCollector
| Associated performance collector object.

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

Interface ID:
  `{557A07BC-E6AE-4520-A361-4A8493199137}`

## Member Function Documentation

void IVirtualBox::createMachine | ( | in wstring | baseFolder,
|  | in wstring | name,
|  | in uuid | id,
|  | [retval] out IMachine | machine |
| ) |  |  |

Creates a new virtual machine.

The new machine will have "empty" default settings and will not yet be registered. The typical sequence to create a virtual machine is therefore something like this:

1. Call this method (IVirtualBox::createMachine) to have a new machine created. The machine object returned is "mutable", i.e. automatically locked for the current session, as if openSession had been called on it.
2. Assign meaningful settings to the new machine by calling the respective methods.
3. Call IMachine::saveSettings to have the settings written to the machine's XML settings file. The configuration of the newly created machine will not be saved to disk (and the settings subfolder and file, as described below, will not be created) until this method is called.
4. Call registerMachine to have the machine show up in the list of machines registered with VirtualBox.

Every machine has a settings file that is used to store the machine configuration. This file is stored in the directory called machine settings subfolder. Unless specified otherwise, both the subfolder and the settings file will have a name that corresponds to the name of the virtual machine. You can specify where to create the machine settings subfolder using the baseFolder argument. The base folder can be absolute (full path) or relative to the VirtualBox home directory.

If a null or empty string is given as the base folder (which is recommended), the default machine settings folder will be used as the base folder to create the machine settings subfolder and file. In any case, the full path to the settings file will look like:

              <base_folder>/<machine_name>/<machine_name>.xml

Optionally the UUID of the machine can be predefined. If this is not desired (i.e. a new UUID should be generated), pass just an empty or null UUID.

You should also specify a valid name for the machine. See the IMachine::name property description for more details about the machine name.

The created machine remains unregistered until you call registerMachine().

Parameters:

  | baseFolder | Name of the folder where to create the machine settings subfolder containing the settings file.
  | name | Machine name.
  | id | UUID of the newly created VM, when non-null or non-empty. Otherwise a UUID is automatically generated.
  | machine | Created machine object.

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

void IVirtualBox::createLegacyMachine | ( | in wstring | settingsFile,
|  | in wstring | name,
|  | in uuid | id,
|  | [retval] out IMachine | machine |
| ) |  |  |

Creates a new virtual machine in "legacy" mode, using the specified settings file to store machine settings.

As opposed to machines created by createMachine(), the settings file of the machine created in "legacy" mode is not automatically renamed when the machine name is changed -- it will always remain the same as specified in this method call.

The specified settings file name can be absolute (full path) or relative to the VirtualBox home directory. If the file name doesn't contain an extension, the default extension (.xml) will be appended.

Optionally the UUID of the machine can be predefined. If this is not desired (i.e. a new UUID should be generated), pass just an empty or null UUID.

Note that the configuration of the newly created machine is not saved to disk (and therefore no settings file is created) until IMachine::saveSettings() is called. If the specified settings file already exists, IMachine::saveSettings() will return an error.

You should also specify a valid name for the machine. See the IMachine::name property description for more details about the machine name.

The created machine remains unregistered until you call registerMachine().

Deprecated:
  This method may be removed later. It is better to use IVirtualBox::createMachine().

Parameters:

  | settingsFile | Name of the file where to store machine settings.
  | name | Machine name.
  | id | UUID of the newly created VM, when non-null or non-empty. Otherwise a UUID is automatically generated.
  | machine | Created machine object.

Note:
  There is no way to change the name of the settings file of the created machine.

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 can be absolute (full path) or relative to the VirtualBox home directory. This file must exist and must be a valid machine settings file whose contents will be used to construct the machine object.

Deprecated:
  Will be removed soon.

Parameters:

  | settingsFile | Name of the machine settings file.
  | machine | Opened machine object.

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 IVirtualBoxCallback::onMachineRegistered signal is sent to all registered callbacks.

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

void IVirtualBox::getMachine | ( | in uuid | id,
|  | [retval] out IMachine | machine |
| ) |  |  |

Attempts to find a virtual machine given its UUID.

To look up a machine by name, use IVirtualBox::findMachine instead.

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

Attempts to find a virtual machine given its name.

To look up a machine by UUID, use IVirtualBox::getMachine instead.

void IVirtualBox::unregisterMachine | ( | in uuid | id,
|  | [retval] out IMachine | machine |
| ) |  |  |

Unregisters the machine previously registered using registerMachine.

After successful method invocation, the IVirtualBoxCallback::onMachineRegistered signal is sent to all registered callbacks.

Parameters:

  | id | UUID of the machine to unregister.
  | machine | Unregistered machine object.

Note:
  The specified machine must not be in the Saved state, have an open (or a spawning) direct session associated with it, have snapshots or have hard disks attached.

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

  If the given machine is inaccessible (see IMachine::accessible), it will be unregistered and fully uninitialized right afterwards. As a result, the returned machine object will be unusable and an attempt to call any method will return the "Object not ready" error.

void IVirtualBox::createHardDisk | ( | in HardDiskStorageType | storageType,
|  | [retval] out IHardDisk | hardDisk |
| ) |  |  |

Creates a new unregistered hard disk that will use the given storage type.

Most properties of the created hard disk object are uninitialized. Valid values must be assigned to them (and probalby some actions performed) to make the actual usage of this hard disk (register, attach to a virtual machine, etc.). See the description of IHardDisk and descriptions of storage type specific interfaces for more information.

Parameters:

  | storageType | Storage type of the hard disk image to create.
  | hardDisk | Created hard disk object of the given storage type.

Note:
  For hard disks using the VirtualDiskImage storage type, an image file is not actually created until you call IVirtualDiskImage::createDynamicImage() or IVirtualDiskImage::createFixedImage().

void IVirtualBox::openHardDisk | ( | in wstring | location,
|  | [retval] out IHardDisk | hardDisk |
| ) |  |  |

Opens a hard disk from an existing location.

This method tries to guess the hard disk storage type from the format of the location string and from the contents of the resource the location points to. Currently, a file path is the only supported format for the location string which must point to either a VDI file or to a VMDK file. On success, an IHardDisk object will be returned that also implements the corresponding interface (IVirtualDiskImage or IVMDKImage, respectively). The IHardDisk::storageType property may also be used to determine the storage type of the returned object (instead of trying to query one of these interfaces).

The opened hard disk remains unregistered until registerHardDisk() is called.

Parameters:

  | location | Location of the resource that contains a valid hard disk.
  | hardDisk | Opened hard disk object.

Note:
  The specified file path can be absolute (full path) or relative to the VirtualBox home directory. If only a file name without any path is given, the default VDI folder will be used as a path to the image file.

void IVirtualBox::openVirtualDiskImage | ( | in wstring | filePath,
|  | [retval] out IVirtualDiskImage | image |
| ) |  |  |

Opens a hard disk from an existing Virtual Disk Image file.

The opened hard disk remains unregistered until registerHardDisk() is called.

Deprecated:
  Use IVirtualBox::openHardDisk() instead.

Parameters:

  | filePath | Name of the file that contains a valid Virtual Disk Image.
  | image | Opened hard disk object.

Note:
  Opening differencing images is not supported.

  The specified file path can be absolute (full path) or relative to the VirtualBox home directory. If only a file name without any path is given, the default VDI folder will be used as a path to the image file.

void IVirtualBox::registerHardDisk | ( | in IHardDisk | hardDisk | ) |

Registers the given hard disk within this VirtualBox installation.

The hard disk must not be registered, must be IHardDisk::accessible and must not be a differencing hard disk, otherwise the registration will fail.

Parameters:

  | hardDisk | Hard disk object to register.

void IVirtualBox::getHardDisk | ( | in uuid | id,
|  | [retval] out IHardDisk | hardDisk |
| ) |  |  |

Returns the registered hard disk with the given UUID.

Parameters:

  | id | UUID of the hard disk to look for.
  | hardDisk | Found hard disk object.

void IVirtualBox::findHardDisk | ( | in wstring | location,
|  | [retval] out IHardDisk | hardDisk |
| ) |  |  |

Returns a registered hard disk that uses the given location to store data.

The search is done by comparing the value of the location argument to the IHardDisk::location attribute of each registered hard disk.

For locations repesented by file paths (such as VDI and VMDK images), the specified location can be either an absolute file path or a path relative to the VirtualBox home directory. If only a file name without any path is given, the default VDI folder will be used as a path to construct the absolute image file name to search for. Note that on host systems with case sensitive filesystems, a case sensitive comparison is performed, otherwise the case of symbols in the file path is ignored.

Parameters:

  | location | Hard disk location specification to search for.
  | hardDisk | Found hard disk object.

void IVirtualBox::findVirtualDiskImage | ( | in wstring | filePath,
|  | [retval] out IVirtualDiskImage | image |
| ) |  |  |

Returns a registered hard disk that uses the given image file.

Deprecated:
  Use IVirtualBox::findHardDisk() instead.

Parameters:

  | filePath | Virtual Disk Image file path to look for.
  | image | Found hard disk object.

Note:
  The specified file path can be absolute (full path) or relative to the VirtualBox home directory. If only a file name without any path is given, the default VDI folder will be used as a path to the image file.

  On host systems with case sensitive filesystems, a case sensitive comparison is performed, otherwise the case of symbols in the file path is ignored.

void IVirtualBox::unregisterHardDisk | ( | in uuid | id,
|  | [retval] out IHardDisk | hardDisk |
| ) |  |  |

Unregisters a hard disk previously registered using registerHardDisk().

Parameters:

  | id | UUID of the hard disk to unregister.
  | hardDisk | Unregistered hard disk object.

Note:
  The specified hard disk must not be attached to any of the existing virtual machines and must not have children (differencing) hard disks.

void IVirtualBox::openDVDImage | ( | in wstring | filePath,
|  | in uuid | id,
|  | [retval] out IDVDImage | image |
| ) |  |  |

Opens the CD/DVD image contained in the specified file of the supported format and assigns it the given UUID.

The opened image remains unregistered until registerDVDImage() is called.

Parameters:

  | filePath | Full name of the file that contains a valid CD/DVD image. Currently, only ISO images are supported.
  | id | UUID to assign to the given image file within this VirtualBox installation. If an empty (null) UUID is specified, the system will randomly generate an UUID.
  | image | Opened CD/DVD image object.

Note:
  The specified file name can be absolute or relative to the VirtualBox home directory.

void IVirtualBox::registerDVDImage | ( | in IDVDImage | image | ) |

Registers a CD/DVD image within this VirtualBox installation.

The image must not be registered and must not be associated with the same image file as any of the already registered images, otherwise the registration will fail.

Parameters:

  | image | CD/DVD image object to register.

void IVirtualBox::getDVDImage | ( | in uuid | id,
|  | [retval] out IDVDImage | image |
| ) |  |  |

Returns a registered CD/DVD image with the given UUID.

Parameters:

  | id | UUID of the image to look for.
  | image | Found CD/DVD image object.

void IVirtualBox::findDVDImage | ( | in wstring | filePath,
|  | [retval] out IDVDImage | image |
| ) |  |  |

Returns a registered CD/DVD image with the given image file.

Parameters:

  | filePath | CD/DVD image file path to look for.
  | image | Found CD/DVD image object.

Note:
  On host systems with case sensitive filesystems, a case sensitive comparison is performed, otherwise the case of symbols in the file path is ignored.

void IVirtualBox::getDVDImageUsage | ( | in uuid | id,
|  | in ResourceUsage | usage,
|  | [retval] out wstring | machineIDs |
| ) |  |  |

Returns the list of of UUIDs of all virtual machines that use the given CD/DVD image.

Parameters:

  | id | UUID of the image to get the usage information for.
  | usage | Type of the usage (permanent, temporary or all).
  | machineIDs | List of UUIDs of all machines that use the given image in the way specified by the usage parameter. The list is returned as a string containing UUIDs separated by spaces. A null string means that the image is not used.

Note:
  When the usage type is ResourceUsage::All and the image is used by the VM both permanently and temporarily, the VM's UUID will be present only once in the list.

void IVirtualBox::unregisterDVDImage | ( | in uuid | id,
|  | [retval] out IDVDImage | image |
| ) |  |  |

Unregisters the CD/DVD image previously registered using registerDVDImage().

Parameters:

  | id | UUID of the CD/DVD image to unregister.
  | image | Unregistered image object.

Note:
  The specified image must not be mounted to any of the existing virtual machines.

void IVirtualBox::openFloppyImage | ( | in wstring | filePath,
|  | in uuid | id,
|  | [retval] out IFloppyImage | image |
| ) |  |  |

Opens a floppy image contained in the specified file of the supported format and assigns it the given UUID.

The opened image remains unregistered until registerFloppyImage() is called.

Parameters:

  | filePath | Full name of the file that contains a valid floppy image.
  | id | UUID to assign to the given image file within this VirtualBox installation. If an empty (null) UUID is specified, the system will randomly generate an UUID.
  | image | Opened CD/DVD image object.

Note:
  The specified file name can be absolute or relative to the VirtualBox home directory.

void IVirtualBox::registerFloppyImage | ( | in IFloppyImage | image | ) |

Registers a floppy image within this VirtualBox installation.

The image must not be registered and must not be associated with the same image file as any of the already registered images, otherwise the registration will fail.

Parameters:

  | image | Floppy image object to register.

void IVirtualBox::getFloppyImage | ( | in uuid | id,
|  | [retval] out IFloppyImage | image |
| ) |  |  |

Returns a registered floppy image with the given UUID.

Parameters:

  | id | UUID of the image to look for.
  | image | Found floppy image object.

void IVirtualBox::findFloppyImage | ( | in wstring | filePath,
|  | [retval] out IFloppyImage | image |
| ) |  |  |

Returns a registered floppy image with the given image file.

Parameters:

  | filePath | Floppy image file path to look for.
  | image | Found floppy image object.

Note:
  On host systems with case sensitive filesystems, a case sensitive comparison is performed, otherwise the case of symbols in the file path is ignored.

void IVirtualBox::getFloppyImageUsage | ( | in uuid | id,
|  | in ResourceUsage | usage,
|  | [retval] out wstring | machineIDs |
| ) |  |  |

Returns the list of of UUIDs of all virtual machines that use the given floppy image.

Parameters:

  | id | UUID of the image to get the usage information for.
  | usage | Type of the usage (permanent, temporary or all).
  | machineIDs | List of UUIDs of all machines that use the given image in the way specified by the usage parameter. The list is returned as a string containing UUIDs separated by spaces. A null string means that the image is not used.

Note:
  When the usage type is ResourceUsage::All and the image is used by the VM both permanently and temporarily, the VM's UUID will be present only once in the list.

void IVirtualBox::unregisterFloppyImage | ( | in uuid | id,
|  | [retval] out IFloppyImage | image |
| ) |  |  |

Unregisters the floppy image previously registered using registerFloppyImage().

Parameters:

  | id | UUID of the floppy image to unregister.
  | image | Unregistered image object.

Note:
  The specified image must not be mounted to any of the existing virtual machines.

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.

Parameters:

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

void IVirtualBox::createSharedFolder | ( | in wstring | name,
|  | in wstring | hostPath,
|  | in boolean | writable |
| ) |  |  |

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

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.

void IVirtualBox::getNextExtraDataKey | ( | in wstring | key,
|  | out wstring | nextKey,
|  | out wstring | nextValue |
| ) |  |  |

Returns the global extra data key name following the supplied key.

An error is returned if the supplied key does not exist. `NULL` is returned in nextKey if the supplied key is the last key. When supplying `NULL` for the key, the first key item is returned in nextKey (if there is any). nextValue is an optional parameter and if supplied, the next key's value is returned in it.

Parameters:

  | key | Name of the data key to follow.
  | nextKey | Name of the next data key.
  | nextValue | Value of the next data key.

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 `NULL` in the value argument.

Parameters:

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

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

Sets associated global extra data.

If you pass `NULL` 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.

Note:
  Before performing the actual data change, this method will ask all registered callbacks using the IVirtualBoxCallback::onExtraDataCanChange() notification for a permission. If one of the callbacks refuses the new value, the change will not be performed.

  On success, the IVirtualBoxCallback::onExtraDataChange() notification is called to inform all registered callbacks about a successful data change.

void IVirtualBox::openSession | ( | in ISession | session,
|  | in uuid | machineId |
| ) |  |  |

Opens a new direct session with the given virtual machine.

A direct session acts as a local lock on the given VM. There can be only one direct session open at a time for every virtual machine, protecting the VM from being manipulated by conflicting actions from different processes. Only after a direct session has been opened, one can change all VM settings and execute the VM in the process space of the session object.

Sessions therefore can be compared to mutex semaphores that lock a given VM for modification and execution. See ISession for details.

Upon successful return, the session object can be used to get access to the machine and to the VM console.

In VirtualBox terminology, the machine becomes "mutable" after a session has been opened. Note that the "mutable" machine object, on which you may invoke IMachine methods to change its settings, will be a different object from the immutable IMachine objects returned by various IVirtualBox methods. To obtain a mutable IMachine object (upon which you can invoke settings methods), use the ISession::machine attribute.

One must always call ISession::close to release the lock on the machine, or the machine's state will eventually be set to "Aborted".

In other words, to change settings on a machine, the following sequence is typically performed:

1. Call this method (openSession) to have a machine locked for the current session.
2. Obtain a mutable IMachine object from ISession::machine.
3. Change the settings of the machine.
4. Call IMachine::saveSettings.
5. Close the session by calling ISession::close.

Parameters:

  | session | Session object that will represent the opened session after successful method invocation. This object must not represent the already open session.
  | machineId | ID of the virtual machine to open a session with.

Note:
  Unless you are writing a new VM frontend, you will not want to execute a VM in the current process. To spawn a new process that executes a VM, use IVirtualBox::openRemoteSession instead.

  This session will be automatically closed if the VirtualBox server is terminated for some reason.

void IVirtualBox::openRemoteSession | ( | in ISession | session,
|  | in uuid | machineId,
|  | in wstring | type,
|  | in wstring | environment,
|  | [retval] out IProgress | progress |
| ) |  |  |

Spawns a new process that executes a virtual machine (called a "remote session").

Opening a remote session causes the VirtualBox server to start a new process that opens a direct session with the given VM. As a result, the VM is locked by that direct session in the new process, preventing conflicting changes from other processes. Since sessions act as locks that such prevent conflicting changes, one cannot open a remote session for a VM that already has another open session (direct or remote), or is currently in the process of opening one (see IMachine::sessionState).

While the remote session still provides some level of control over the VM execution to the caller (using the IConsole interface), not all VM settings are available for modification within the remote session context.

This operation can take some time (a new VM is started in a new process, for which memory and other resources need to be set up). Because of this, an IProgress is returned to allow the caller to wait for this asynchronous operation to be completed. Until then, the remote session object remains in the closed state, and accessing the machine or its console through it is invalid. It is recommended to use IProgress::waitForCompletion or similar calls to wait for completion.

As with all ISession objects, it is recommended to call ISession::close on the local session object once openRemoteSession() has been called. However, the session's state (see ISession::state) will not return to "Closed" until the remote session has also closed (i.e. until the VM is no longer running). In that case, however, the state of the session will automatically change back to "Closed".

Currently supported session types (values of the type argument) are:

- `gui`: VirtualBox Qt GUI session
- `vrdp`: VirtualBox VRDP Server session

The environment argument is a string containing definitions of environment variables in the following format:

              NAME[=VALUE]\n
              NAME[=VALUE]\n
              ...

where `\n` is the new line character. These environment variables will be appended to the environment of the VirtualBox server process. If an environment variable exists both in the server process and in this list, the value from this list takes precedence over the server's variable. If the value of the environment variable is omitted, this variable will be removed from the resulting environment. If the environment string is `null`, the server environment is inherited by the started process as is.

Parameters:

  | session | Session object that will represent the opened remote session after successful method invocation (this object must not represent an already open session).
  | machineId | ID of the virtual machine to open a session with.
  | type | Type of the remote session (case sensitive).
  | environment | Environment to pass to the opened session (may be `null`).
  | progress | Progress object to track the operation completion.

See also:
  openExistingSession

void IVirtualBox::openExistingSession | ( | in ISession | session,
|  | in uuid | machineId |
| ) |  |  |

Opens a new remote session with the virtual machine for which a direct session is already open.

The remote session provides some level of control over the VM execution (using the IConsole interface) to the caller; however, within the remote session context, not all VM settings are available for modification.

As opposed to openRemoteSession(), the number of remote sessions opened this way is not limited by the API

Parameters:

  | session | Session object that will represent the open remote session after successful method invocation. This object must not represent an already open session.
  | machineId | ID of the virtual machine to open a session with.

Note:
  It is an error to open a remote session with the machine that doesn't have an open direct session.

  This session will be automatically closed when the peer (direct) session dies or gets closed.

See also:
  openRemoteSession

void IVirtualBox::registerCallback | ( | in IVirtualBoxCallback | callback | ) |

Registers a new global VirtualBox callback.

The methods of the given callback object will be called by VirtualBox when an appropriate event occurs.

Parameters:

  | callback | Callback object to register.

void IVirtualBox::unregisterCallback | ( | in IVirtualBoxCallback | callback | ) |

Unregisters the previously registered global VirtualBox callback.

Parameters:

  | callback | Callback object to unregister.

void IVirtualBox::waitForPropertyChange | ( | in wstring | what,
|  | in unsigned long | timeout,
|  | out wstring | changed,
|  | out wstring | values |
| ) |  |  |

Blocks the caller until any of the properties represented by the what argument changes the value or until the given timeout interval expires.

The what argument is a comma separated list of propertiy masks that describe properties the caller is interested in. The property mask is a string in the following format:

            [[group.]subgroup.]name

where `name` is the property name and `group`, `subgroup` are zero or or more property group specifiers. Each element (group or name) in the property mask may be either a latin string or an asterisk symbol (`"*"`) which is used to match any string for the given element. A property mask that doesn't contain asterisk symbols represents a single fully qualified property name.

Groups in the fully qualified property name go from more generic (the left-most part) to more specific (the right-most part). The first element is usually a name of the object the property belongs to. The second element may be either a property name, or a child object name, or an index if the preceeding element names an object which is one of many objects of the same type. This way, property names form a hierarchy of properties. Here are some examples of property names:

`VirtualBox.version` | IVirtualBox::version property
`Machine.<UUID>.name` | IMachine::name property of the machine with the given UUID

Most property names directly correspond to the properties of objects (components) provided by the VirtualBox library and may be used to track changes to these properties. However, there may be pseudo-property names that don't correspond to any existing object's property directly, as well as there may be object properties that don't have a corresponding property name that is understood by this method, and therefore changes to such properties cannot be tracked. See individual object's property descrcriptions to get a fully qualified property name that can be used with this method (if any).

There is a special property mask `"*"` (i.e. a string consisting of a single asterisk symbol) that can be used to match all properties. Below are more examples of property masks:

`VirtualBox.*` | Track all properties of the VirtualBox object
`Machine.*.name` | Track changes to the IMachine::name property of all registered virtual machines

Parameters:

  | what | Comma separated list of property masks.
  | timeout | Wait timeout in milliseconds. Specify -1 for an indefinite wait.
  | changed | Comma separated list of properties that have been changed and caused this method to return to the caller.
  | values | Reserved, not currently used.

void IVirtualBox::saveSettings | ( |  | ) |

Saves the global settings to the global settings file (settingsFilePath).

This method is only useful for explicitly saving the global settings file after it has been auto-converted from the old format to the most recent format (see settingsFileVersion for details). Normally, the global settings file is implicitly saved when a global setting is changed.

void IVirtualBox::saveSettingsWithBackup | ( | [retval] out wstring | bakFileName | ) |

Creates a backup copy of the global settings file (settingsFilePath) in case of auto-conversion, and then calls saveSettings().

Note that the backup copy is created only if the settings file auto-conversion took place (see settingsFileVersion for details). Otherwise, this call is fully equivalent to saveSettings() and no backup copying is done.

The backup copy is created in the same directory where the original settings file is located. It is given the following file name:

              original.xml.x.y-platform.bak

where `original.xml` is the original settings file name (excluding path), and `x.y-platform` is the version of the old format of the settings file (before auto-conversion).

If the given backup file already exists, this method will try to add the `.N` suffix to the backup file name (where `N` counts from 0 to 9) and copy it again until it succeeds. If all suffixes are occupied, or if any other copy error occurs, this method will return a failure.

If the copy operation succeeds, the bakFileName return argument will receive a full path to the created backup file (for informational purposes). Note that this will happen even if the subsequent saveSettings() call performed by this method after the copy operation, fails.

Parameters:

  | bakFileName | Full path to the created backup copy.

Note:
  The VirtualBox API never calls this method. It is intended purely for the purposes of creating backup copies of the settings files by front-ends before saving the results of the automatically performed settings conversion to disk.

See also:
  settingsFileVersion

## Member Data Documentation

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 wstring IVirtualBox::settingsFileVersion

Current version of the format of the global VirtualBox settings file (`VirtualBox.xml`).

The version string has the following format:

              x.y-platform

where `x` and `y` are the major and the minor format versions, and `platform` is the platform identifier.

The current version usually matches the value of the settingsFormatVersion attribute unless the settings file was created by an older version of VirtualBox and there was a change of the settings file format since then.

Note that VirtualBox automatically converts settings files from older versions to the most recent version when reading them (usually at VirtualBox startup) but it doesn't save the changes back until you call a method that implicitly saves settings (such as setExtraData()) or call saveSettings() explicitly. Therefore, if the value of this attribute differs from the value of settingsFormatVersion, then it means that the settings file was converted but the result of the conversion is not yet saved to disk.

The above feature may be used by interactive front-ends to inform users about the settings file format change and offer them to explicitly save all converted settings files (the global and VM-specific ones), optionally create bacup copies of the old settings files before saving, etc.

See also:
  settingsFormatVersion, saveSettingsWithBackup()

readonly attribute wstring IVirtualBox::settingsFormatVersion

Most recent version of the settings file format.

The version string has the following format:

              x.y-platform

where `x` and `y` are the major and the minor format versions, and `platform` is the platform identifier.

VirtualBox uses this version of the format when saving settings files (either as a result of method calls that require to save settings or as a result of an explicit call to saveSettings()).

See also:
  settingsFileVersion

readonly attribute IHost IVirtualBox::host

Associated host object.

readonly attribute ISystemProperties IVirtualBox::systemProperties

Associated system information object.

readonly attribute IMachineCollection IVirtualBox::machines

Collection of machine objects registered within this VirtualBox instance.

readonly attribute IMachine [] IVirtualBox::machines2

Array of machine objects registered within this VirtualBox instance.

readonly attribute IHardDiskCollection IVirtualBox::hardDisks

Collection of hard disk objects registered within this VirtualBox instance.

This collection contains only "top-level" (basic or independent) hard disk images, but not differencing ones. All differencing images of the given top-level image (i.e. all its children) can be enumerated using IHardDisk::children.

readonly attribute IDVDImageCollection IVirtualBox::DVDImages

readonly attribute IFloppyImageCollection IVirtualBox::FloppyImages

readonly attribute IProgressCollection IVirtualBox::progressOperations

readonly attribute IGuestOSTypeCollection IVirtualBox::guestOSTypes

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

readonly attribute IPerformanceCollector IVirtualBox::performanceCollector

Associated performance collector object.