# 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 name, in wstring osTypeId, in wstring baseFolder, in wstringUUID id,[retval] out IMachine machine)
| Creates a new virtual machine.
void | createLegacyMachine (in wstring name, in wstring osTypeId, in wstring settingsFile, in wstringUUID 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 wstringUUID 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 wstringUUID id,[retval] out IMachine machine)
| Unregisters the machine previously registered using registerMachine.
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 | openHardDisk (in wstring location, in AccessMode accessMode, in boolean setImageId, in wstringUUID imageId, in boolean setParentId, in wstringUUID parentId,[retval] out IMedium medium)
| Opens a medium from an existing location, optionally replacing the image UUID and/or parent UUID.
void | getHardDisk (in wstringUUID id,[retval] out IMedium medium)
| Returns a medium with the given UUID.
void | findHardDisk (in wstring location,[retval] out IMedium medium)
| Returns a medium that uses the given location to store medium data.
void | openDVDImage (in wstring location, in wstringUUID id,[retval] out IMedium image)
| Opens a CD/DVD image contained in the specified file of the supported format and assigns it the given UUID.
void | getDVDImage (in wstringUUID id,[retval] out IMedium image)
| Returns a CD/DVD image with the given UUID.
void | findDVDImage (in wstring location,[retval] out IMedium image)
| Returns a CD/DVD image with the given image location.
void | openFloppyImage (in wstring location, in wstringUUID id,[retval] out IMedium image)
| Opens a floppy image contained in the specified file of the supported format and assigns it the given UUID.
void | getFloppyImage (in wstringUUID id,[retval] out IMedium image)
| Returns a floppy image with the given UUID.
void | findFloppyImage (in wstring location,[retval] out IMedium image)
| Returns a floppy image with the given image location.
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)
| 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 | openSession (in ISession session, in wstringUUID machineId)
| Opens a new direct session with the given virtual machine.
void | openRemoteSession (in ISession session, in wstringUUID 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 wstringUUID 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 | 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 registered with this VirtualBox instance.
readonly attribute IMedium[] | floppyImages
| Array of floppy image objects registered with 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 server settings.

## 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:
  `{2158464A-F706-414B-A8C4-FB589DFC6B62}`

## Member Function Documentation

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

Creates a new virtual machine.

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.

You should specify valid name for the newly created machine when calling this method. See the IMachine::name attribute description for more details about the machine name.

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

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

If baseFolder is a `null` or empty string (which is recommended), the default machine settings folder will be used as a base folder for the created machine. Otherwise the given base folder will be used. In either case, the full path to the resulting settings file has the following structure:

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

Note that if the resulting settings file already exists, this method will fail with VBOX_E_FILE_ERROR.

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.

Parameters:

  | name | Machine name.
  | osTypeId | Guest OS Type ID.
  | baseFolder | Base machine folder (optional).
  | id | Machine UUID (optional).
  | 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:
  There is no way to change the name of the settings file or subfolder of the created machine directly.

void IVirtualBox::createLegacyMachine | ( | in wstring | name,
|  | in wstring | osTypeId,
|  | in wstring | settingsFile,
|  | in wstringUUID | 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.

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, this method will fail with VBOX_E_FILE_ERROR.

See createMachine for more information.

Deprecated:
  This method may be removed later. Use IVirtualBox::createMachine instead.

Parameters:

  | name | Machine name.
  | osTypeId | Machine OS Type ID.
  | settingsFile | Name of the machine settings file.
  | id | Machine UUID (optional).
  | machine | Created machine object.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | osTypeId is invalid.
  VBOX_E_FILE_ERROR | settingsFile is invalid or the settings file already exists or could not be created due to an I/O error.
  E_INVALIDARG | name or settingsFile is empty or `null`.

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

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.

Expected result codes:

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

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.

void IVirtualBox::getMachine | ( | in wstringUUID | 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.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | Could not find registered machine matching id.

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.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | Could not find registered machine matching name.

void IVirtualBox::unregisterMachine | ( | in wstringUUID | 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.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | Could not find registered machine matching id.
  VBOX_E_INVALID_VM_STATE | Machine is in Saved state.
  VBOX_E_INVALID_OBJECT_STATE | Machine has snapshot or open session or medium attached.

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 any medium 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::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.

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:

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

After the storage unit is successfully created, the medium gets remembered by this VirtualBox installation and will be accessible through getHardDisk and findHardDisk methods. Remembered base medium are also returned as part of the hardDisks array. See IMedium for more details.

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, IMedium and ISystemProperties::defaultHardDiskFolder 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.
  | 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).

void IVirtualBox::openHardDisk | ( | in wstring | location,
|  | in AccessMode | accessMode,
|  | in boolean | setImageId,
|  | in wstringUUID | imageId,
|  | in boolean | setParentId,
|  | in wstringUUID | parentId,
|  | [retval] out IMedium | medium |
| ) |  |  |

Opens a medium from an existing location, optionally replacing the image UUID and/or parent UUID.

After the medium is successfully opened by this method, it gets remembered by (known to) this VirtualBox installation and will be accessible through getHardDisk and findHardDisk methods. Remembered base media are also returned as part of the hardDisks array and can be attached to virtual machines. See IMedium for more details.

If a differencing 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 tries to guess the storage format of the specified medium by reading medium data at the specified location.

If write is ReadWrite (which it should be), 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 image 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 when the image will quickly be closed again.

Note that the format of the location string is storage format specific. See IMedium::location, IMedium and ISystemProperties::defaultHardDiskFolder for more details.

Parameters:

  | location | Location of the storage unit that contains medium data in one of the supported storage formats.
  | accessMode | Determines whether to open the image in read/write or read-only mode.
  | setImageId | Select whether a new image UUID is set or not.
  | imageId | New UUID for the image. If an empty string is passed, then a new UUID is automatically created. Specifying a zero UUIDs is not valid.
  | setParentId | Select whether a new parent UUID is set or not.
  | parentId | New parent UUID for the image. If an empty string is passed, then a new UUID is automatically created, provided setParentId is `true`. A zero UUID is valid.
  | 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.

void IVirtualBox::getHardDisk | ( | in wstringUUID | id,
|  | [retval] out IMedium | medium |
| ) |  |  |

Returns a medium with the given UUID.

The medium with the given UUID must be known to this VirtualBox installation, i.e. it must be previously created by createHardDisk or opened by openHardDisk, or attached to some known virtual machine.

Parameters:

  | id | UUID of the medium to look for.
  | medium | Found medium object.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | No medium object matching id found.

void IVirtualBox::findHardDisk | ( | in wstring | location,
|  | [retval] out IMedium | medium |
| ) |  |  |

Returns a medium that uses the given location 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 openHardDisk, or attached to some known virtual machine.

The search is done by comparing the value of the location argument to the IMedium::location attribute of each known medium.

For locations represented by file names in the host's file system, the requested location can be a path relative to the VirtualBox home folder. If only a file name without any path is given, the default medium folder will be prepended to the file name before searching. Note that on case sensitive file systems, a case sensitive comparison is performed, otherwise the case of symbols in the file path is ignored.

Parameters:

  | location | Location string to search for.
  | medium | Found medium object.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | No medium object matching location found.

void IVirtualBox::openDVDImage | ( | in wstring | location,
|  | in wstringUUID | id,
|  | [retval] out IMedium | image |
| ) |  |  |

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

After the image is successfully opened by this method, it gets remembered by (known to) this VirtualBox installation and will be accessible through getDVDImage and findDVDImage methods. Remembered images are also returned as part of the DVDImages array and can be mounted to virtual machines. See IMedium for more details.

See IMedium::location to get more details about the format of the location string.

Parameters:

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

Expected result codes:

  VBOX_E_FILE_ERROR | Invalid CD/DVD image file location or could not find the CD/DVD image at the specified location.
  VBOX_E_INVALID_OBJECT_STATE | CD/DVD image already exists in the media registry.

Note:
  Currently only ISO 9960 CD/DVD images are supported by VirtualBox.

void IVirtualBox::getDVDImage | ( | in wstringUUID | id,
|  | [retval] out IMedium | image |
| ) |  |  |

Returns a CD/DVD image with the given UUID.

The image with the given UUID must be known to this VirtualBox installation, i.e. it must be previously opened by openDVDImage, or mounted to some known virtual machine.

Parameters:

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

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | No matching DVD image found in the media registry.

void IVirtualBox::findDVDImage | ( | in wstring | location,
|  | [retval] out IMedium | image |
| ) |  |  |

Returns a CD/DVD image with the given image location.

The image with the given UUID must be known to this VirtualBox installation, i.e. it must be previously opened by openDVDImage, or mounted to some known virtual machine.

The search is done by comparing the value of the location argument to the IMedium::location attribute of each known CD/DVD image.

The requested location can be a path relative to the VirtualBox home folder. If only a file name without any path is given, the default hard disk folder will be prepended to the file name before searching. Note that on case sensitive file systems, a case sensitive comparison is performed, otherwise the case in the file path is ignored.

Parameters:

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

Expected result codes:

  VBOX_E_FILE_ERROR | Invalid image file location.
  VBOX_E_OBJECT_NOT_FOUND | No matching DVD image found in the media registry.

void IVirtualBox::openFloppyImage | ( | in wstring | location,
|  | in wstringUUID | id,
|  | [retval] out IMedium | image |
| ) |  |  |

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

After the image is successfully opened by this method, it gets remembered by (known to) this VirtualBox installation and will be accessible through getFloppyImage and findFloppyImage methods. Remembered images are also returned as part of the floppyImages array and can be mounted to virtual machines. See IMedium for more details.

See IMedium::location to get more details about the format of the location string.

Parameters:

  | location | Full path to 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 a new UUID.
  | image | Opened floppy image object.

Expected result codes:

  VBOX_E_FILE_ERROR | Invalid floppy image file location or could not find the floppy image at the specified location.
  VBOX_E_INVALID_OBJECT_STATE | Floppy image already exists in the media registry.

Note:
  Currently, only raw floppy images are supported by VirtualBox.

void IVirtualBox::getFloppyImage | ( | in wstringUUID | id,
|  | [retval] out IMedium | image |
| ) |  |  |

Returns a floppy image with the given UUID.

The image with the given UUID must be known to this VirtualBox installation, i.e. it must be previously opened by openFloppyImage, or mounted to some known virtual machine.

Parameters:

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

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | No matching floppy image found in the media registry.

void IVirtualBox::findFloppyImage | ( | in wstring | location,
|  | [retval] out IMedium | image |
| ) |  |  |

Returns a floppy image with the given image location.

The image with the given UUID must be known to this VirtualBox installation, i.e. it must be previously opened by openFloppyImage, or mounted to some known virtual machine.

The search is done by comparing the value of the location argument to the IMedium::location attribute of each known floppy image.

The requested location can be a path relative to the VirtualBox home folder. If only a file name without any path is given, the default hard disk folder will be prepended to the file name before searching. Note that on case sensitive file systems, a case sensitive comparison is performed, otherwise the case of symbols in the file path is ignored.

Parameters:

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

Expected result codes:

  VBOX_E_FILE_ERROR | Invalid image file location.
  VBOX_E_OBJECT_NOT_FOUND | No matching floppy image found in the media registry.

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.

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.

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

Note:
  In the current implementation, this operation is not implemented.

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.

void IVirtualBox::getExtraDataKeys | ( | [retval] out wstring[] | value | ) |

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

Parameters:

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

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.

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.

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.

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

Expected result codes:

  E_UNEXPECTED | Virtual machine not registered.
  E_ACCESSDENIED | Process not started by OpenRemoteSession.
  VBOX_E_OBJECT_NOT_FOUND | No matching virtual machine found.
  VBOX_E_INVALID_OBJECT_STATE | Session already open or being opened.
  VBOX_E_VM_ERROR | Failed to assign machine to session.

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 wstringUUID | 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 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
- `"sdl"`: VirtualBox SDL GUI 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` or empty, 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.
  | progress | Progress object to track the operation completion.

Expected result codes:

  E_UNEXPECTED | Virtual machine not registered.
  E_INVALIDARG | Invalid session type type.
  VBOX_E_OBJECT_NOT_FOUND | No machine matching machineId found.
  VBOX_E_INVALID_OBJECT_STATE | Session already open or being opened.
  VBOX_E_IPRT_ERROR | Launching process for machine failed.
  VBOX_E_VM_ERROR | Failed to assign machine to session.

See also:
  openExistingSession

void IVirtualBox::openExistingSession | ( | in ISession | session,
|  | in wstringUUID | 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.

Expected result codes:

  E_UNEXPECTED | Virtual machine not registered.
  VBOX_E_OBJECT_NOT_FOUND | No machine matching machineId found.
  VBOX_E_INVALID_OBJECT_STATE | Session already open or being opened.
  VBOX_E_INVALID_SESSION_STATE | Direct session state not Open.
  VBOX_E_VM_ERROR | Failed to get console object from direct session or assign machine to session.

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.

Expected result codes:

  E_INVALIDARG | A `null` callback cannot be registered.

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

Unregisters the previously registered global VirtualBox callback.

Parameters:

  | callback | Callback object to unregister.

Expected result codes:

  E_INVALIDARG | Specified callback not registered.

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 property 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 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 preceding 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 descriptions 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.

Note:
  This function is not implemented in the current version of the product.

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.

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.

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.

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.

Parameters:

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

## 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 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 registered with this VirtualBox instance.

readonly attribute IMedium [] IVirtualBox::floppyImages

Array of floppy image objects registered with 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.

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.

readonly attribute IDHCPServer [] IVirtualBox::DHCPServers

dhcp server settings.