diff options
Diffstat (limited to 'src/VBox/Main/idl/VirtualBox.xidl')
| -rw-r--r-- | src/VBox/Main/idl/VirtualBox.xidl | 30710 |
1 files changed, 30710 insertions, 0 deletions
diff --git a/src/VBox/Main/idl/VirtualBox.xidl b/src/VBox/Main/idl/VirtualBox.xidl new file mode 100644 index 00000000..886c03cf --- /dev/null +++ b/src/VBox/Main/idl/VirtualBox.xidl @@ -0,0 +1,30710 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!-- + Copyright (C) 2006-2022 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<!-- + This is the master declaration for VirtualBox's Main API, + represented by COM/XPCOM and web service interfaces. + + From this document, the build system generates several files + via XSLT that are then used during the build process. + + Below is the list of XSL templates that operate on this file and + output files they generate. These XSL templates must be updated + whenever the schema of this file changes: + + 1. src/VBox/Main/idl/midl.xsl => + out/<platform>/bin/sdk/idl/VirtualBox.idl + (MS COM interface definition file for Main API) + + 2. src/VBox/Main/idl/xpidl.xsl => + out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl + (XPCOM interface definition file for Main API) + + 3. src/VBox/Main/idl/doxygen.xsl => + out/<platform>/obj/src/VBox/Main/VirtualBox.idl + (pseudo-IDL for Doxygen to generate the official Main API + documentation) + + 4. src/VBox/Main/webservice/*.xsl => + a bunch of WSDL and C++ files + (VirtualBox web service sources and SOAP mappers; + see src/VBox/Main/webservice/Makefile.kmk for details) + + 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl => + out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h + (smart Qt-based C++ wrapper classes for COM interfaces + of the Main API) + + 6. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl => + out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi + (Main API TypeLib block for the WiX installer) + + 7. src/VBox/Runtime/common/err/errmsgvboxcom.xsl => + out/<platform>/obj/Runtime/errmsgvboxcomdata.h + (<result> extraction for the %Rhrc format specifier) + + + Note! SlickEdit users can use the 'xml_validate' command on the SlickEdit + command line to verify the document against the DTD. Uncomment the + DOCTYPE below first (java doesn't seem to like it). +--> + +<!DOCTYPE idl SYSTEM "VirtualBox.dtd"> + +<idl> + +<desc> + Welcome to the <b>VirtualBox Main API documentation</b>. This documentation + describes the so-called <i>VirtualBox Main API</i> which comprises all public + COM interfaces and components provided by the VirtualBox server and by the + VirtualBox client library. + + VirtualBox employs a client-server design, meaning that whenever any part of + VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line + interface or any virtual machine --, a dedicated server process named + VBoxSVC runs in the background. This allows multiple processes working with + VirtualBox to cooperate without conflicts. These processes communicate to each + other using inter-process communication facilities provided by the COM + implementation of the host computer. + + On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM + implementation. On all other platforms, Mozilla XPCOM, an open-source COM + implementation, is used. + + All the parts that a typical VirtualBox user interacts with (the Qt GUI + and the VBoxManage command-line interface) are technically + front-ends to the Main API and only use the interfaces that are documented + in this Main API documentation. This ensures that, with any given release + version of VirtualBox, all capabilities of the product that could be useful + to an external client program are always exposed by way of this API. + + The VirtualBox Main API (also called the <i>VirtualBox COM library</i>) + contains two public component classes: + <tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which + implement IVirtualBox and ISession interfaces respectively. These two classes + are of supreme importance and will be needed in order for any front-end + program to do anything useful. It is recommended to read the documentation of + the mentioned interfaces first. + + The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that + there can be only one object of this class on the local machine at any given + time. This object is a parent of many other objects in the VirtualBox COM + library and lives in the VBoxSVC process. In fact, when you create an instance + of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC + process is already running, starts it if not, and returns you a reference to + the <tt>VirtualBox</tt> object created in this process. When the last reference + to this object is released, the VBoxSVC process ends (with a 5 second delay to + protect from too frequent restarts). + + The <tt>%VirtualBox.Session</tt> class is a regular component. You can create + as many <tt>Session</tt> objects as you need but all of them will live in a + process which issues the object instantiation call. <tt>Session</tt> objects + represent virtual machine sessions which are used to configure virtual + machines and control their execution. + + The naming of methods and attributes is very clearly defined: they all start + with a lowercase letter (except if they start with an acronym), and are using + CamelCase style otherwise. This naming only applies to the IDL description, + and is modified by the various language bindings (some convert the first + character to upper case, some not). See the SDK reference for more details + about how to call a method or attribute from a specific programming language. +</desc> + +<if target="midl"> + <cpp line="enum {"/> + <cpp line=" kTypeLibraryMajorVersion = 1,"/> + <cpp line=" kTypeLibraryMinorVersion = 3"/> + <cpp line="};"/> +</if> + +<if target="xpidl"> + <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience --> + <cpp> +/* currently, nsISupportsImpl.h lacks the below-like macros */ + +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI NS_IMPL_QUERY_INTERFACE4_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE5_CI NS_IMPL_QUERY_INTERFACE5_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE6_CI NS_IMPL_QUERY_INTERFACE6_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE7_CI NS_IMPL_QUERY_INTERFACE7_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE8_CI NS_IMPL_QUERY_INTERFACE8_CI + + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \ + NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \ + NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \ + NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS4_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS4_CI(_class, _i1, _i2, _i3, _i4) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI(_class, _i1, _i2, _i3, _i4) \ + NS_IMPL_CI_INTERFACE_GETTER4(_class, _i1, _i2, _i3, _i4) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS5_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS5_CI(_class, _i1, _i2, _i3, _i4, _i5) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE5_CI(_class, _i1, _i2, _i3, _i4, _i5) \ + NS_IMPL_CI_INTERFACE_GETTER5(_class, _i1, _i2, _i3, _i4, _i5) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS6_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS6_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE6_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6) \ + NS_IMPL_CI_INTERFACE_GETTER6(_class, _i1, _i2, _i3, _i4, _i5, _i6) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS7_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS7_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE7_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7) \ + NS_IMPL_CI_INTERFACE_GETTER7(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS8_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS8_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7, _i8) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE8_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7, _i8) \ + NS_IMPL_CI_INTERFACE_GETTER8(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7, _i8) +#endif + +#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI +# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \ + NS_INTERFACE_MAP_BEGIN(_class) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \ + NS_IMPL_QUERY_CLASSINFO(_class) \ + NS_INTERFACE_MAP_END +#endif + +#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI +# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2) \ + NS_INTERFACE_MAP_BEGIN(_class) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \ + NS_IMPL_QUERY_CLASSINFO(_class) \ + NS_INTERFACE_MAP_END +#endif + +#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI +# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2, _i3, _ic3) \ + NS_INTERFACE_MAP_BEGIN(_class) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \ + NS_IMPL_QUERY_CLASSINFO(_class) \ + NS_INTERFACE_MAP_END +#endif + +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \ + NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2) \ + NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2, _i3, _ic3) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2, _i3, _ic3) \ + NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3) +#endif + + </cpp> +</if> + +<!-- + Note!! Don't forget to update the python bindings (++) when changing the + UUID or version!! +--> +<library + name="VirtualBox" + uuid="d7569351-1750-46f0-936e-bd127d5bc264" + version="1.3" +> + +<application + name="VirtualBox" + uuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9" + supportsErrorInfo="yes" +> + + + <!-- + // COM result codes for VirtualBox + ///////////////////////////////////////////////////////////////////////// + --> + + <descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes"> + <desc> + This section describes all VirtualBox-specific COM result codes that may + be returned by methods of VirtualBox COM interfaces in addition to + standard COM result codes. + + Note that along with the result code, every VirtualBox method returns + extended error information through the IVirtualBoxErrorInfo interface on + failure. This interface is a preferred way to present the error to the end + user because it contains a human readable description of the error. Raw + result codes, both standard and described in this section, are intended to + be used by programs to analyze the reason of a failure and select an + appropriate course of action without involving the end user (for example, + retry the operation later or make a different call). + + The standard COM result codes that may originate from our methods include: + + <dl> + <dt><tt>E_INVALIDARG</tt></dt> + <dd> + Returned when the value of the method's argument is not within the range + of valid values. This should not be confused with situations when the + value is within the range but simply doesn't suit the current object + state and there is a possibility that it will be accepted later (in such + cases VirtualBox-specific codes are returned, for example, + <link to="VBOX_E_OBJECT_NOT_FOUND"/>). + </dd> + <dt><tt>E_POINTER</tt></dt> + <dd> + Returned if a memory pointer for the output argument is invalid (for + example, @c null). When pointers representing input arguments (such + as strings) are invalid, E_INVALIDARG is returned. + </dd> + <dt><tt>E_ACCESSDENIED</tt></dt> + <dd> + Returned when the called object is not ready. Since the lifetime of a + public COM object cannot be fully controlled by the implementation, + VirtualBox maintains the readiness state for all objects it creates and + returns this code in response to any method call on the object that was + deactivated by VirtualBox and is not functioning any more. + </dd> + <dt><tt>E_OUTOFMEMORY</tt></dt> + <dd> + Returned when a memory allocation operation fails. + </dd> + </dl> + </desc> + </descGroup> + + <!-- + Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore + everything in <result>/<desc> after (and including) the first dot, so express + the matter of the error code in the first sentence and keep it short. + --> + + <result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001"> + <desc> + Object corresponding to the supplied arguments does not exist. + </desc> + </result> + + <result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002"> + <desc> + Current virtual machine state prevents the operation. + </desc> + </result> + + <result name="VBOX_E_VM_ERROR" value="0x80BB0003"> + <desc> + Virtual machine error occurred attempting the operation. + </desc> + </result> + + <result name="VBOX_E_FILE_ERROR" value="0x80BB0004"> + <desc> + File not accessible or erroneous file contents. + </desc> + </result> + + <result name="VBOX_E_IPRT_ERROR" value="0x80BB0005"> + <desc> + Runtime subsystem error. + </desc> + </result> + + <result name="VBOX_E_PDM_ERROR" value="0x80BB0006"> + <desc> + Pluggable Device Manager error. + </desc> + </result> + + <result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007"> + <desc> + Current object state prohibits operation. + </desc> + </result> + + <result name="VBOX_E_HOST_ERROR" value="0x80BB0008"> + <desc> + Host operating system related error. + </desc> + </result> + + <result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009"> + <desc> + Requested operation is not supported. + </desc> + </result> + + <result name="VBOX_E_XML_ERROR" value="0x80BB000A"> + <desc> + Invalid XML found. + </desc> + </result> + + <result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B"> + <desc> + Current session state prohibits operation. + </desc> + </result> + + <result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C"> + <desc> + Object being in use prohibits operation. + </desc> + </result> + + <result name="VBOX_E_PASSWORD_INCORRECT" value="0x80BB000D"> + <desc> + A provided password was incorrect. + </desc> + </result> + + <result name="VBOX_E_MAXIMUM_REACHED" value="0x80BB000E"> + <desc> + A maximum has been reached. + </desc> + </result> + + <result name="VBOX_E_GSTCTL_GUEST_ERROR" value="0x80BB000F"> + <desc> + Guest Control reported an error from the guest side. + </desc> + </result> + + <result name="VBOX_E_TIMEOUT" value="0x80BB0010"> + <desc> + The operation ran into an explicitly requested timeout. + </desc> + </result> + + <result name="VBOX_E_DND_ERROR" value="0x80BB0011"> + <desc> + A drag and drop error has occurred. + </desc> + </result> + + <!-- + Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore + everything in <result>/<desc> after (and including) the first dot, so express + the matter of the error code in the first sentence and keep it short. + --> + + <descGroup/> + + <!-- + // all common enums + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="SettingsVersion" + uuid="b4cc23c2-96f2-419d-830b-bd13c1135dfb" + > + <desc> + Settings version of VirtualBox settings files. This is written to + the "version" attribute of the root "VirtualBox" element in the settings + file XML and indicates which VirtualBox version wrote the file. + </desc> + + <const name="Null" value="0"> + <desc>Null value, indicates invalid version.</desc> + </const> + <const name="v1_0" value="1"> + <desc>Legacy settings version, not currently supported.</desc> + </const> + <const name="v1_1" value="2"> + <desc>Legacy settings version, not currently supported.</desc> + </const> + <const name="v1_2" value="3"> + <desc>Legacy settings version, not currently supported.</desc> + </const> + <const name="v1_3pre" value="4"> + <desc>Legacy settings version, not currently supported.</desc> + </const> + <const name="v1_3" value="5"> + <desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc> + <!-- + Machine XML: Capitalization of Uart, Lpt elements and many attributes changed. + --> + </const> + <const name="v1_4" value="6"> + <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc> + <!-- + VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged + (was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk) + --> + </const> + <const name="v1_5" value="7"> + <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc> + <!-- + 2008-09-04: 2.0.0 released + 2008-11-20: settings version 1.5 introduced + 2008-12-17: 2.1.0 released + Machine changes: + guest OS identifiers changed; + Machine/Hardware/Display/MonitorCount renamed to monitorCount; + Machine/Hardware/Display/Accelerate3D renamed to accelerate3D; + Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count + --> + </const> + <const name="v1_6" value="8"> + <desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc> + <!-- + 2008-12-17: 2.1.0 released + 2008-12-19: settings version 1.6 introduced (is in 2.1 branch) + 2009-04-08: 2.2.0 released + Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done) + --> + </const> + <const name="v1_7" value="9"> + <desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc> + <!-- + 2008-12-17: 2.1.0 released + 2009-03-11: settings version 1.7 introduced (is in 2.2 branch) + 2009-04-08: 2.2.0 released + VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done) + Machine changes: HardDiskAttachments is now StorageControllers (done) + --> + </const> + <const name="v1_8" value="10"> + <desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc> + <!-- + Machine additions: Display/@accelerate2DVideo (done) + --> + </const> + <const name="v1_9" value="11"> + <desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc> + <!-- + The big storage controller / DVD / Floppy rework (done) + --> + </const> + <const name="v1_10" value="12"> + <desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc> + <!-- + Machine changes: RTC localOrUTC (done) + CPU hot-plug support + --> + </const> + <const name="v1_11" value="13"> + <desc>Settings version "1.11", written by VirtualBox 4.0.x.</desc> + <!-- + Machine changes: HD Audio controller, per-machine disk registries, + /@format attribute for DVD and floppy images. + --> + </const> + <const name="v1_12" value="14"> + <desc>Settings version "1.12", written by VirtualBox 4.1.x.</desc> + <!-- + Machine changes: raw PCI device attachment; + NetworkAdapter changes: bandwidth group. + --> + </const> + <const name="v1_13" value="15"> + <desc>Settings version "1.13", written by VirtualBox 4.2.x.</desc> + <!-- + Machine changes: tracing config, groups, autostart; + NetworkAdapter changes: unit for bandwidth group limits. + --> + </const> + <const name="v1_14" value="16"> + <desc>Settings version "1.14", written by VirtualBox 4.3.x.</desc> + <!-- + Machine changes: default frontend, USB rework. + --> + </const> + <const name="v1_15" value="17"> + <desc>Settings version "1.15", written by VirtualBox 5.0.x.</desc> + <!-- + Machine changes: hot-plug flag for storage devices. + --> + </const> + <const name="v1_16" value="18"> + <desc>Settings version "1.16", written by VirtualBox 5.1.x.</desc> + <!-- + Machine changes: NVMe storage controller, paravirt debug options, CPU + profile and BIOS/CPU APIC settings. + VirtualBox.xml: Add support for additional USB device sources (e.g. USB/IP) + --> + </const> + <const name="v1_17" value="19"> + <desc>Settings version "1.17", written by VirtualBox 6.0.x.</desc> + <!-- + Machine changes: nested hardware virtualization, hardware + virtualization using native API, shared folder automount point, + UART type selection and VM process priority. + --> + </const> + <const name="v1_18" value="20"> + <desc>Settings version "1.18", written by VirtualBox 6.1.x.</desc> + <!-- + Machine changes: virtio-scsi storage controller, NVRAM device. + --> + </const> + <const name="v1_19" value="21"> + <desc>Settings version "1.19", written by VirtualBox 7.0.x.</desc> + <!-- + VirtualBox.xml additions: HostOnlyNetworks in NetserviceRegistry + Machine changes: IOMMU device, HostOnlyNetwork mode for + NetworkAdapter, full VM encryption. + --> + </const> + <const name="Future" value="99999"> + <desc>Settings version greater than "1.19", written by a future VirtualBox version.</desc> + </const> + </enum> + + <enum + name="AccessMode" + uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f" + > + <desc> + Access mode for opening files. + </desc> + + <const name="ReadOnly" value="1"/> + <const name="ReadWrite" value="2"/> + </enum> + + <enum + name="MachineState" + uuid="00bc01b5-00a4-48db-000a-9061008357aa" + > + <desc> + Virtual machine execution state. + + This enumeration represents possible values of the <link + to="IMachine::state"/> attribute. + + Below is the basic virtual machine state diagram. It shows how the state + changes during virtual machine execution. The text in square braces shows + a method of the IConsole or IMachine interface that performs the given state + transition. + + <pre> + +---------[powerDown()] <- Stuck <--[failure]-+ + V | + +-> PoweredOff --+-->[powerUp()]--> Starting --+ | +-----[resume()]-----+ + | | | | V | + | Aborted <----+ +--> Running --[pause()]--> Paused + | | ^ | ^ | + | AbortedSaved <-----------[failure]-----<----+ | | | | + | | | | | | | + | +-------------+ | | | | | + | V | | | | | + | Saved --------[powerUp()]-----> Restoring -+ | | | | + | ^ | | | | + | | +-----------------------------------------+-|-------------------+ + + | | | | | + | | +- OnlineSnapshotting <--[takeSnapshot()]<--+---------------------+ + | | | | + | +-------- Saving <--------[saveState()]<----------+---------------------+ + | | | + +-------------- Stopping -------[powerDown()]<----------+---------------------+ + </pre> + + Note that states to the right of PoweredOff, Aborted, AbortedSaved, and + Saved in the above diagram are called <i>online VM states</i>. These + states represent the virtual machine which is being executed in a + dedicated process (usually with a GUI window attached to it where you can + see the activity of the virtual machine and interact with it). There are + two special pseudo-states, FirstOnline and LastOnline, that can be used + in relational expressions to detect if the given machine state is online + or not: + + <pre> + if (machine.GetState() >= MachineState_FirstOnline && + machine.GetState() <= MachineState_LastOnline) + { + ...the machine is being executed... + } + </pre> + + When the virtual machine is in one of the online VM states (that is, being + executed), only a few machine settings can be modified. Methods working + with such settings contain an explicit note about that. An attempt to + change any other setting or perform a modifying operation during this time + will result in the @c VBOX_E_INVALID_VM_STATE error. + + All online states except Running, Paused and Stuck are transitional: they + represent temporary conditions of the virtual machine that will last as + long as the operation that initiated such a condition. + + The Stuck state is a special case. It means that execution of the machine + has reached the "Guru Meditation" condition. This condition indicates an + internal VMM (virtual machine manager) failure which may happen as a + result of either an unhandled low-level virtual hardware exception or one + of the recompiler exceptions (such as the <i>too-many-traps</i> + condition). + + Note also that any online VM state may transit to the Aborted state. This + happens if the process that is executing the virtual machine terminates + unexpectedly (for example, crashes). Other than that, the Aborted state is + equivalent to PoweredOff. + + There are also a few additional state diagrams that do not deal with + virtual machine execution and therefore are shown separately. The states + shown on these diagrams are called <i>offline VM states</i> (this includes + PoweredOff, Aborted, AbortedSaved and Saved too). + + The first diagram shows what happens when a lengthy setup operation is + being executed (such as <link to="IMachine::attachDevice"/>). + + <pre> + +----------------------------------(same state as before the call)------+ + | | + +-> PoweredOff --+ | + | | | + |-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+ + | | + +-> Saved -------+ + </pre> + + The next two diagrams demonstrate the process of taking a snapshot of a + powered off virtual machine, restoring the state to that as of a snapshot + or deleting a snapshot, respectively. + + <pre> + +----------------------------------(same state as before the call)------+ + | | + +-> PoweredOff --+ | + | +-->[takeSnapshot()] ------------------> Snapshotting -+ + +-> Aborted -----+ + + +-> PoweredOff --+ + | | + | Aborted -----+-->[restoreSnapshot() ]-------> RestoringSnapshot -+ + | | [deleteSnapshot() ]-------> DeletingSnapshot --+ + +-> Saved -------+ | + | | + +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+ + </pre> + + <note internal="yes"> + For whoever decides to touch this enum: In order to keep the + comparisons involving FirstOnline and LastOnline pseudo-states valid, + the numeric values of these states must be correspondingly updated if + needed: for any online VM state, the condition + <tt>FirstOnline <= state <= LastOnline</tt> must be + @c true. The same relates to transient states for which + the condition <tt>FirstOnline <= state <= LastOnline</tt> must be + @c true. + </note> + </desc> + + <const name="Null" value="0"> + <desc>Null value (never used by the API).</desc> + </const> + <const name="PoweredOff" value="1"> + <desc> + The machine is not running and has no saved execution state; it has + either never been started or been shut down successfully. + </desc> + </const> + <const name="Saved" value="2"> + <desc> + The machine is not currently running, but the execution state of the machine + has been saved to an external file when it was running, from where + it can be resumed. + </desc> + </const> + <const name="Teleported" value="3"> + <desc> + The machine was teleported to a different host (or process) and then + powered off. Take care when powering it on again may corrupt resources + it shares with the teleportation target (e.g. disk and network). + </desc> + </const> + <const name="Aborted" value="4"> + <desc> + The process running the machine has terminated abnormally. This may + indicate a crash of the VM process in host execution context, or + the VM process has been terminated externally. + </desc> + </const> + <const name="AbortedSaved" value="5"> + <desc> + A machine in the @c Saved stated has terminated abnormally before + reaching the @c Running state. Similar to the @c Aborted state, + this may indicate a crash of the VM process in host execution + context, or the VM process has been terminated externally. + </desc> + </const> + + <const name="Running" value="6"> + <desc> + The machine is currently being executed. + <note internal="yes"> + For whoever decides to touch this enum: In order to keep the + comparisons in the old source code valid, this state must immediately + precede the Paused state. + + @todo Lift this spectacularly wonderful restriction. + </note> + </desc> + </const> + <const name="Paused" value="7"> + <desc> + Execution of the machine has been paused. + <note internal="yes"> + For whoever decides to touch this enum: In order to keep the + comparisons in the old source code valid, this state must immediately + follow the Running state. + + @todo Lift this spectacularly wonderful restriction. + </note> + </desc> + </const> + <const name="Stuck" value="8"> + <desc> + Execution of the machine has reached the "Guru Meditation" + condition. This indicates a severe error in the hypervisor itself. + <note internal="yes"> + bird: Why this uncool name? Could we rename it to "GuruMeditation" or + "Guru", perhaps? Or are there some other VMM states that are + intended to be lumped in here as well? + </note> + </desc> + </const> + <const name="Teleporting" value="9"> + <desc> + The machine is about to be teleported to a different host or process. + It is possible to pause a machine in this state, but it will go to the + @c TeleportingPausedVM state and it will not be + possible to resume it again unless the teleportation fails. + </desc> + </const> + <const name="LiveSnapshotting" value="10"> + <desc> + A live snapshot is being taken. The machine is running normally, but + some of the runtime configuration options are inaccessible. Also, if + paused while in this state it will transition to + @c OnlineSnapshotting and it will not be resume the + execution until the snapshot operation has completed. + </desc> + </const> + <const name="Starting" value="11"> + <desc> + Machine is being started after powering it on from a + zero execution state. + </desc> + </const> + <const name="Stopping" value="12"> + <desc> + Machine is being normally stopped powering it off, or after the guest OS + has initiated a shutdown sequence. + </desc> + </const> + <const name="Saving" value="13"> + <desc> + Machine is saving its execution state to a file. + </desc> + </const> + <const name="Restoring" value="14"> + <desc> + Execution state of the machine is being restored from a file + after powering it on from either the @c Saved or @c AbortedSaved + execution state. + </desc> + </const> + <const name="TeleportingPausedVM" value="15"> + <desc> + The machine is being teleported to another host or process, but it is + not running. This is the paused variant of the + @c Teleporting state. + </desc> + </const> + <const name="TeleportingIn" value="16"> + <desc> + Teleporting the machine state in from another host or process. + </desc> + </const> + <const name="DeletingSnapshotOnline" value="17"> + <desc> + Like @c DeletingSnapshot, but the merging of media is ongoing in + the background while the machine is running. + </desc> + </const> + <const name="DeletingSnapshotPaused" value="18"> + <desc> + Like @c DeletingSnapshotOnline, but the machine was paused when the + merging of differencing media was started. + </desc> + </const> + <const name="OnlineSnapshotting" value="19"> + <desc> + Like @c LiveSnapshotting, but the machine was paused when the + merging of differencing media was started. + </desc> + </const> + <const name="RestoringSnapshot" value="20"> + <desc> + A machine snapshot is being restored; this typically does not take long. + </desc> + </const> + <const name="DeletingSnapshot" value="21"> + <desc> + A machine snapshot is being deleted; this can take a long time since this + may require merging differencing media. This value indicates that the + machine is not running while the snapshot is being deleted. + </desc> + </const> + <const name="SettingUp" value="22"> + <desc> + Lengthy setup operation is in progress. + </desc> + </const> + <const name="Snapshotting" value="23"> + <desc> + Taking an (offline) snapshot. + </desc> + </const> + + <const name="FirstOnline" value="6" wsmap="suppress"> <!-- Running --> + <desc> + Pseudo-state: first online state (for use in relational expressions). + </desc> + </const> + <const name="LastOnline" value="19" wsmap="suppress"> <!-- OnlineSnapshotting --> + <desc> + Pseudo-state: last online state (for use in relational expressions). + </desc> + </const> + + <const name="FirstTransient" value="9" wsmap="suppress"> <!-- Teleporting --> + <desc> + Pseudo-state: first transient state (for use in relational expressions). + </desc> + </const> + <const name="LastTransient" value="23" wsmap="suppress"> <!-- Snapshotting --> + <desc> + Pseudo-state: last transient state (for use in relational expressions). + </desc> + </const> + + </enum> + + <enum + name="SessionState" + uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8" + > + <desc> + Session state. This enumeration represents possible values of + <link to="IMachine::sessionState"/> and <link to="ISession::state"/> + attributes. + </desc> + + <const name="Null" value="0"> + <desc>Null value (never used by the API).</desc> + </const> + <const name="Unlocked" value="1"> + <desc> + In <link to="IMachine::sessionState"/>, this means that the machine + is not locked for any sessions. + + In <link to="ISession::state"/>, this means that no machine is + currently locked for this session. + </desc> + </const> + <const name="Locked" value="2"> + <desc> + In <link to="IMachine::sessionState"/>, this means that the machine + is currently locked for a session, whose process identifier can + then be found in the <link to="IMachine::sessionPID" /> attribute. + + In <link to="ISession::state"/>, this means that a machine is + currently locked for this session, and the mutable machine object + can be found in the <link to="ISession::machine"/> attribute + (see <link to="IMachine::lockMachine" /> for details). + </desc> + </const> + <const name="Spawning" value="3"> + <desc> + A new process is being spawned for the machine as a result of + <link to="IMachine::launchVMProcess"/> call. This state also occurs + as a short transient state during an <link to="IMachine::lockMachine"/> + call. + </desc> + </const> + <const name="Unlocking" value="4"> + <desc> + The session is being unlocked. + </desc> + </const> + </enum> + + <enum + name="CPUArchitecture" + uuid="4a2c9915-12f1-43b2-bb84-e4bd4d5ca227" + > + <desc>Basic CPU architecture types.</desc> + <const name="Any" value="0"> + <desc>Matches any CPU architecture.</desc> + </const> + <const name="x86" value="1"> + <desc>32-bit (and 16-bit) x86.</desc> + </const> + <const name="AMD64" value="2"> + <desc>64-bit x86. (Also known as x86-64 or x64.)</desc> + </const> + </enum> + + <enum + name="CPUPropertyType" + uuid="3fcfe589-ca66-468f-e313-656f9d0b2eb6" + > + <desc> + Virtual CPU property type. This enumeration represents possible values of the + IMachine get- and setCPUProperty methods. + </desc> + <const name="Null" value="0"> + <desc>Null value (never used by the API).</desc> + </const> + <const name="PAE" value="1"> + <desc> + This setting determines whether VirtualBox will expose the Physical Address + Extension (PAE) feature of the host CPU to the guest. Note that in case PAE + is not available, it will not be reported. + </desc> + </const> + <const name="LongMode" value="2"> + <desc> + This setting determines whether VirtualBox will advertise long mode + (i.e. 64-bit guest support) and let the guest enter it. + </desc> + </const> + <const name="TripleFaultReset" value="3"> + <desc> + This setting determines whether a triple fault within a guest will + trigger an internal error condition and stop the VM (default) or reset + the virtual CPU/VM and continue execution. + </desc> + </const> + <const name="APIC" value="4"> + <desc> + This setting determines whether an APIC is part of the virtual CPU. + This feature can only be turned off when the X2APIC feature is off. + </desc> + </const> + <const name="X2APIC" value="5"> + <desc> + This setting determines whether an x2APIC is part of the virtual CPU. + Since this feature implies that the APIC feature is present, it + automatically enables the APIC feature when set. + </desc> + </const> + <const name="IBPBOnVMExit" value="6"> + <desc> + If set, force an indirect branch prediction barrier on VM exits if the + host CPU supports it. This setting will significantly slow down workloads + causing many VM exits, so it is only recommended for situation where there + is a real need to be paranoid. + </desc> + </const> + <const name="IBPBOnVMEntry" value="7"> + <desc> + If set, force an indirect branch prediction barrier on VM entry if the + host CPU supports it. This setting will significantly slow down workloads + causing many VM exits, so it is only recommended for situation where there + is a real need to be paranoid. + </desc> + </const> + <const name="HWVirt" value="8"> + <desc> + Enabled the hardware virtualization (AMD-V/VT-x) feature on the guest CPU. + This requires hardware virtualization on the host CPU. + </desc> + </const> + <const name="SpecCtrl" value="9"> + <desc> + If set, the speculation control CPUID bits and MSRs, when available on the + host, are exposed to the guest. Depending on the host CPU and operating + system, this may significantly slow down workloads causing many VM exits. + </desc> + </const> + <const name="SpecCtrlByHost" value="10"> + <desc> + If set, the speculation controls are managed by the host. This is intended + for guests which do not set the speculation controls themselves. + Note! This has not yet been implemented beyond leaving everything to the host OS. + </desc> + </const> + <const name="L1DFlushOnEMTScheduling" value="11"> + <desc> + If set and the host is affected by CVE-2018-3646, flushes the level 1 data + cache when the EMT is scheduled to do ring-0 guest execution. There could + be a small performance penalty for certain typs of workloads. + For security reasons this setting will be enabled by default. + </desc> + </const> + <const name="L1DFlushOnVMEntry" value="12"> + <desc> + If set and the host is affected by CVE-2018-3646, flushes the level 1 data + on every VM entry. This setting may significantly slow down workloads + causing many VM exits, so it is only recommended for situation where there + is a real need to be paranoid. + </desc> + </const> + <const name="MDSClearOnEMTScheduling" value="13"> + <desc> + If set and the host is affected by CVE-2018-12126, CVE-2018-12127, or + CVE-2018-12130, clears the relevant MDS buffers when the EMT is scheduled + to do ring-0 guest execution. There could be a small performance penalty + for certain typs of workloads. For security reasons this setting will be + enabled by default. + </desc> + </const> + <const name="MDSClearOnVMEntry" value="14"> + <desc> + If set and the host is affected by CVE-2018-12126, CVE-2018-12127, or + CVE-2018-12130, clears the relevant MDS buffers on every VM entry. This + setting may slow down workloads causing many VM exits, so it is only + recommended for situation where there is a real need to be paranoid. + </desc> + </const> + </enum> + + + <enum + name="HWVirtExPropertyType" + uuid="00069d9c-00b5-460c-00dd-64250024f7aa" + > + <desc> + Hardware virtualization property type. This enumeration represents possible values + for the <link to="IMachine::getHWVirtExProperty"/> and + <link to="IMachine::setHWVirtExProperty"/> methods. + </desc> + <const name="Null" value="0"> + <desc>Null value (never used by the API).</desc> + </const> + <const name="Enabled" value="1"> + <desc> + Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If + such extensions are not available, they will not be used. + </desc> + </const> + <const name="VPID" value="2"> + <desc> + Whether VT-x VPID is enabled. If this extension is not available, it will not be used. + </desc> + </const> + <const name="NestedPaging" value="3"> + <desc> + Whether Nested Paging is enabled. If this extension is not available, it will not be used. + </desc> + </const> + <const name="UnrestrictedExecution" value="4"> + <desc> + Whether VT-x unrestricted execution is enabled. If this feature is not available, it will not be used. + </desc> + </const> + <const name="LargePages" value="5"> + <desc> + Whether large page allocation is enabled; requires nested paging and a 64-bit host. + </desc> + </const> + <const name="Force" value="6"> + <desc> + Whether the VM should fail to start if hardware virtualization (VT-x/AMD-V) cannot be used. If + not set, there will be an automatic fallback to software virtualization. + </desc> + </const> + <const name="UseNativeApi" value="7"> + <desc> + Use the native hypervisor API instead of the VirtualBox one (HM) for VT-X/AMD-V. This is + ignored if <link to="HWVirtExPropertyType_Enabled"/> isn't set. + </desc> + </const> + <const name="VirtVmsaveVmload" value="8"> + <desc> + Whether AMD-V Virtualized VMSAVE/VMLOAD is enabled. If this feature is not available, it will not + be used. + </desc> + </const> + </enum> + + <enum + name="ParavirtProvider" + uuid="696453ec-3742-4a05-bead-658ccbf2c944" + > + <desc> + The paravirtualized guest interface provider. This enumeration represents possible + values for the <link to="IMachine::paravirtProvider"/> attribute. + </desc> + <const name="None" value="0"> + <desc>No provider is used.</desc> + </const> + <const name="Default" value="1"> + <desc>A default provider is automatically chosen according to the guest OS type.</desc> + </const> + <const name="Legacy" value="2"> + <desc>Used for VMs which didn't used to have any provider settings. Usually + interpreted as @c None for most VMs.</desc> + </const> + <const name="Minimal" value="3"> + <desc>A minimal set of features to expose to the paravirtualized guest.</desc> + </const> + <const name="HyperV" value="4"> + <desc>Microsoft Hyper-V.</desc> + </const> + <const name="KVM" value="5"> + <desc>Linux KVM.</desc> + </const> + </enum> + + <enum + name="LockType" + uuid="678aaf14-2815-4c3e-b20a-e86ed0216498" + > + <desc> + Used with <link to="IMachine::lockMachine" />. + </desc> + <const name="Null" value="0"> + <desc>Placeholder value, do not use when obtaining a lock.</desc> + </const> + <const name="Shared" value="1"> + <desc>Request only a shared lock for remote-controlling the machine. + Such a lock allows changing certain VM settings which can be safely + modified for a running VM.</desc> + </const> + <const name="Write" value="2"> + <desc>Lock the machine for writing. This requests an exclusive lock, i.e. + there cannot be any other API client holding any type of lock for this + VM concurrently. Remember that a VM process counts as an API client + which implicitly holds the equivalent of a shared lock during the + entire VM runtime.</desc> + </const> + <const name="VM" value="3"> + <desc>Lock the machine for writing, and create objects necessary for + running a VM in this process.</desc> + </const> + </enum> + + <enum + name="SessionType" + uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A" + > + <desc> + Session type. This enumeration represents possible values of the + <link to="ISession::type"/> attribute. + </desc> + + <const name="Null" value="0"> + <desc>Null value (never used by the API).</desc> + </const> + <const name="WriteLock" value="1"> + <desc> + Session has acquired an exclusive write lock on a machine + using <link to="IMachine::lockMachine"/>. + </desc> + </const> + <const name="Remote" value="2"> + <desc> + Session has launched a VM process using + <link to="IMachine::launchVMProcess"/> + </desc> + </const> + <const name="Shared" value="3"> + <desc> + Session has obtained a link to another session using + <link to="IMachine::lockMachine"/> + </desc> + </const> + </enum> + + <enum + name="DeviceType" + uuid="cb977be1-d1fb-41f8-ad7e-951736c6cb3e" + > + <desc> + Device type. + </desc> + <const name="Null" value="0"> + <desc> + Null value, may also mean "no device" (not allowed for + <link to="IConsole::getDeviceActivity"/>). + </desc> + </const> + <const name="Floppy" value="1"> + <desc>Floppy device.</desc> + </const> + <const name="DVD" value="2"> + <desc>CD/DVD-ROM device.</desc> + </const> + <const name="HardDisk" value="3"> + <desc>Hard disk device.</desc> + </const> + <const name="Network" value="4"> + <desc>Network device.</desc> + </const> + <const name="USB" value="5"> + <desc>USB device.</desc> + </const> + <const name="SharedFolder" value="6"> + <desc>Shared folder device.</desc> + </const> + <const name="Graphics3D" value="7"> + <desc>Graphics device 3D activity.</desc> + </const> + </enum> + + <enum + name="DeviceActivity" + uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707" + > + <desc> + Device activity for <link to="IConsole::getDeviceActivity"/>. + </desc> + + <const name="Null" value="0"/> + <const name="Idle" value="1"/> + <const name="Reading" value="2"/> + <const name="Writing" value="3"/> + </enum> + + <enum + name="ClipboardMode" + uuid="33364716-4008-4701-8f14-be0fa3d62950" + > + <desc> + Host-Guest clipboard interchange mode. + </desc> + + <const name="Disabled" value="0"/> + <const name="HostToGuest" value="1"/> + <const name="GuestToHost" value="2"/> + <const name="Bidirectional" value="3"/> + </enum> + + <enum + name="DnDMode" + uuid="07af8800-f936-4b33-9172-cd400e83c148" + > + <desc> + Drag and drop interchange mode. + </desc> + + <const name="Disabled" value="0"/> + <const name="HostToGuest" value="1"/> + <const name="GuestToHost" value="2"/> + <const name="Bidirectional" value="3"/> + </enum> + + <enum + name="Scope" + uuid="7c91096e-499e-4eca-9f9b-9001438d7855" + > + <desc> + Scope of the operation. + + A generic enumeration used in various methods to define the action or + argument scope. + </desc> + + <const name="Global" value="0"/> + <const name="Machine" value="1"/> + <const name="Session" value="2"/> + </enum> + + <enum + name="BIOSBootMenuMode" + uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5" + > + <desc> + BIOS boot menu mode. + </desc> + + <const name="Disabled" value="0"/> + <const name="MenuOnly" value="1"/> + <const name="MessageAndMenu" value="2"/> + </enum> + + <enum + name="APICMode" + uuid="c6884ba5-3cc4-4a92-a7f6-4410f9fd894e" + > + <desc> + BIOS APIC initialization mode. If the hardware does not support the + mode then the code falls back to a lower mode. + </desc> + + <const name="Disabled" value="0"/> + <const name="APIC" value="1"/> + <const name="X2APIC" value="2"/> + </enum> + + <enum + name="ProcessorFeature" + uuid="0064dece-000e-4963-00f8-eb9b00674c8a" + > + <desc> + CPU features. + </desc> + + <const name="HWVirtEx" value="0"/> + <const name="PAE" value="1"/> + <const name="LongMode" value="2"/> + <const name="NestedPaging" value="3"/> + <const name="UnrestrictedGuest" value="4"/> + <const name="NestedHWVirt" value="5"/> + <const name="VirtVmsaveVmload" value="6"/> + </enum> + + <enum + name="FirmwareType" + uuid="b903f264-c230-483e-ac74-2b37ce60d371" + > + <desc> + Firmware type. + </desc> + <const name="BIOS" value="1"> + <desc>BIOS Firmware.</desc> + </const> + <const name="EFI" value="2"> + <desc>EFI Firmware, bitness detected basing on OS type.</desc> + </const> + <const name="EFI32" value="3"> + <desc>EFI firmware, 32-bit.</desc> + </const> + <const name="EFI64" value="4"> + <desc>EFI firmware, 64-bit.</desc> + </const> + <const name="EFIDUAL" value="5"> + <desc>EFI firmware, combined 32 and 64-bit.</desc> + </const> + </enum> + + <enum + name="PointingHIDType" + uuid="b3fd8215-6870-4e61-b6d9-2998fa625de0" + > + <desc> + Type of pointing device used in a virtual machine. + </desc> + <const name="None" value="1"> + <desc>No mouse.</desc> + </const> + <const name="PS2Mouse" value="2"> + <desc>PS/2 auxiliary device, a.k.a. mouse.</desc> + </const> + <const name="USBMouse" value="3"> + <desc>USB mouse (relative pointer).</desc> + </const> + <const name="USBTablet" value="4"> + <desc> + USB tablet (absolute pointer). Also enables a relative USB mouse in + addition. + </desc> + </const> + <const name="ComboMouse" value="5"> + <desc> + Combined device, working as PS/2 or USB mouse, depending on guest + behavior. Using this device can have negative performance implications. + </desc> + </const> + <const name="USBMultiTouch" value="6"> + <desc> + USB multi-touch device, just touchscreen. It is a specific mode of the + USB tablet and also enables the mouse device. + </desc> + </const> + <const name="USBMultiTouchScreenPlusPad" value="7"> + <desc> + USB multi-touch device, touchscreen plus touchpad. It also enables the + mouse device. + </desc> + </const> + </enum> + + <enum + name="KeyboardHIDType" + uuid="383e43d7-5c7c-4ec8-9cb8-eda1bccd6699" + > + <desc> + Type of keyboard device used in a virtual machine. + </desc> + <const name="None" value="1"> + <desc>No keyboard.</desc> + </const> + <const name="PS2Keyboard" value="2"> + <desc>PS/2 keyboard.</desc> + </const> + <const name="USBKeyboard" value="3"> + <desc>USB keyboard.</desc> + </const> + <const name="ComboKeyboard" value="4"> + <desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior. + Using of such device can have negative performance implications.</desc> + </const> + </enum> + + <enum + name="BitmapFormat" + uuid="afb2bf39-8b1e-4f9f-8948-d1b887f83eb0" + > + <desc> + Format of a bitmap. Generic values for formats used by + the source bitmap, the screen shot or image update APIs. + </desc> + + <const name="Opaque" value="0"> + <desc> + Unknown buffer format (the user may not assume any particular format of + the buffer). + </desc> + </const> + <const name="BGR" value="0x20524742"> + <desc> + Generic BGR format without alpha channel. + Pixel layout depends on the number of bits per pixel: + <ul> + <li> + <b>32</b> - bits 31:24 undefined, bits 23:16 R, bits 15:8 G, bits 7:0 B. + </li> + + <li> + <b>16</b> - bits 15:11 R, bits 10:5 G, bits 4:0 B. + </li> + </ul> + </desc> + </const> + <const name="BGR0" value="0x30524742"> + <desc> + 4 bytes per pixel: B, G, R, 0. + </desc> + </const> + <const name="BGRA" value="0x41524742"> + <desc> + 4 bytes per pixel: B, G, R, A. + </desc> + </const> + <const name="RGBA" value="0x41424752"> + <desc> + 4 bytes per pixel: R, G, B, A. + </desc> + </const> + <const name="PNG" value="0x20474E50"> + <desc> + PNG image. + </desc> + </const> + <const name="JPEG" value="0x4745504A"> + <desc> + JPEG image. + </desc> + </const> + </enum> + + <enum + name="PartitioningType" + uuid="64c4c806-8908-4c0b-9a51-2d7a0151321f" + > + <desc> + The type of the disk partition. + </desc> + + <const name="MBR" value="0"/> + <const name="GPT" value="1"/> + </enum> + + <enum + name="PartitionType" + uuid="84a6629c-8e9c-474c-adbb-21995671597f" + > + <desc></desc> + + <!-- MBR partition IDs using the same value: --> + <const name="Empty" value="0"><desc>Empty partition entry</desc></const> + <const name="FAT12" value="1"> <desc>FAT12 if partition size less than 65536 sectors</desc></const> + <const name="FAT16" value="4"> <desc>FAT16 if partition size less than 65536 sectors</desc></const> + <const name="FAT" value="6"> <desc>FAT12 or FAT16 if partition size greater or equal than 65536 sectors</desc></const> + <const name="IFS" value="7"> <desc>NT and OS/2 installable file system, e.g. NTFS, exFAT, HPFS.</desc></const> + <const name="FAT32CHS" value="11"> <desc>The FAT32 with CHS addressing.</desc></const> + <const name="FAT32LBA" value="12"> <desc>The FAT32 with LBA addressing.</desc></const> + <const name="FAT16B" value="14"> <desc>The FAT16 with LBA addressing.</desc></const> + <const name="Extended" value="15"> <desc>The extended partition with LBA addressing.</desc></const> + <const name="WindowsRE" value="39"> <desc>Windows Recovery Environment (RE) partition (hidden NTFS partition).</desc></const> + <const name="LinuxSwapOld" value="66"> <desc>The linux swap partition (old versions).</desc></const> + <const name="LinuxOld" value="67"> <desc>The linux native partition (old versions).</desc></const> + <const name="DragonFlyBSDSlice" value="108"><desc>The BSD slice.</desc></const> + <const name="LinuxSwap" value="130"><desc>The linux swap partition.</desc></const> + <const name="Linux" value="131"><desc>The linux native partition.</desc></const> + <const name="LinuxExtended" value="133"><desc>The linux extended partition.</desc></const> + <const name="LinuxLVM" value="142"><desc>The linux LVM partition.</desc></const> + <const name="BSDSlice" value="165"><desc>The BSD slice.</desc></const> + <const name="AppleUFS" value="168"><desc>The Apple UFS partition.</desc></const> + <const name="AppleHFS" value="175"><desc>The Apple HFS partition.</desc></const> + <const name="Solaris" value="191"><desc>The Apple HFS partition.</desc></const> + <const name="GPT" value="238"><desc>The GPT protective MBR partition.</desc></const> + <const name="EFI" value="239"><desc>The EFI system partition.</desc></const> + + <!-- Dummy value: --> + <const name="Unknown" value="256"><desc>Unknown partition type.</desc></const> + + <!-- GPT partition types: --> + <const name="MBR" value="257"><desc>MBR partition scheme.</desc></const> + <const name="iFFS" value="258"><desc>Intel Fast Flash (iFFS) partition.</desc></const> + <const name="SonyBoot" value="259"><desc>Sony boot partition.</desc></const> + <const name="LenovoBoot" value="260"><desc>Lenovo boot partition.</desc></const> + + <const name="WindowsMSR" value="270"><desc>Microsoft Reserved Partition (MSR).</desc></const> + <const name="WindowsBasicData" value="271"><desc>Windows Basic data partition</desc></const> + <const name="WindowsLDMMeta" value="272"><desc>Windows Logical Disk Manager (LDM) metadata partition.</desc></const> + <const name="WindowsLDMData" value="273"><desc>Windows Logical Disk Manager data partition.</desc></const> + <const name="WindowsRecovery" value="274"><desc>Windows Recovery Environment.</desc></const> + <const name="WindowsStorageSpaces" value="276"><desc>Windows Storage Spaces partition.</desc></const> + <const name="WindowsStorageReplica" value="277"><desc>Windows Storage Replica partition.</desc></const> + <const name="IBMGPFS" value="275"><desc>IBM General Parallel File System (GPFS) partition.</desc></const> + + <const name="LinuxData" value="300"><desc>Linux filesystem data.</desc></const> + <const name="LinuxRAID" value="301"><desc>Linux RAID partition.</desc></const> + <const name="LinuxRootX86" value="302"><desc>Linux root partition for x86.</desc></const> + <const name="LinuxRootAMD64" value="303"><desc>Linux root partition for AMD64.</desc></const> + <const name="LinuxRootARM32" value="304"><desc>Linux root partition for ARM32.</desc></const> + <const name="LinuxRootARM64" value="305"><desc>Linux root partition for ARM64 / AArch64.</desc></const> + <const name="LinuxHome" value="306"><desc>Linux /home partition.</desc></const> + <const name="LinuxSrv" value="307"><desc>Linux /srv partition.</desc></const> + <const name="LinuxPlainDmCrypt" value="308"><desc>Linux plain dm-crypt partition.</desc></const> + <const name="LinuxLUKS" value="309"><desc>Linux unitified key setup (LUKS) partition.</desc></const> + <const name="LinuxReserved" value="310"><desc>Linux reserved partition.</desc></const> + + <const name="FreeBSDBoot" value="330"><desc>FreeBSD boot partition.</desc></const> + <const name="FreeBSDData" value="331"><desc>FreeBSD data partition.</desc></const> + <const name="FreeBSDSwap" value="332"><desc>FreeBSD swap partition.</desc></const> + <const name="FreeBSDUFS" value="333"><desc>FreeBSD unix file system (UFS) partition.</desc></const> + <const name="FreeBSDVinum" value="334"><desc>FreeBSD Vinum volume manager partition.</desc></const> + <const name="FreeBSDZFS" value="335"><desc>FreeBSD ZFS partition.</desc></const> + <const name="FreeBSDUnknown" value="359"><desc>Unknown FreeBSD partition.</desc></const> + + <const name="AppleHFSPlus" value="360"><desc>Apple hierarchical file system plus (HFS+) partition.</desc></const> + <const name="AppleAPFS" value="361"><desc>Apple APFS/FileFault container partition.</desc></const> + <const name="AppleRAID" value="362"><desc>Apple RAID partition.</desc></const> + <const name="AppleRAIDOffline" value="363"><desc>Apple RAID partition, offline.</desc></const> + <const name="AppleBoot" value="364"><desc>Apple boot partition.</desc></const> + <const name="AppleLabel" value="365"><desc>Apple label.</desc></const> + <const name="AppleTvRecovery" value="366"><desc>Apple TV recovery partition.</desc></const> + <const name="AppleCoreStorage" value="367"><desc>Apple Core Storage Containe.</desc></const> + <const name="SoftRAIDStatus" value="370"><desc>SoftRAID status.</desc></const> + <const name="SoftRAIDScratch" value="371"><desc>SoftRAID scratch.</desc></const> + <const name="SoftRAIDVolume" value="372"><desc>SoftRAID volume.</desc></const> + <const name="SoftRAIDCache" value="373"><desc>SoftRAID cache.</desc></const> + <const name="AppleUnknown" value="389"><desc>Unknown Apple partition.</desc></const> + + <const name="SolarisBoot" value="390"><desc>Solaris boot partition.</desc></const> + <const name="SolarisRoot" value="391"><desc>Solaris root partition.</desc></const> + <const name="SolarisSwap" value="392"><desc>Solaris swap partition.</desc></const> + <const name="SolarisBackup" value="393"><desc>Solaris backup partition.</desc></const> + <const name="SolarisUsr" value="394"><desc>Solaris /usr partition.</desc></const> + <const name="SolarisVar" value="395"><desc>Solaris /var partition.</desc></const> + <const name="SolarisHome" value="396"><desc>Solaris /home partition.</desc></const> + <const name="SolarisAltSector" value="397"><desc>Solaris alternate sector.</desc></const> + <const name="SolarisReserved" value="398"><desc>Solaris reserved partition.</desc></const> + <const name="SolarisUnknown" value="419"><desc>Unknown Solaris partition.</desc></const> + + <const name="NetBSDSwap" value="420"><desc>NetBSD swap partition.</desc></const> + <const name="NetBSDFFS" value="421"><desc>NetBSD fast file system (FFS) partition.</desc></const> + <const name="NetBSDLFS" value="422"><desc>NetBSD log structured file system (LFS) partition.</desc></const> + <const name="NetBSDRAID" value="423"><desc>NetBSD RAID partition.</desc></const> + <const name="NetBSDConcatenated" value="424"><desc>NetBSD concatenated partition.</desc></const> + <const name="NetBSDEncrypted" value="425"><desc>NetBSD encrypted partition.</desc></const> + <const name="NetBSDUnknown" value="449"><desc>Unknown NetBSD partition.</desc></const> + + <const name="ChromeOSKernel" value="450"><desc>Chrome OS kernel partition.</desc></const> + <const name="ChromeOSRootFS" value="451"><desc>Chrome OS root file system partition.</desc></const> + <const name="ChromeOSFuture" value="452"><desc>Chrome OS partition reserved for future.</desc></const> + + <const name="ContLnxUsr" value="480"><desc>Container Linux /usr partition.</desc></const> + <const name="ContLnxRoot" value="481"><desc>Container Linux resizable root filesystem partition.</desc></const> + <const name="ContLnxReserved" value="482"><desc>Container Linux OEM customization partition.</desc></const> + <const name="ContLnxRootRAID" value="483"><desc>Container Linux root filesystem on RAID partition.</desc></const> + + <const name="HaikuBFS" value="510"><desc>Haiku BFS</desc></const> + + <const name="MidntBSDBoot" value="540"><desc>MidnightBSD boot partition.</desc></const> + <const name="MidntBSDData" value="541"><desc>MidnightBSD data partition.</desc></const> + <const name="MidntBSDSwap" value="542"><desc>MidnightBSD swap partition.</desc></const> + <const name="MidntBSDUFS" value="543"><desc>MidnightBSD unix file system (UFS) partition.</desc></const> + <const name="MidntBSDVium" value="544"><desc>MidnightBSD Vinum volume manager partition.</desc></const> + <const name="MidntBSDZFS" value="545"><desc>MidnightBSD ZFS partition.</desc></const> + <const name="MidntBSDUnknown" value="569"><desc>Unknown MidnightBSD partition.</desc></const> + + <const name="OpenBSDData" value="570"><desc>OpenBSD data partition.</desc></const> + + <const name="QNXPowerSafeFS" value="600"><desc>QNX power-safe file system partition.</desc></const> + + <const name="Plan9" value="630"><desc>Plan 9 partition.</desc></const> + + <const name="VMWareVMKCore" value="660"><desc>VMWare ESX coredump partition.</desc></const> + <const name="VMWareVMFS" value="661"><desc>VMWare ESX virtual machine file system (VMFS) partition.</desc></const> + <const name="VMWareReserved" value="662"><desc>VMWare ESX reserved partition.</desc></const> + <const name="VMWareUnknown" value="689"><desc>Unknown VMWare partition.</desc></const> + + <const name="AndroidX86Bootloader" value="690"><desc>Android x86 bootloader partition.</desc></const> + <const name="AndroidX86Bootloader2" value="691"><desc>Android x86 bootloader2 partition.</desc></const> + <const name="AndroidX86Boot" value="692"><desc>Android x86 boot partition.</desc></const> + <const name="AndroidX86Recovery" value="693"><desc>Android x86 recovery partition.</desc></const> + <const name="AndroidX86Misc" value="694"><desc>Android x86 misc partition.</desc></const> + <const name="AndroidX86Metadata" value="695"><desc>Android x86 metadata partition.</desc></const> + <const name="AndroidX86System" value="696"><desc>Android x86 system partition.</desc></const> + <const name="AndroidX86Cache" value="697"><desc>Android x86 cache partition.</desc></const> + <const name="AndroidX86Data" value="698"><desc>Android x86 data partition.</desc></const> + <const name="AndroidX86Persistent" value="699"><desc>Android x86 persistent data partition.</desc></const> + <const name="AndroidX86Vendor" value="700"><desc>Android x86 vendor partition.</desc></const> + <const name="AndroidX86Config" value="701"><desc>Android x86 config partition.</desc></const> + <const name="AndroidX86Factory" value="702"><desc>Android x86 factory partition.</desc></const> + <const name="AndroidX86FactoryAlt" value="703"><desc>Android x86 alternative factory partition.</desc></const> + <const name="AndroidX86Fastboot" value="704"><desc>Android x86 fastboot partition.</desc></const> + <const name="AndroidX86OEM" value="705"><desc>Android x86 OEM partition.</desc></const> + + <const name="AndroidARMMeta" value="720"><desc>Android ARM meta partition.</desc></const> + <const name="AndroidARMExt" value="721"><desc>Android ARM EXT partition.</desc></const> + + <const name="ONIEBoot" value="750"><desc>Open Network Install Environment (ONIE) boot partition.</desc></const> + <const name="ONIEConfig" value="751"><desc>Open Network Install Environment (ONIE) config partition.</desc></const> + + <const name="PowerPCPrep" value="780"><desc>PowerPC PReP boot partition.</desc></const> + + <const name="XDGShrBootConfig" value="810"><desc>freedesktop.org shared boot loader configuration partition.</desc></const> + + <const name="CephBlock" value="830"><desc>Ceph block partition.</desc></const> + <const name="CephBlockDB" value="831"><desc>Ceph block DB partition.</desc></const> + <const name="CephBlockDBDmc" value="832"><desc>Ceph dm-crypt block DB partition.</desc></const> + <const name="CephBlockDBDmcLUKS" value="833"><desc>Ceph dm-crypt Linux unitified key setup (LUKS) block DB partition.</desc></const> + <const name="CephBlockDmc" value="834"><desc>Ceph dm-crypt block partition.</desc></const> + <const name="CephBlockDmcLUKS" value="835"><desc>Ceph dm-crypt Linux unitified key setup (LUKS) block partition.</desc></const> + <const name="CephBlockWALog" value="836"><desc>Ceph block write-ahead log partition.</desc></const> + <const name="CephBlockWALogDmc" value="837"><desc>Ceph dm-crypt block write-ahead log partition.</desc></const> + <const name="CephBlockWALogDmcLUKS" value="838"><desc>Ceph dm-crypt Linux unitified key setup (LUKS) block write-ahead log partition.</desc></const> + <const name="CephDisk" value="839"><desc>Ceph disk in creation partition.</desc></const> + <const name="CephDiskDmc" value="840"><desc>Ceph dm-crypt disk in creation partition.</desc></const> + <const name="CephJournal" value="841"><desc>Ceph Journal partition.</desc></const> + <const name="CephJournalDmc" value="842"><desc>Ceph dm-crypt journal partition.</desc></const> + <const name="CephJournalDmcLUKS" value="843"><desc>Ceph dm-crypt Linux unitified key setup (LUKS) journal partition.</desc></const> + <const name="CephLockbox" value="844"><desc>Ceph Lockbox for dm-crypt keys partition.</desc></const> + <const name="CephMultipathBlock1" value="845"><desc>Ceph multipath block 1 partition.</desc></const> + <const name="CephMultipathBlock2" value="846"><desc>Ceph multipath block 2 partition.</desc></const> + <const name="CephMultipathBlockDB" value="847"><desc>Ceph multipath block DB partition.</desc></const> + <const name="CephMultipathBLockWALog" value="848"><desc>Ceph multipath block write-ahead log partition.</desc></const> + <const name="CephMultipathJournal" value="849"><desc>Ceph multipath journal partition.</desc></const> + <const name="CephMultipathOSD" value="851"><desc>Ceph multipath object storage deamon (OSD) partition.</desc></const> + <const name="CephOSD" value="852"><desc>Ceph object storage deamon (OSD) partition.</desc></const> + <const name="CephOSDDmc" value="853"><desc>Ceph dm-crypt object storage deamon (OSD) partition.</desc></const> + <const name="CephOSDDmcLUKS" value="854"><desc>Ceph dm-crypt Linux unitified key setup (LUKS) object storage deamon (OSD) partition.</desc></const> + </enum> + + + <!-- + // IVirtualBoxErrorInfo + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IVirtualBoxErrorInfo" extends="$errorinfo" + uuid="c1bcc6d5-7966-481d-ab0b-d0ed73e28135" + supportsErrorInfo="no" + wsmap="managed" + rest="managed" + > + <desc> + The IVirtualBoxErrorInfo interface represents extended error information. + + Extended error information can be set by VirtualBox components after + unsuccessful or partially successful method invocation. This information + can be retrieved by the calling party as an IVirtualBoxErrorInfo object + and then shown to the client in addition to the plain 32-bit result code. + + In MS COM, this interface extends the IErrorInfo interface, + in XPCOM, it extends the nsIException interface. In both cases, + it provides a set of common attributes to retrieve error + information. + + Sometimes invocation of some component's method may involve methods of + other components that may also fail (independently of this method's + failure), or a series of non-fatal errors may precede a fatal error that + causes method failure. In cases like that, it may be desirable to preserve + information about all errors happened during method invocation and deliver + it to the caller. The <link to="#next"/> attribute is intended + specifically for this purpose and allows to represent a chain of errors + through a single IVirtualBoxErrorInfo object set after method invocation. + + <note>errors are stored to a chain in the reverse order, i.e. the + initial error object you query right after method invocation is the last + error set by the callee, the object it points to in the @a next attribute + is the previous error and so on, up to the first error (which is the last + in the chain).</note> + </desc> + + <attribute name="resultCode" type="long" readonly="yes"> + <desc> + Result code of the error. + Usually, it will be the same as the result code returned + by the method that provided this error information, but not + always. For example, on Win32, CoCreateInstance() will most + likely return E_NOINTERFACE upon unsuccessful component + instantiation attempt, but not the value the component factory + returned. Value is typed 'long', not 'result', + to make interface usable from scripting languages. + <note> + In MS COM, there is no equivalent. + In XPCOM, it is the same as nsIException::result. + </note> + </desc> + </attribute> + + <attribute name="resultDetail" type="long" readonly="yes"> + <desc> + Optional result data of this error. This will vary depending on the + actual error usage. By default this attribute is not being used. + </desc> + </attribute> + + <attribute name="interfaceID" type="uuid" mod="string" readonly="yes"> + <desc> + UUID of the interface that defined the error. + <note> + In MS COM, it is the same as IErrorInfo::GetGUID, except for the + data type. + In XPCOM, there is no equivalent. + </note> + </desc> + </attribute> + + <attribute name="component" type="wstring" readonly="yes"> + <desc> + Name of the component that generated the error. + <note> + In MS COM, it is the same as IErrorInfo::GetSource. + In XPCOM, there is no equivalent. + </note> + </desc> + </attribute> + + <attribute name="text" type="wstring" readonly="yes"> + <desc> + Text description of the error. + <note> + In MS COM, it is the same as IErrorInfo::GetDescription. + In XPCOM, it is the same as nsIException::message. + </note> + </desc> + </attribute> + + <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + Next error object if there is any, or @c null otherwise. + <note> + In MS COM, there is no equivalent. + In XPCOM, it is the same as nsIException::inner. + </note> + </desc> + </attribute> + + </interface> + + <!-- + // INATNetwork + ///////////////////////////////////////////////////////////////////////// + --> + + <interface name="INATNetwork" extends="$unknown" + uuid="4fdebbf0-be30-49c0-b315-e9749e1bded1" + wsmap="managed" + rest="managed" + reservedMethods="2" reservedAttributes="8" + > + + <attribute name="networkName" type="wstring"> + <desc> + TBD: the idea, technically we can start any number of the NAT networks, + but we should expect that at some point we will get collisions because of + port-forwanding rules. so perhaps we should support only single instance of NAT + network. + </desc> + </attribute> + <attribute name="enabled" type="boolean"/> + <attribute name="network" type="wstring"> + <desc> + This is CIDR IPv4 string. Specifying it user defines IPv4 addresses + of gateway (low address + 1) and DHCP server (= low address + 2). + Note: If there are defined IPv4 port-forward rules update of network + will be ignored (because new assignment could break existing rules). + </desc> + </attribute> + <attribute name="gateway" type="wstring" readonly="yes"> + <desc> + This attribute is read-only. It's recalculated on changing + network attribute (low address of network + 1). + </desc> + </attribute> + <attribute name="IPv6Enabled" type="boolean"> + <desc> + This attribute define whether gateway will support IPv6 or not. + </desc> + </attribute> + <attribute name="IPv6Prefix" type="wstring"> + <desc> + This a CIDR IPv6 defining prefix for link-local addresses + autoconfiguration within network. Note: ignored if attribute + IPv6Enabled is false. + </desc> + </attribute> + <attribute name="advertiseDefaultIPv6RouteEnabled" type="boolean" dtracename="advertiseDefaultIPv6Route"/> + <attribute name="needDhcpServer" type="boolean"/> + <attribute name="eventSource" type="IEventSource" readonly="yes"/> + <attribute name="portForwardRules4" type="wstring" readonly="yes" safearray="yes"> + <desc>Array of NAT port-forwarding rules in string representation, + in the following format: + "name:protocolid:[host ip]:host port:[guest ip]:guest port". + </desc> + </attribute> + <attribute name="localMappings" type="wstring" readonly="yes" safearray="yes"> + <desc>Array of mappings (address,offset),e.g. ("127.0.1.1=4") maps 127.0.1.1 to networkid + 4. + </desc> + </attribute> + + <method name="addLocalMapping"> + <rest request="post" path="/natnetworks/{networkid}/configuration/"/> + <desc> + </desc> + <param name="hostid" type="wstring" dir="in"/> + <param name="offset" type="long" dir="in"/> + </method> + + <attribute name="loopbackIp6" type="long"> + <desc>Offset in ipv6 network from network id for address mapped into loopback6 interface of the host. + </desc> + </attribute> + + <attribute name="portForwardRules6" type="wstring" readonly="yes" safearray="yes"> + <desc>Array of NAT port-forwarding rules in string representation, in the + following format: "name:protocolid:[host ip]:host port:[guest ip]:guest port". + </desc> + </attribute> + <method name="addPortForwardRule"> + <rest request="post" path="/natnetworks/{networkid}/configuration/"/> + <param name="isIpv6" type="boolean" dir="in"/> + <param name="ruleName" type="wstring" dir="in"/> + <param name="proto" type="NATProtocol" dir="in"> + <desc>Protocol handled with the rule.</desc> + </param> + <param name="hostIP" type="wstring" dir="in"> + <desc>IP of the host interface to which the rule should apply. + An empty ip address is acceptable, in which case the NAT engine + binds the handling socket to any interface. + </desc> + </param> + <param name="hostPort" type="unsigned short" dir="in"> + <desc>The port number to listen on.</desc> + </param> + <param name="guestIP" type="wstring" dir="in"> + <desc>The IP address of the guest which the NAT engine will forward + matching packets to. An empty IP address is not acceptable.</desc> + </param> + <param name="guestPort" type="unsigned short" dir="in"> + <desc>The port number to forward.</desc> + </param> + </method> + <method name="removePortForwardRule"> + <rest request="post" path="/natnetworks/{networkid}/configuration/"/> + <param name="isIpv6" type="boolean" dir="in"/> + <param name="ruleName" type="wstring" dir="in"/> + </method> + <method name="start"> + <rest request="post" path="/natnetworks/{networkid}/actions/"/> + </method> + <method name="stop"> + <rest request="post" path="/natnetworks/{networkid}/actions/"/> + </method> + </interface> + + + <!-- + // ICloudNetwork + ///////////////////////////////////////////////////////////////////////// + --> + + <interface name="ICloudNetwork" extends="$unknown" + uuid="d8e3496e-735f-4fde-8a54-427d49409b5f" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="12" + > + + <attribute name="networkName" type="wstring"> + <desc> + TBD: User-friendly, descriptive name of cloud subnet. For example, domain + names of subnet and vcn, separated by dot. + </desc> + </attribute> + <attribute name="enabled" type="boolean"/> + <attribute name="provider" type="wstring"> + <desc> + Cloud provider short name. + </desc> + </attribute> + <attribute name="profile" type="wstring"> + <desc> + Cloud profile name. + </desc> + </attribute> + <attribute name="networkId" type="wstring"> + <desc> + Cloud network id. + </desc> + </attribute> + </interface> + + <!-- + // IHostOnlyNetwork + ///////////////////////////////////////////////////////////////////////// + --> + + <interface name="IHostOnlyNetwork" extends="$unknown" + uuid="6eb5de7d-9a67-4fde-83be-f768084d03b5" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + + <attribute name="networkName" type="wstring"> + <desc> + TBD: User-friendly, descriptive name of host-only network. For example, + "Host-only network 192.168.56.0". + </desc> + </attribute> + <attribute name="enabled" type="boolean"/> + <attribute name="networkMask" type="wstring"> + <desc> + specifies network mask + </desc> + </attribute> + + <attribute name="hostIP" type="wstring" readonly="yes"> + <desc> + host IP address, which usually is the lower IP address of DHCP range. + </desc> + </attribute> + + <attribute name="lowerIP" type="wstring"> + <desc> + specifies from IP address in DHCP address range + </desc> + </attribute> + + <attribute name="upperIP" type="wstring"> + <desc> + specifies to IP address in DHCP address range + </desc> + </attribute> + + <attribute name="id" type="uuid" mod="string"> + <desc> + Host-only network ID. + </desc> + </attribute> + </interface> + + <!-- + // IDHCPServer and associates + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="DHCPOption" + uuid="00f5b10f-0021-4513-00f7-5bf4000982bf"> + <!-- Names should exactly match those given in DhcpOptions.h. + Everything must be documented properly. + + Note! We use these descriptions in the VBoxManage man page / manual. + When making changes remember to regenerate the man page bits: + kmk -C doc/manual dhcpoptions + --> + <const name="SubnetMask" value="1"><desc>IPv4 netmask. Set to <link to="IDHCPServer::networkMask"/> by default.</desc></const> + <const name="TimeOffset" value="2"><desc>UTC offset in seconds (32-bit decimal value).</desc></const> + <const name="Routers" value="3"><desc>Space separated list of IPv4 router addresses.</desc></const> + <const name="TimeServers" value="4"><desc>Space separated list of IPv4 time server (RFC 868) addresses.</desc></const> + <const name="NameServers" value="5"><desc>Space separated list of IPv4 name server (IEN 116) addresses.</desc></const> + <const name="DomainNameServers" value="6"><desc>Space separated list of IPv4 DNS addresses.</desc></const> + <const name="LogServers" value="7"><desc>Space separated list of IPv4 log server addresses.</desc></const> + <const name="CookieServers" value="8"><desc>Space separated list of IPv4 cookie server (RFC 865) addresses.</desc></const> + <const name="LPRServers" value="9"><desc>Space separated list of IPv4 line printer server (RFC 1179) addresses.</desc></const> + <const name="ImpressServers" value="10"><desc>Space separated list of IPv4 imagen impress server addresses.</desc></const> + <const name="ResourseLocationServers" value="11"><desc>Space separated list of IPv4 resource location (RFC 887) addresses.</desc></const> + <const name="HostName" value="12"><desc>The client name. See RFC 1035 for character limits. </desc></const> + <const name="BootFileSize" value="13"><desc>Number of 512 byte blocks making up the boot file (16-bit decimal value).</desc></const> + <const name="MeritDumpFile" value="14"><desc>Client core file.</desc></const> + <const name="DomainName" value="15"><desc>Domain name for the client.</desc></const> + <const name="SwapServer" value="16"><desc>IPv4 address of the swap server that the client should use.</desc></const> + <const name="RootPath" value="17"><desc>The path to the root disk the client should use.</desc></const> + <const name="ExtensionPath" value="18"><desc>Path to a file containing additional DHCP options (RFC2123).</desc></const> + <const name="IPForwarding" value="19"><desc>Whether IP forwarding should be enabled by the client (boolean).</desc></const> + <const name="OptNonLocalSourceRouting" value="20"><desc>Whether non-local datagrams should be forwarded by the client (boolean)</desc></const> + <const name="PolicyFilter" value="21"><desc>List of IPv4 addresses and masks paris controlling non-local source routing.</desc></const> + <const name="MaxDgramReassemblySize" value="22"><desc>The maximum datagram size the client should reassemble (16-bit decimal value).</desc></const> + <const name="DefaultIPTTL" value="23"><desc>The default time-to-leave on outgoing (IP) datagrams (8-bit decimal value).</desc></const> + <const name="PathMTUAgingTimeout" value="24"><desc>RFC1191 path MTU discovery timeout value in seconds (32-bit decimal value).</desc></const> + <const name="PathMTUPlateauTable" value="25"><desc>RFC1191 path MTU discovery size table, sorted in ascending order (list of 16-bit decimal values).</desc></const> + <const name="InterfaceMTU" value="26"><desc>The MTU size for the interface (16-bit decimal value).</desc></const> + <const name="AllSubnetsAreLocal" value="27"><desc>Indicates whether the MTU size is the same for all subnets (boolean).</desc></const> + <const name="BroadcastAddress" value="28"><desc>Broadcast address (RFC1122) for the client to use (IPv4 address).</desc></const> + <const name="PerformMaskDiscovery" value="29"><desc>Whether to perform subnet mask discovery via ICMP (boolean).</desc></const> + <const name="MaskSupplier" value="30"><desc>Whether to respond to subnet mask requests via ICMP (boolean).</desc></const> + <const name="PerformRouterDiscovery" value="31"><desc>Whether to perform router discovery (RFC1256) (boolean).</desc></const> + <const name="RouterSolicitationAddress" value="32"><desc>Where to send router solicitation requests (RFC1256) (IPv4 address).</desc></const> + <const name="StaticRoute" value="33"><desc>List of network and router address pairs addresses.</desc></const> + <const name="TrailerEncapsulation" value="34"><desc>Whether to negotiate the use of trailers for ARP (RTF893) (boolean).</desc></const> + <const name="ARPCacheTimeout" value="35"><desc>The timeout in seconds for ARP cache entries (32-bit decimal value).</desc></const> + <const name="EthernetEncapsulation" value="36"><desc>Whether to use IEEE 802.3 (RTF1042) rather than of v2 (RFC894) ethernet encapsulation (boolean).</desc></const> + <const name="TCPDefaultTTL" value="37"><desc>Default time-to-live for TCP sends (non-zero 8-bit decimal value).</desc></const> + <const name="TCPKeepaliveInterval" value="38"><desc>The interface in seconds between TCP keepalive messages (32-bit decimal value).</desc></const> + <const name="TCPKeepaliveGarbage" value="39"><desc>Whether to include a byte of garbage in TCP keepalive messages for backward compatibility (boolean).</desc></const> + <const name="NISDomain" value="40"><desc>The NIS (Sun Network Information Services) domain name (string).</desc></const> + <const name="NISServers" value="41"><desc>Space separated list of IPv4 NIS server addresses.</desc></const> + <const name="NTPServers" value="42"><desc>Space separated list of IPv4 NTP (RFC1035) server addresses.</desc></const> + <const name="VendorSpecificInfo" value="43"><desc>Vendor specific information. Only accessible using <link to="DHCPOptionEncoding_Hex"/>.</desc></const> + <const name="NetBIOSNameServers" value="44"><desc>Space separated list of IPv4 NetBIOS name server (NBNS) addresses (RFC1001,RFC1002).</desc></const> + <const name="NetBIOSDatagramServers" value="45"><desc>Space separated list of IPv4 NetBIOS datagram distribution server (NBDD) addresses (RFC1001,RFC1002).</desc></const> + <const name="NetBIOSNodeType" value="46"><desc>NetBIOS node type (RFC1001,RFC1002): 1=B-node, 2=P-node, 4=M-node, and 8=H-node (8-bit decimal value).</desc></const> + <const name="NetBIOSScope" value="47"><desc>NetBIOS scope (RFC1001,RFC1002). Only accessible using <link to="DHCPOptionEncoding_Hex"/>.</desc></const> + <const name="XWindowsFontServers" value="48"><desc>Space separated list of IPv4 X windows font server addresses.</desc></const> + <const name="XWindowsDisplayManager" value="49"><desc>Space separated list of IPv4 X windows display manager addresses.</desc></const> + <!-- Options 50 thru 59 are considered DHCP internal and currently not settable. --> + <const name="NetWareIPDomainName" value="62"><desc>Netware IP domain name (RFC2242) (string).</desc></const> + <const name="NetWareIPInformation" value="63"><desc>Netware IP information (RFC2242). Only accessible using <link to="DHCPOptionEncoding_Hex"/>.</desc></const> + <const name="NISPlusDomain" value="64"><desc>The NIS+ domain name (string).</desc></const> + <const name="NISPlusServers" value="65"><desc>Space separated list of IPv4 NIS+ server addresses.</desc></const> + <const name="TFTPServerName" value="66"><desc>TFTP server name (string).</desc></const> + <const name="BootfileName" value="67"><desc>Bootfile name (string).</desc></const> + <const name="MobileIPHomeAgents" value="68"><desc>Space separated list of IPv4 mobile IP agent addresses.</desc></const> + <const name="SMTPServers" value="69"><desc>Space separated list of IPv4 simple mail transport protocol (SMPT) server addresses.</desc></const> + <const name="POP3Servers" value="70"><desc>Space separated list of IPv4 post office protocol 3 (POP3) server addresses.</desc></const> + <const name="NNTPServers" value="71"><desc>Space separated list of IPv4 network news transport protocol (NTTP) server addresses.</desc></const> + <const name="WWWServers" value="72"><desc>Space separated list of default IPv4 world wide web (WWW) server addresses.</desc></const> + <const name="FingerServers" value="73"><desc>Space separated list of default IPv4 finger server addresses.</desc></const> + <const name="IRCServers" value="74"><desc>Space separated list of default IPv4 internet relay chat (IRC) server addresses.</desc></const> + <const name="StreetTalkServers" value="75"><desc>Space separated list of IPv4 StreetTalk server addresses.</desc></const> + <const name="STDAServers" value="76"><desc>Space separated list of IPv4 StreetTalk directory assistance (STDA) server addresses.</desc></const> + <!-- 77 is client only --> + <const name="SLPDirectoryAgent" value="78"><desc>Addresses of one or more service location protocol (SLP) directory agent, and an indicator of whether their use is mandatory. Only accessible using <link to="DHCPOptionEncoding_Hex"/>.</desc></const> + <const name="SLPServiceScope" value="79"><desc>List of service scopes for the service location protocol (SLP) and whether using the list is mandator. Only accessible using <link to="DHCPOptionEncoding_Hex"/>.</desc></const> + <!-- 80 is client only --> + <const name="DomainSearch" value="119"><desc>Domain search list, see RFC3397 and section 4.1.4 in RFC1035 for encoding. Only accessible using <link to="DHCPOptionEncoding_Hex"/>.</desc></const> + </enum> + + <enum + name="DHCPOptionEncoding" + uuid="84b6d460-2838-4682-c0d6-ef5b573ef28a"> + <const name="Normal" value="0"> + <desc>Value format is specific to the option and generally user friendly.</desc> + </const> + <const name="Hex" value="1"> + <desc>Value format is a series of hex bytes (<tt>09314f3200fe</tt>), + optionally colons as byte separators (<tt>9:31:4f:32::fe</tt>).</desc> + </const> + </enum> + + <enum + name="DHCPConfigScope" + uuid="469c42e4-b9ec-43f2-bdcb-9e9d1eb434ae"> + <const name="Global" value="0"><desc><link to="IDHCPServer::globalConfig"/></desc></const> + <const name="Group" value="1"><desc><link to="IDHCPServer::groupConfigs"/></desc></const> + <const name="MachineNIC" value="2"><desc><link to="IDHCPServer::individualConfigs"/></desc></const> + <const name="MAC" value="3"><desc><link to="IDHCPServer::individualConfigs"/></desc></const> + </enum> + + <enum + name="DHCPGroupConditionType" + uuid="2cb9280f-ada2-4194-dee8-bfb8ad77119d" + > + <const name="MAC" value="0"><desc>MAC address</desc></const> + <const name="MACWildcard" value="1"><desc>MAC address wildcard pattern.</desc></const> + <const name="vendorClassID" value="2"><desc>Vendor class ID</desc></const> + <const name="vendorClassIDWildcard" value="3"><desc>Vendor class ID wildcard pattern.</desc></const> + <const name="userClassID" value="4"><desc>User class ID</desc></const> + <const name="userClassIDWildcard" value="5"><desc>User class ID wildcard pattern.</desc></const> + </enum> + + <interface + name="IDHCPServer" extends="$unknown" + uuid="cadef0a2-a1a9-4ac2-8e80-c049af69dac8" + wsmap="managed" + rest="managed" + reservedMethods="0" reservedAttributes="3" + > + <desc> + The IDHCPServer interface represents the VirtualBox DHCP server configuration. + + To enumerate all the DHCP servers on the host, use the + <link to="IVirtualBox::DHCPServers"/> attribute. + </desc> + <!-- We want to keep our "real" servers updated about configuration changes --> + <attribute name="eventSource" type="IEventSource" readonly="yes"/> + <attribute name="enabled" type="boolean"> + <desc> + specifies if the DHCP server is enabled + </desc> + </attribute> + + <attribute name="IPAddress" type="wstring" readonly="yes"> + <desc> + specifies server IP + </desc> + </attribute> + + <attribute name="networkMask" type="wstring" readonly="yes"> + <desc> + specifies server network mask + </desc> + </attribute> + + <attribute name="networkName" type="wstring" readonly="yes"> + <desc> + specifies internal network name the server is used for + </desc> + </attribute> + + <attribute name="lowerIP" type="wstring" readonly="yes"> + <desc> + specifies from IP address in server address range + </desc> + </attribute> + + <attribute name="upperIP" type="wstring" readonly="yes"> + <desc> + specifies to IP address in server address range + </desc> + </attribute> + + <attribute name="globalConfig" type="IDHCPGlobalConfig" readonly="yes"> + <desc>Global configuration that applies to all clients.</desc> + </attribute> + + <attribute name="groupConfigs" type="IDHCPGroupConfig" safearray="yes" readonly="yes"> + <desc>Configuration groups that applies to selected clients, selection is flexible.</desc> + </attribute> + + <attribute name="individualConfigs" type="IDHCPIndividualConfig" safearray="yes" readonly="yes"> + <desc>Individual NIC configurations either by MAC address or VM + NIC number.</desc> + </attribute> + + <!-- VM-slot settings + It's corresponds to dhcpd.conf entries, like: + + host ncd1 { hardware ethernet 0:c0:c3:11:90:23; } + + - in Main we can match (vm name, slot) to ethernet address + that why it's easy to configure dhcp server in such way, + then ask user to to enter valid name, + + - mac address might change because of adapter type (e1k <-> pcnet) or because + of import/export + + - it's easy to provide vm-name.rom in boot filename VM with network boot. + + XXX: do we need classic getOptionValueByMAC? + + XML: O-o-oh, this settings are per VM, so perhaps they should be stored in + VM configuration files. And we haven't got the attachment type for + NATNetwork. + --> + <method name="setConfiguration"> + <rest request="post" path="/dhcpservers/{serverid}/configuration/"/> + <desc> + configures the server + <result name="E_INVALIDARG"> + invalid configuration supplied + </result> + </desc> + <param name="IPAddress" type="wstring" dir="in"> + <desc> + server IP address + </desc> + </param> + <param name="networkMask" type="wstring" dir="in"> + <desc> + server network mask + </desc> + </param> + <param name="FromIPAddress" type="wstring" dir="in"> + <desc> + server From IP address for address range + </desc> + </param> + <param name="ToIPAddress" type="wstring" dir="in"> + <desc> + server To IP address for address range + </desc> + </param> + </method> + + <method name="start"> + <rest request="post" path="/dhcpservers/{serverid}/actions/"/> + <desc> + Starts DHCP server process. + <result name="E_FAIL"> + Failed to start the process. + </result> + </desc> + <param name="trunkName" type="wstring" dir="in"> + <desc> + Name of internal network trunk. + </desc> + </param> + <param name="trunkType" type="wstring" dir="in"> + <desc> + Type of internal network trunk. + </desc> + </param> + </method> + + <method name="stop"> + <rest request="post" path="/dhcpservers/{serverid}/actions/"/> + <desc> + Stops DHCP server process. + <result name="E_FAIL"> + Failed to stop the process. + </result> + </desc> + </method> + + <method name="restart"> + <rest request="post" path="/dhcpservers/{serverid}/actions/"/> + <desc> + Restart running DHCP server process. + <result name="E_FAIL"> + Failed to restart the process. + </result> + </desc> + </method> + + <method name="findLeaseByMAC"> + <desc> + Queries the persistent lease database by MAC address. + + This is handy if the host wants to connect to a server running inside + a VM on a host only network. + + <result name="VBOX_E_OBJECT_NOT_FOUND">If MAC address not in the database.</result> + <result name="VBOX_E_FILE_ERROR">If not able to read the lease database file.</result> + </desc> + <param name="mac" type="wstring" dir="in"> + <desc>The MAC address to look up.</desc> + </param> + <param name="type" type="long" dir="in"> + <desc>Reserved, MBZ.</desc> + </param> + <param name="address" type="wstring" dir="out"> + <desc>The assigned address.</desc> + </param> + <param name="state" type="wstring" dir="out"> + <desc>The lease state.</desc> + </param> + <param name="issued" type="long long" dir="out"> + <desc>Timestamp of when the lease was issued, in seconds since 1970-01-01 UTC.</desc> + </param> + <param name="expire" type="long long" dir="out"> + <desc>Timestamp of when the lease expires/expired, in seconds since 1970-01-01 UTC.</desc> + </param> + </method> + + <method name="getConfig"> + <rest request="get" path="/dhcpservers/{serverid}/configuration/"/> + <desc> + Gets or adds a configuration. + </desc> + <param name="scope" dir="in" type="DHCPConfigScope"> + <desc>The kind of configuration being sought or added.</desc> + </param> + <param name="name" dir="in" type="wstring"> + <desc> + Meaning depends on the @a scope: + - Ignored when the @a scope is <link to="DHCPConfigScope_Global"/>. + - A VM name or UUID for <link to="DHCPConfigScope_MachineNIC"/>. + - A MAC address for <link to="DHCPConfigScope_MAC"/>. + - A group name for <link to="DHCPConfigScope_Group"/>. + </desc> + </param> + <param name="slot" dir="in" type="unsigned long"> + <desc>The NIC slot when @a scope is set to <link to="DHCPConfigScope_MachineNIC"/>, + must be zero for all other scope values. + </desc> + </param> + <param name="mayAdd" dir="in" type="boolean"> + <desc> + Set to @c TRUE if the configuration should be added if not found. + If set to @c FALSE the method will fail with VBOX_E_OBJECT_NOT_FOUND. + </desc> + </param> + <param name="config" dir="return" type="IDHCPConfig"> + <desc>The requested configuration.</desc> + </param> + </method> + + <!-- @todo Add variant of queryLeaseByMac that goes by VM name and optionally slot. --> + <!-- @todo Add lease database attribute (readonly) --> + + </interface> + + <interface + name="IDHCPConfig" extends="$unknown" + uuid="00f4a8dc-0002-4b81-0077-1dcb004571ba" + wsmap="managed" + rest="managed" + reservedMethods="8" reservedAttributes="16" + > + <desc> + The DHCP server has several configuration levels: global, group and + individual MAC. This interface implements the settings common to + each level. + </desc> + + <attribute name="scope" type="DHCPConfigScope" readonly="yes"> + <desc> + Indicates the kind of config this is (mostly for IDHCPIndividualConfig). + </desc> + </attribute> + + <attribute name="minLeaseTime" type="unsigned long"> + <desc>The minimum lease time in seconds, ignored if zero.</desc> + </attribute> + <attribute name="defaultLeaseTime" type="unsigned long"> + <desc>The default lease time in seconds, ignored if zero.</desc> + </attribute> + <attribute name="maxLeaseTime" type="unsigned long"> + <desc>The maximum lease time in seconds, ignored if zero.</desc> + </attribute> + + <attribute name="forcedOptions" type="DHCPOption" safearray="yes"> + <desc>List of DHCP options which should be forced upon the clients in this + config scope when they are available, whether the clients asks for them + or not.</desc> + </attribute> + + <attribute name="suppressedOptions" type="DHCPOption" safearray="yes"> + <desc>List of DHCP options which should not be sent to the clients in + this config scope. This is intended for cases where one client or a + group of clients shouldn't see one or more (typically global) options.</desc> + </attribute> + + <method name="setOption"> + <desc> + Sets a DHCP option. + </desc> + <param name="option" dir="in" type="DHCPOption"> + <desc>The DHCP option.</desc> + </param> + <param name="encoding" dir="in" type="DHCPOptionEncoding"> + <desc>The value encoding.</desc> + </param> + <param name="value" dir="in" type="wstring"> + <desc>The DHCP option value. The exact format depends on the DHCP + @a option value and @a encoding, see see <link to="DHCPOption"/> + for the <link to="DHCPOptionEncoding_Normal"/> format. + </desc> + </param> + </method> + + <method name="removeOption"> + <desc>Removes the given DHCP option.</desc> + <param name="option" dir="in" type="DHCPOption"/> + </method> + + <method name="removeAllOptions"> + <desc> + Removes all the options. + + One exception here is the DhcpOpt_SubnetMask option in the global scope + that is linked to the <link to="IDHCPServer::networkMask"/> attribute + and therefore cannot be removed. + </desc> + </method> + + <method name="getOption"> + <desc>Gets the value of a single DHCP option.</desc> + <param name="option" dir="in" type="DHCPOption"> + <desc>The DHCP option being sought.</desc> + </param> + <param name="encoding" dir="out" type="DHCPOptionEncoding"> + <desc>The value encoding.</desc> + </param> + <param name="value" dir="return" type="wstring"> + <desc>The value of the requested DHCP option. The exact format depends on + the DHCP @a option value and the @a encoding, see <link to="DHCPOption"/> + for the <link to="DHCPOptionEncoding_Normal"/> format. + </desc> + </param> + </method> + + <method name="getAllOptions"> + <desc>Gets all DHCP options and their values</desc> + <param name="options" dir="out" type="DHCPOption" safearray="yes"> + <desc>Array containing the DHCP option numbers.</desc> + </param> + <param name="encodings" dir="out" type="DHCPOptionEncoding" safearray="yes"> + <desc>Array of value encodings that runs parallel to @a options.</desc> + </param> + <param name="values" dir="return" type="wstring" safearray="yes"> + <desc>Array of values that runs parallel to @a options and @a encodings. The + format depends on both of those. + </desc> + </param> + </method> + + <method name="remove"> + <desc> + Remove this group or individual configuration. + Will of course not work on global configurations. + </desc> + </method> + + </interface> + + <interface + name="IDHCPGlobalConfig" extends="IDHCPConfig" + uuid="46735de7-f4c4-4020-a185-0d2881bcfa8b" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="4" + > + <desc> + The global DHCP server configuration, see <link to="IDHCPServer::globalConfig"/>. + </desc> + + </interface> + + <interface + name="IDHCPGroupCondition" extends="$unknown" + uuid="5ca9e537-5a1d-43f1-6f27-6a0db298a9a8" + wsmap="managed" + rest="managed" + reservedMethods="3" reservedAttributes="3" + > + <attribute name="inclusive" type="boolean"> + <desc>Whether this is an inclusive or exclusive group membership condition</desc> + </attribute> + <attribute name="type" type="DHCPGroupConditionType"> + <desc>Defines how the <link to="IDHCPGroupCondition::value"/> is interpreted.</desc> + </attribute> + <attribute name="value" type="wstring"> + <desc>The condition value.</desc> + </attribute> + <method name="remove"> + <desc>Remove this condition from the group.</desc> + </method> + </interface> + + <interface + name="IDHCPGroupConfig" extends="IDHCPConfig" + uuid="537707f7-ebf9-4d5c-7aea-877bfc4256ba" + wsmap="managed" + rest="managed" + reservedMethods="8" reservedAttributes="8" + > + <desc> + A configuration that applies to a group of NICs. + </desc> + + <attribute name="name" type="wstring"> + <desc>The group name.</desc> + </attribute> + + <attribute name="conditions" type="IDHCPGroupCondition" safearray="yes" readonly="yes"> + <desc> + Group membership conditions. + + Add new conditions by calling <link to="IDHCPGroupConfig::addCondition"/> + and use <link to="IDHCPGroupCondition::remove"/> to remove. + </desc> + </attribute> + + <method name="addCondition"> + <desc>Adds a new condition.</desc> + <param name="inclusive" dir="in" type="boolean"/> + <param name="type" dir="in" type="DHCPGroupConditionType"/> + <param name="value" dir="in" type="wstring"/> + <param name="condition" dir="return" type="IDHCPGroupCondition"/> + </method> + + <method name="removeAllConditions"> + <desc>Removes all conditions.</desc> + </method> + + </interface> + + <interface + name="IDHCPIndividualConfig" extends="IDHCPConfig" + uuid="c40c2b86-73a5-46cc-8227-93fe57d006a6" + wsmap="managed" + rest="managed" + reservedMethods="8" reservedAttributes="8" + > + <desc> + Configuration for a single NIC, either given directly by MAC address or by + VM + adaptor slot number. + </desc> + + <attribute name="MACAddress" type="wstring" readonly="yes"> + <desc> + The MAC address. If a <link to="DHCPConfigScope_MachineNIC"/> config, this + will be queried via the VM ID. + </desc> + </attribute> + + <attribute name="machineId" type="uuid" mod="string" readonly="yes"> + <desc> + The virtual machine ID if a <link to="DHCPConfigScope_MachineNIC"/> config, + null UUID for <link to="DHCPConfigScope_MAC"/>. + </desc> + </attribute> + + <attribute name="slot" type="unsigned long" readonly="yes"> + <desc>The NIC slot number of the VM if a <link to="DHCPConfigScope_MachineNIC"/> config.</desc> + </attribute> + + <attribute name="fixedAddress" type="wstring"> + <desc>Fixed IPv4 address assignment, dynamic if empty.</desc> + </attribute> + + </interface> + + <interface + name="IVirtualBox" extends="$unknown" + uuid="7682d5eb-f00e-44f1-8ca2-99d08b1cd607" + wsmap="managed" + rest="managed" + wrap-gen-hook="yes" + reservedMethods="8" reservedAttributes="12" + > + <desc> + 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 + <link to="IVirtualBox::machines"/> attribute. + + Error information handling is a bit special with IVirtualBox: creating + an instance will always succeed. The return of the actual error + code/information is postponed to any attribute or method call. The + reason for this is that COM likes to mutilate the error code and lose + the detailed error information returned by instance creation. + </desc> + + <attribute name="version" type="wstring" readonly="yes"> + <desc> + A string representing the version number of the product. The + format is 3 integer numbers divided by dots (e.g. 1.0.1). The + last number represents the build number and will frequently change. + + This may be followed by a _ALPHA[0-9]*, _BETA[0-9]* or _RC[0-9]* tag + in prerelease builds. Non-Oracle builds may (/shall) also have a + publisher tag, at the end. The publisher tag starts with an underscore + just like the prerelease build type tag. + </desc> + </attribute> + + <attribute name="versionNormalized" type="wstring" readonly="yes"> + <desc> + A string representing the version number of the product, + without the publisher information (but still with other tags). + See <link to="#version" />. + </desc> + </attribute> + + <attribute name="revision" type="unsigned long" readonly="yes"> + <desc> + The internal build revision number of the product. + </desc> + </attribute> + + <attribute name="packageType" type="wstring" readonly="yes"> + <desc> + 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. + </desc> + </attribute> + + <attribute name="APIVersion" type="wstring" readonly="yes"> + <desc> + A string representing the VirtualBox API version number. The format is + 2 integer numbers divided by an underscore (e.g. 1_0). After the + first public release of packages with a particular API version the + API will not be changed in an incompatible way. Note that this + guarantee does not apply to development builds, and also there is no + guarantee that this version is identical to the first two integer + numbers of the package version. + </desc> + </attribute> + + <attribute name="APIRevision" type="long long" readonly="yes"> + <desc> + This is mainly intended for the VBox Validation Kit so it can fluently + deal with incompatible API changes and new functionality during + development (i.e. on trunk). + + The high 7 bits (62:56) is the major version number, the next 8 bits + (55:48) are the minor version number, the next 8 bits (47:40) are the + build number, and the rest (39:0) is the API revision number. + + The API revision number is manually increased on trunk when making + incompatible changes that the validation kit or others needs to be able + to detect and cope with dynamically. It can also be used to indicate + the presence of new features on both trunk and branches. + </desc> + </attribute> + + <attribute name="homeFolder" type="wstring" readonly="yes"> + <desc> + Full path to the directory where the global settings file, + <tt>VirtualBox.xml</tt>, is stored. + + In this version of VirtualBox, the value of this property is + always <tt><user_dir>/.VirtualBox</tt> (where + <tt><user_dir></tt> 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). + </desc> + </attribute> + + <attribute name="settingsFilePath" type="wstring" readonly="yes"> + <desc> + Full name of the global settings file. + The value of this property corresponds to the value of + <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>. + </desc> + </attribute> + + <attribute name="host" type="IHost" readonly="yes"> + <desc>Associated host object.</desc> + </attribute> + + <attribute name="systemProperties" type="ISystemProperties" readonly="yes"> + <desc>Associated system information object.</desc> + </attribute> + + <attribute name="machines" type="IMachine" readonly="yes" safearray="yes"> + <desc> + Array of machine objects registered within this VirtualBox instance. + </desc> + </attribute> + + <attribute name="machineGroups" type="wstring" readonly="yes" safearray="yes"> + <desc> + Array of all machine group names which are used by the machines which + are accessible. Each group is only listed once, however they are listed + in no particular order and there is no guarantee that there are no gaps + in the group hierarchy (i.e. <tt>"/"</tt>, <tt>"/group/subgroup"</tt> + is a valid result). + </desc> + </attribute> + + <attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes"> + <desc> + 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 + <link to="IMedium::children"/>. + </desc> + </attribute> + + <attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes"> + <desc> + Array of CD/DVD image objects currently in use by this VirtualBox instance. + </desc> + </attribute> + + <attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes"> + <desc> + Array of floppy image objects currently in use by this VirtualBox instance. + </desc> + </attribute> + + <attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/> + + <attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/> + + <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes"> + <desc> + Collection of global shared folders. Global shared folders are + available to all virtual machines. + + New shared folders are added to the collection using + <link to="#createSharedFolder"/>. Existing shared folders can be + removed using <link to="#removeSharedFolder"/>. + + <note> + In the current version of the product, global shared folders are not + implemented and therefore this collection is always empty. + </note> + </desc> + </attribute> + + <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes"> + <desc> + Associated performance collector object. + </desc> + </attribute> + + <attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes"> + <desc> + DHCP servers. + </desc> + </attribute> + <!-- Array of NAT networks --> + <attribute name="NATNetworks" type="INATNetwork" safearray="yes" readonly="yes"/> + + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for VirtualBox events. + </desc> + </attribute> + + <attribute name="extensionPackManager" type="IExtPackManager" readonly="yes"> + <desc> + The extension pack manager. + </desc> + </attribute> + + + <attribute name="internalNetworks" type="wstring" safearray="yes" readonly="yes"> + <desc> + Names of all internal networks. + </desc> + </attribute> + + <attribute name="hostOnlyNetworks" type="IHostOnlyNetwork" safearray="yes" readonly="yes"> + <desc> + Names of all host-only networks. + </desc> + </attribute> + + <attribute name="genericNetworkDrivers" type="wstring" safearray="yes" readonly="yes"> + <desc> + Names of all generic network drivers. + </desc> + </attribute> + + <attribute name="cloudNetworks" type="ICloudNetwork" safearray="yes" readonly="yes"> + <desc> + Names of all configured cloud networks. + </desc> + </attribute> + + <attribute name="cloudProviderManager" type="ICloudProviderManager" readonly="yes"> + <desc> + The cloud provider manager (singleton). + </desc> + </attribute> + + <method name="composeMachineFilename"> + <rest request="get" path="/server/methods/"/> + <desc> + Returns a recommended full path of the settings file name for a new virtual + machine. + + This API serves two purposes: + + <ul> + <li>It gets called by <link to="#createMachine" /> if @c null or + empty string (which is recommended) is specified for the + @a settingsFile argument there, which means that API should use + a recommended default file name.</li> + + <li>It can be called manually by a client software before creating a machine, + e.g. if that client wants to pre-create the machine directory to create + virtual hard disks in that directory together with the new machine + settings file. In that case, the file name should be stripped from the + full settings file path returned by this function to obtain the + machine directory.</li> + </ul> + + See <link to="IMachine::name"/> and <link to="#createMachine"/> for more + details about the machine name. + + @a groupName defines which additional subdirectory levels should be + included. It must be either a valid group name or @c null or empty + string which designates that the machine will not be related to a + machine group. + + If @a baseFolder is a @c null or empty string (which is recommended), the + default machine settings folder + (see <link to="ISystemProperties::defaultMachineFolder" />) will be used as + a base folder for the created machine, resulting in a file name like + "/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder + will be used. + + This method does not access the host disks. In particular, it does not check + for whether a machine with this name already exists. + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Suggested machine name.</desc> + </param> + <param name="group" type="wstring" dir="in"> + <desc>Machine group name for the new machine or machine group. It is + used to determine the right subdirectory.</desc> + </param> + <param name="createFlags" type="wstring" dir="in"> + <desc>Machine creation flags, see <link to="#createMachine" /> (optional).</desc> + </param> + <param name="baseFolder" type="wstring" dir="in"> + <desc>Base machine folder (optional).</desc> + </param> + <param name="file" type="wstring" dir="return"> + <desc>Fully qualified path where the machine would be created.</desc> + </param> + </method> + + <method name="createMachine"> + <rest name="create" request="post" path="/vms/"/> + <desc> + Creates a new virtual machine by creating a machine settings file at + the given location. + + VirtualBox machine settings files use a custom XML dialect. Starting + with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced, + and machine files can be created at arbitrary locations. + + However, it is recommended that machines are created in the default + machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see + <link to="ISystemProperties::defaultMachineFolder" />). If you specify + @c null or empty string (which is recommended) for the @a settingsFile + argument, <link to="#composeMachineFilename" /> is called automatically + to have such a recommended name composed based on the machine name + given in the @a name argument and the primary group. + + If the resulting settings file already exists, this method will fail, + unless the forceOverwrite flag is set. + + The new machine is created unregistered, with the initial configuration + set according to the specified guest OS type. A typical sequence of + actions to create a new virtual machine is as follows: + + <ol> + <li> + Call this method to have a new machine created. The returned machine + object will be "mutable" allowing to change any machine property. + </li> + + <li> + Configure the machine using the appropriate attributes and methods. + </li> + + <li> + Call <link to="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. + </li> + + <li> + Call <link to="#registerMachine" /> to add the machine to the list + of machines known to VirtualBox. + </li> + </ol> + + The specified guest OS type identifier must match an ID of one of known + guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/> + array. + + <note> + <link to="IMachine::settingsModified"/> will return + @c false for the created machine, until any of machine settings + are changed. + </note> + + <note> + There is no way to change the name of the settings file or + subfolder of the created machine directly. + </note> + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + @a osTypeId is invalid. + </result> + <result name="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. + </result> + <result name="E_INVALIDARG"> + @a name is empty or @c null. + </result> + </desc> + + <param name="settingsFile" type="wstring" dir="in"> + <desc>Fully qualified path where the settings file should be created, + empty string or @c null for a default folder and file based on the + @a name argument and the primary group. + (see <link to="#composeMachineFilename" />).</desc> + </param> + <param name="name" type="wstring" dir="in"> + <desc>Machine name.</desc> + </param> + <param name="groups" type="wstring" safearray="yes" dir="in"> + <desc>Array of group names. @c null or an empty array have the same + meaning as an array with just the empty string or <tt>"/"</tt>, i.e. + create a machine without group association.</desc> + </param> + <param name="osTypeId" type="wstring" dir="in"> + <desc>Guest OS Type ID.</desc> + </param> + <param name="flags" type="wstring" dir="in"> + <desc> + Additional property parameters, passed as a comma-separated list of + "name=value" type entries. The following ones are recognized: + <tt>forceOverwrite=1</tt> to overwrite an existing machine settings + file, <tt>UUID=<uuid></tt> to specify a machine UUID and + <tt>directoryIncludesUUID=1</tt> to switch to a special VM directory + naming scheme which should not be used unless necessary. + </desc> + </param> + <param name="cipher" type="wstring" dir="in"> + <desc> + The cipher. It should be empty if encryption is not required. + </desc> + </param> + <param name="passwordId" type="wstring" dir="in"> + <desc> + The password id. It should be empty if encryption is not required. + </desc> + </param> + <param name="password" type="wstring" dir="in"> + <desc> + The password. It should be empty if encryption is not required. + </desc> + </param> + <param name="machine" type="IMachine" dir="return"> + <desc>Created machine object.</desc> + </param> + </method> + + <method name="openMachine"> + <rest name="open" request="post" path="/vms/{vmid}/actions/"/> + <desc> + Opens a virtual machine from the existing settings file. + The opened machine remains unregistered until you call + <link to="#registerMachine"/>. + + The specified settings file name must be fully qualified. + The file must exist and be a valid machine XML settings file + whose contents will be used to construct the machine object. + + <note> + If the VM is encrypted and password is incorrect + the method returns success allowing you to register the + encrypted machine but it remains in inaccessible state. You + can check <link to="IMachine::accessible"/> and + <link to="IMachine::accessError"/> properties to determine the + real machine state. + </note> + + <note> + <link to="IMachine::settingsModified"/> will return + @c false for the opened machine, until any of machine settings + are changed. + </note> + + <result name="VBOX_E_FILE_ERROR"> + Settings file name invalid, not found or sharing violation. + </result> + </desc> + <param name="settingsFile" type="wstring" dir="in"> + <desc> + Name of the machine settings file. + </desc> + </param> + <param name="password" type="wstring" dir="in"> + <desc> + The password. If the machine is not encrypted the parameter is + ignored. + </desc> + </param> + <param name="machine" type="IMachine" dir="return"> + <desc>Opened machine object.</desc> + </param> + </method> + + <method name="registerMachine"> + <rest name="register" request="post" path="/vms/{vmid}/actions/"/> + <desc> + + Registers the machine previously created using + <link to="#createMachine"/> or opened using + <link to="#openMachine"/> within this VirtualBox installation. After + successful method invocation, the + <link to="IMachineRegisteredEvent"/> event is fired. + + <note> + This method implicitly calls <link to="IMachine::saveSettings"/> + to save all current machine settings before registering it. + </note> + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + No matching virtual machine found. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Virtual machine was not created within this VirtualBox instance. + </result> + + </desc> + <param name="machine" type="IMachine" dir="in"/> + </method> + + <method name="findMachine" const="yes"> + <rest name="find" request="get" path="/vms/{vmid}/"/> + <desc> + Attempts to find a virtual machine given its name or UUID. + + <note>Inaccessible machines cannot be found by name, only by UUID, because their name + cannot safely be determined.</note> + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Could not find registered machine matching @a nameOrId. + </result> + + </desc> + <param name="nameOrId" type="wstring" dir="in"> + <desc>What to search for. This can either be the UUID or the name of a virtual machine.</desc> + </param> + <param name="machine" type="IMachine" dir="return"> + <desc>Machine object, if found.</desc> + </param> + </method> + + <method name="getMachinesByGroups"> + <rest request="get" path="/server/methods/"/> + <desc> + Gets all machine references which are in one of the specified groups. + </desc> + <param name="groups" type="wstring" dir="in" safearray="yes"> + <desc>What groups to match. The usual group list rules apply, i.e. + passing an empty list will match VMs in the toplevel group, likewise + the empty string.</desc> + </param> + <param name="machines" type="IMachine" dir="return" safearray="yes"> + <desc>All machines which matched.</desc> + </param> + </method> + + <method name="getMachineStates"> + <rest request="get" path="/server/methods/"/> + <desc> + Gets the state of several machines in a single operation. + </desc> + <param name="machines" type="IMachine" dir="in" safearray="yes"> + <desc>Array with the machine references.</desc> + </param> + <param name="states" type="MachineState" dir="return" safearray="yes"> + <desc>Machine states, corresponding to the machines.</desc> + </param> + </method> + + <method name="createAppliance"> + <rest name="create" request="post" path="/appliances/"/> + <desc> + 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 <link to="IAppliance" /> for details. + </desc> + <param name="appliance" type="IAppliance" dir="return"> + <desc>New appliance.</desc> + </param> + </method> + + <method name="createUnattendedInstaller"> + <rest request="post" path="/server/methods/"/> + <desc> + Creates a new <link to="IUnattended"/> guest installation object. This can be used to + analyze an installation ISO to create and configure a new machine for it to be installed + on. It can also be used to (re)install an existing machine. + </desc> + <param name="unattended" type="IUnattended" dir="return"> + <desc>New unattended object.</desc> + </param> + </method> + + <method name="createMedium"> + <rest name="create" request="post" path="/mediums/"/> + <desc> + Creates a new base medium object that will use the given storage + format and location for medium data. + + The actual storage unit is not created by this method. In order to + do it, and before you are able to attach the created medium to + virtual machines, you must call one of the following methods to + allocate a format-specific storage unit at the specified location: + <ul> + <li><link to="IMedium::createBaseStorage"/></li> + <li><link to="IMedium::createDiffStorage"/></li> + </ul> + + Some medium attributes, such as <link to="IMedium::id"/>, may + remain uninitialized until the medium storage unit is successfully + created by one of the above methods. + + Depending on the given device type, the file at the storage location + must be in one of the media formats understood by VirtualBox: + + <ul> + <li>With a "HardDisk" device type, the file must be a hard disk image + in one of the formats supported by VirtualBox (see + <link to="ISystemProperties::mediumFormats" />). + After the storage unit is successfully created and this method succeeds, + if the medium is a base medium, it + will be added to the <link to="#hardDisks"/> array attribute. </li> + <li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image. + After this method succeeds, the medium will be added to the + <link to="#DVDImages"/> array attribute.</li> + <li>With a "Floppy" device type, the file must be an RAW floppy image. + After this method succeeds, the medium will be added to the + <link to="#floppyImages"/> array attribute.</li> + </ul> + + The list of all storage formats supported by this VirtualBox + installation can be obtained using + <link to="ISystemProperties::mediumFormats"/>. If the @a format + attribute is empty or @c null then the default storage format + specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will + be used for disks r creating a storage unit of the medium. + + Note that the format of the location string is storage format specific. + See <link to="IMedium::location"/> and IMedium for more details. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + @a format identifier is invalid. See + <link to="ISystemProperties::mediumFormats"/>. + </result> + <result name="VBOX_E_FILE_ERROR"> + @a location is a not valid file name (for file-based formats only). + </result> + </desc> + <param name="format" type="wstring" dir="in"> + <desc> + Identifier of the storage format to use for the new medium. + </desc> + </param> + <param name="location" type="wstring" dir="in"> + <desc> + Location of the storage unit for the new medium. + </desc> + </param> + <param name="accessMode" type="AccessMode" dir="in"> + <desc>Whether to open the image in read/write or read-only mode. For + a "DVD" device type, this is ignored and read-only mode is always assumed.</desc> + </param> + <param name="aDeviceTypeType" type="DeviceType" dir="in"> + <desc> + Must be one of "HardDisk", "DVD" or "Floppy". + </desc> + </param> + <param name="medium" type="IMedium" dir="return"> + <desc>Created medium object.</desc> + </param> + </method> + + <method name="openMedium"> + <rest request="post" path="/server/methods/"/> + <desc> + Finds existing media or opens a medium from an existing storage location. + + Once a medium has been opened, it can be passed to other VirtualBox + methods, in particular to <link to="IMachine::attachDevice" />. + + Depending on the given device type, the file at the storage location + must be in one of the media formats understood by VirtualBox: + + <ul> + <li>With a "HardDisk" device type, the file must be a hard disk image + in one of the formats supported by VirtualBox (see + <link to="ISystemProperties::mediumFormats" />). + After this method succeeds, if the medium is a base medium, it + will be added to the <link to="#hardDisks"/> array attribute. </li> + <li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image. + After this method succeeds, the medium will be added to the + <link to="#DVDImages"/> array attribute.</li> + <li>With a "Floppy" device type, the file must be an RAW floppy image. + After this method succeeds, the medium will be added to the + <link to="#floppyImages"/> array attribute.</li> + </ul> + + After having been opened, the medium can be re-found by this method + and can be attached to virtual machines. See <link to="IMedium" /> for + more details. + + The UUID of the newly opened medium will either be retrieved from the + storage location, if the format supports it (e.g. for hard disk images), + or a new UUID will be randomly generated (e.g. for ISO and RAW files). + If for some reason you need to change the medium's UUID, use + <link to="IMedium::setIds" />. + + If a differencing hard disk medium is to be opened by this method, the + operation will succeed only if its parent medium and all ancestors, + if any, are already known to this VirtualBox installation (for example, + were opened by this method before). + + This method attempts to guess the storage format of the specified medium + by reading medium data at the specified location. + + If @a accessMode is ReadWrite (which it should be for hard disks and floppies), + the image is opened for read/write access and must have according permissions, + as VirtualBox may actually write status information into the disk's metadata + sections. + + Note that write access is required for all typical hard disk usage in VirtualBox, + since VirtualBox may need to write metadata such as a UUID into the image. + The only exception is opening a source image temporarily for copying and + cloning (see <link to="IMedium::cloneTo" /> when the image will be closed + again soon. + + The format of the location string is storage format specific. See + <link to="IMedium::location"/> and IMedium for more details. + + <result name="VBOX_E_FILE_ERROR"> + Invalid medium storage file location or could not find the medium + at the specified location. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Could not get medium storage format. + </result> + <result name="E_INVALIDARG"> + Invalid medium storage format. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Medium has already been added to a media registry. + </result> + </desc> + <param name="location" type="wstring" dir="in"> + <desc> + Location of the storage unit that contains medium data in one of + the supported storage formats. + </desc> + </param> + <param name="deviceType" type="DeviceType" dir="in"> + <desc> + Must be one of "HardDisk", "DVD" or "Floppy". + </desc> + </param> + <param name="accessMode" type="AccessMode" dir="in"> + <desc>Whether to open the image in read/write or read-only mode. For + a "DVD" device type, this is ignored and read-only mode is always assumed.</desc> + </param> + <param name="forceNewUuid" type="boolean" dir="in"> + <desc>Allows the caller to request a completely new medium UUID for + the image which is to be opened. Useful if one intends to open an exact + copy of a previously opened image, as this would normally fail due to + the duplicate UUID.</desc> + </param> + <param name="medium" type="IMedium" dir="return"> + <desc>Opened medium object.</desc> + </param> + </method> + + <method name="getGuestOSType"> + <rest request="get" path="/server/methods/"/> + <desc> + 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 + <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a + particular virtual machine can be read or set using the + <link to="IMachine::OSTypeId"/> attribute. + + The <link to="IVirtualBox::guestOSTypes"/> collection contains all + available guest OS type objects. Each object has an + <link to="IGuestOSType::id"/> attribute which contains an identifier of + the guest OS this object describes. + + While this function returns an error for unknown guest OS types, they + can be still used without serious problems (if one accepts the fact + that there is no default VM config information). + + <result name="E_INVALIDARG"> + @a id is not a valid Guest OS type. + </result> + + </desc> + <param name="id" type="wstring" dir="in"> + <desc>Guest OS type ID string.</desc> + </param> + <param name="type" type="IGuestOSType" dir="return"> + <desc>Guest OS type object.</desc> + </param> + </method> + + <method name="createSharedFolder"> + <rest name="create" request="post" path="/sharedfolders/"/> + <desc> + 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 + <link to="ISharedFolder"/> to read more about logical names. + <note> + In the current implementation, this operation is not + implemented. + </note> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Unique logical name of the shared folder.</desc> + </param> + <param name="hostPath" type="wstring" dir="in"> + <desc>Full path to the shared folder in the host file system.</desc> + </param> + <param name="writable" type="boolean" dir="in"> + <desc>Whether the share is writable or readonly</desc> + </param> + <param name="automount" type="boolean" dir="in"> + <desc>Whether the share gets automatically mounted by the guest + or not.</desc> + </param> + <param name="autoMountPoint" type="wstring" dir="in"> + <desc>Where the guest should automatically mount the folder, if possible. + For Windows and OS/2 guests this should be a drive letter, while other + guests it should be a absolute directory. + </desc> + </param> + </method> + + <method name="removeSharedFolder"> + <rest name="remove" request="delete" path="/sharedfolders/"/> + <desc> + Removes the global shared folder with the given name previously + created by <link to="#createSharedFolder"/> from the collection of + shared folders and stops sharing it. + <note> + In the current implementation, this operation is not + implemented. + </note> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Logical name of the shared folder to remove.</desc> + </param> + </method> + + <method name="getExtraDataKeys"> + <rest request="get" path="/server/methods/"/> + <desc> + Returns an array representing the global extra data keys which currently + have values defined. + </desc> + <param name="keys" type="wstring" dir="return" safearray="yes"> + <desc>Array of extra data keys.</desc> + </param> + </method> + + <method name="getExtraData"> + <rest request="get" path="/server/methods/"/> + <desc> + Returns associated global extra data. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + <result name="VBOX_E_FILE_ERROR"> + Settings file not accessible. + </result> + <result name="VBOX_E_XML_ERROR"> + Could not parse the settings file. + </result> + + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the data key to get.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc>Value of the requested data key.</desc> + </param> + </method> + + <method name="setExtraData"> + <rest request="put" path="/server/methods/"/> + <desc> + Sets associated global extra data. + + If you pass @c null or an empty string as a key @a value, the given + @a key will be deleted. + + <note> + Key must contain printable (non-control) UTF-8 characters only. + </note> + <note> + Before performing the actual data change, this method will ask all + registered event listeners using the + <link to="IExtraDataCanChangeEvent"/> + notification for a permission. If one of the listeners refuses the + new value, the change will not be performed. + </note> + <note> + On success, the + <link to="IExtraDataChangedEvent"/> notification + is called to inform all registered listeners about a successful data + change. + </note> + + <result name="VBOX_E_FILE_ERROR"> + Settings file not accessible. + </result> + <result name="VBOX_E_XML_ERROR"> + Could not parse the settings file. + </result> + <result name="E_ACCESSDENIED"> + Modification request refused. + </result> + <result name="E_INVALIDARG"> + Key contains invalid characters. + </result> + + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the data key to set.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc>Value to assign to the key.</desc> + </param> + </method> + + <method name="setSettingsSecret"> + <desc> + Unlocks the secret data by passing the unlock password to the + server. The server will cache the password for that machine. + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is not mutable. + </result> + + </desc> + <param name="password" type="wstring" dir="in"> + <desc> + The cipher key. + </desc> + </param> + </method> + + <!--method name="createDHCPServerForInterface"> + <desc> + Creates a DHCP server settings to be used for the given interface + <result name="E_INVALIDARG"> + Host network interface @a name already exists. + </result> + </desc> + <param name="interface" type="IHostNetworkInterface" dir="in"> + <desc>Network Interface</desc> + </param> + <param name="server" type="IDHCPServer" dir="out"> + <desc>DHCP server settings</desc> + </param> + </method--> + + <method name="createDHCPServer"> + <rest name="create" request="post" path="/dhcpservers/"/> + <desc> + Creates a DHCP server settings to be used for the given internal network name + <result name="E_INVALIDARG"> + Host network interface @a name already exists. + </result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>server name</desc> + </param> + <param name="server" type="IDHCPServer" dir="return"> + <desc>DHCP server settings</desc> + </param> + </method> + + <method name="findDHCPServerByNetworkName"> + <rest name="find" request="get" path="/dhcpservers/"/> + <desc> + Searches a DHCP server settings to be used for the given internal network name + <result name="E_INVALIDARG"> + Host network interface @a name already exists. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>server name</desc> + </param> + <param name="server" type="IDHCPServer" dir="return"> + <desc>DHCP server settings</desc> + </param> + </method> + + <!--method name="findDHCPServerForInterface"> + <desc> + Searches a DHCP server settings to be used for the given interface + <result name="E_INVALIDARG"> + Host network interface @a name already exists. + </result> + </desc> + <param name="interface" type="IHostNetworkInterface" dir="in"> + <desc>Network Interface</desc> + </param> + <param name="server" type="IDHCPServer" dir="out"> + <desc>DHCP server settings</desc> + </param> + </method--> + + <method name="removeDHCPServer"> + <rest name="remove" request="delete" path="/dhcpservers/"/> + <desc> + Removes the DHCP server settings + <result name="E_INVALIDARG"> + Host network interface @a name already exists. + </result> + </desc> + <param name="server" type="IDHCPServer" dir="in"> + <desc>DHCP server settings to be removed</desc> + </param> + </method> + + <!-- bunch of methods to create NAT --> + <method name="createNATNetwork"> + <!-- Here we create a record in NAT network array with name + and gateway/network parameters this information should + be enough for VBoxNetNAT and VBoxNetDHCP for + servicing the guests. + --> + <rest name="create" request="post" path="/natnetworks/"/> + <param name="networkName" type="wstring" dir="in"/> + <param name="network" type="INATNetwork" dir="return"/> + </method> + + <!-- + Returns the NATNetwork by name, e.g. for adding port forward rule or deletion. + --> + <method name="findNATNetworkByName"> + <rest name="find" request="get" path="/natnetworks/"/> + <param name="networkName" type="wstring" dir="in"/> + <param name="network" type="INATNetwork" dir="return"/> + </method> + <!-- + Deletes given NAT network. + --> + <method name="removeNATNetwork"> + <rest name="remove" request="delete" path="/natnetworks/"/> + <param name="network" type="INATNetwork" dir="in"/> + </method> + + <!-- bunch of methods to manage host-only networks --> + <!-- + Here we create a record in cloud network array with specified name. + --> + <method name="createHostOnlyNetwork"> + <rest name="create" request="post" path="/hostonlynetworks/"/> + <param name="networkName" type="wstring" dir="in"/> + <param name="network" type="IHostOnlyNetwork" dir="return"/> + </method> + + <!-- + Returns the host-only network by name. + --> + <method name="findHostOnlyNetworkByName"> + <param name="networkName" type="wstring" dir="in"/> + <param name="network" type="IHostOnlyNetwork" dir="return"/> + </method> + <!-- + Returns the host-only network by id. + --> + <method name="findHostOnlyNetworkById"> + <rest name="find" request="get" path="/hostonlynetworks/"/> + <desc> + Searches through all host networks for one with + the given GUID. + <note> + The method returns an error if the given GUID does not + correspond to any host network. + </note> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc>GUID of the host-only network to search for.</desc> + </param> + <param name="network" type="IHostOnlyNetwork" dir="return"> + <desc>Found host-only network object.</desc> + </param> + </method> + <!-- + Deletes given host-only network. + --> + <method name="removeHostOnlyNetwork"> + <rest name="remove" request="delete" path="/hostonlynetworks/"/> + <param name="network" type="IHostOnlyNetwork" dir="in"/> + </method> + + <!-- bunch of methods to manage cloud networks --> + <method name="createCloudNetwork"> + <!-- Here we create a record in cloud network array with specified name. + --> + <rest name="create" request="post" path="/cloudnetworks/"/> + <param name="networkName" type="wstring" dir="in"/> + <param name="network" type="ICloudNetwork" dir="return"/> + </method> + + <!-- + Returns the cloud network by name. + --> + <method name="findCloudNetworkByName"> + <rest name="find" request="get" path="/cloudnetworks/"/> + <param name="networkName" type="wstring" dir="in"/> + <param name="network" type="ICloudNetwork" dir="return"/> + </method> + <!-- + Deletes given cloud network. + --> + <method name="removeCloudNetwork"> + <rest name="remove" request="delete" path="/cloudnetworks/"/> + <param name="network" type="ICloudNetwork" dir="in"/> + </method> + + <method name="checkFirmwarePresent"> + <rest request="get" path="/server/methods/"/> + <desc> + 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. + </desc> + <param name="firmwareType" type="FirmwareType" dir="in"> + <desc> + Type of firmware to check. + </desc> + </param> + <param name="version" type="wstring" dir="in"> + <desc>Expected version number, usually empty string (presently ignored).</desc> + </param> + + <param name="url" type="wstring" dir="out"> + <desc> + Suggested URL to download this firmware from. + </desc> + </param> + + <param name="file" type="wstring" dir="out"> + <desc> + Filename of firmware, only valid if result == TRUE. + </desc> + </param> + + <param name="result" type="boolean" dir="return"> + <desc>If firmware of this type and version is available.</desc> + </param> + </method> + + <method name="findProgressById"> + <rest name="find" request="get" path="/progresses/{progressid}/"/> + <desc> + Searches through all progress objects known to VBoxSVC for an + instance with the given GUID. + <note> + The method returns an error if the given GUID does not + correspond to any currently known progress object. + </note> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc>GUID of the progress object to search for.</desc> + </param> + <param name="progressObject" type="IProgress" dir="return"> + <desc>Found progress object.</desc> + </param> + </method> + + </interface> + + <!-- + // IVFSExplorer + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="VFSType" + uuid="813999ba-b949-48a8-9230-aadc6285e2f2" + > + <desc> + Virtual file systems supported by VFSExplorer. + </desc> + + <const name="File" value="1" /> + <const name="Cloud" value="2" /> + <const name="S3" value="3" /> + <const name="WebDav" value="4" /> + </enum> + + <interface + name="IVFSExplorer" extends="$unknown" + uuid="fb220201-2fd3-47e2-a5dc-2c2431d833cc" + wsmap="managed" + > + <desc> + The VFSExplorer interface unifies access to different file system + types. This includes local file systems as well remote file systems like + S3. For a list of supported types see <link to="VFSType" />. + An instance of this is returned by <link to="IAppliance::createVFSExplorer" />. + </desc> + + <attribute name="path" type="wstring" readonly="yes"> + <desc>Returns the current path in the virtual file system.</desc> + </attribute> + + <attribute name="type" type="VFSType" readonly="yes"> + <desc>Returns the file system type which is currently in use.</desc> + </attribute> + + <method name="update"> + <desc>Updates the internal list of files/directories from the + current directory level. Use <link to="#entryList" /> to get the full list + after a call to this method.</desc> + + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="cd"> + <desc>Change the current directory level.</desc> + + <param name="dir" type="wstring" dir="in"> + <desc>The name of the directory to go in.</desc> + </param> + + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="cdUp"> + <desc>Go one directory upwards from the current directory level.</desc> + + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="entryList"> + <desc>Returns a list of files/directories after a call to <link + to="#update" />. The user is responsible for keeping this internal + list up do date.</desc> + + <param name="names" type="wstring" safearray="yes" dir="out"> + <desc>The list of names for the entries.</desc> + </param> + + <param name="types" type="unsigned long" safearray="yes" dir="out"> + <desc>The list of types for the entries. <link to="FsObjType"/></desc> + </param> + + <param name="sizes" type="long long" safearray="yes" dir="out"> + <desc>The list of sizes (in bytes) for the entries.</desc> + </param> + + <param name="modes" type="unsigned long" safearray="yes" dir="out"> + <desc>The list of file modes (in octal form) for the entries.</desc> + </param> + </method> + + <method name="exists"> + <desc>Checks if the given file list exists in the current directory + level.</desc> + + <param name="names" type="wstring" safearray="yes" dir="in"> + <desc>The names to check.</desc> + </param> + + <param name="exists" type="wstring" safearray="yes" dir="return"> + <desc>The names which exist.</desc> + </param> + </method> + + <method name="remove"> + <desc>Deletes the given files in the current directory level.</desc> + + <param name="names" type="wstring" safearray="yes" dir="in"> + <desc>The names to remove.</desc> + </param> + + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + </interface> + + <enum + name="ImportOptions" + uuid="0a981523-3b20-4004-8ee3-dfd322202ace" + > + + <desc> + Import options, used with <link to="IAppliance::importMachines" />. + </desc> + + <const name="KeepAllMACs" value="1"> + <desc>Don't generate new MAC addresses of the attached network adapters.</desc> + </const> + <const name="KeepNATMACs" value="2"> + <desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc> + </const> + + <const name="ImportToVDI" value="3"> + <desc>Import all disks to VDI format</desc> + </const> + + </enum> + + <enum + name="ExportOptions" + uuid="8f45eb08-fd34-41ee-af95-a880bdee5554" + > + + <desc> + Export options, used with <link to="IAppliance::write" />. + </desc> + + <const name="CreateManifest" value="1"> + <desc>Write the optional manifest file (.mf) which is used for integrity + checks prior import.</desc> + </const> + <const name="ExportDVDImages" value="2"> + <desc>Export DVD images. Default is not to export them as it is rarely + needed for typical VMs.</desc> + </const> + <const name="StripAllMACs" value="3"> + <desc>Do not export any MAC address information. Default is to keep them + to avoid losing information which can cause trouble after import, at the + price of risking duplicate MAC addresses, if the import options are used + to keep them.</desc> + </const> + <const name="StripAllNonNATMACs" value="4"> + <desc>Do not export any MAC address information, except for adapters + using NAT. Default is to keep them to avoid losing information which can + cause trouble after import, at the price of risking duplicate MAC + addresses, if the import options are used to keep them.</desc> + </const> + + </enum> + + <enum + name="CertificateVersion" + uuid="9e232a99-51d0-4dbd-96a0-ffac4bc3e2a8" + > + <desc> + X.509 certificate version numbers. + </desc> + <const name="V1" value="1"/> + <const name="V2" value="2"/> + <const name="V3" value="3"/> + <const name="Unknown" value="99"/> + </enum> + + <!-- + // ICertificate + ///////////////////////////////////////////////////////////////////////// + --> + <interface + name="ICertificate" extends="$unknown" + uuid="392f1de4-80e1-4a8a-93a1-67c5f92a838a" + wsmap="managed" + rest="managed" + reservedAttributes="12" reservedMethods="2" + > + <desc> + X.509 certificate details. + </desc> + <attribute name="versionNumber" type="CertificateVersion" readonly="yes"> + <desc>Certificate version number.</desc> + </attribute> + <attribute name="serialNumber" type="wstring" readonly="yes"> + <desc>Certificate serial number.</desc> + </attribute> + <attribute name="signatureAlgorithmOID" type="wstring" readonly="yes"> + <desc>The dotted OID of the signature algorithm.</desc> + </attribute> + <attribute name="signatureAlgorithmName" type="wstring" readonly="yes"> + <desc>The signature algorithm name if known (if known).</desc> + </attribute> + <attribute name="issuerName" type="wstring" readonly="yes" safearray="yes"> + <desc>Issuer name. Each member of the array is on the format + COMPONENT=NAME, e.g. "C=DE", "ST=Example", "L=For Instance", "O=Beispiel GmbH", + "CN=beispiel.example.org". + </desc> + </attribute> + <attribute name="subjectName" type="wstring" readonly="yes" safearray="yes"> + <desc>Subject name. Same format as issuerName.</desc> + </attribute> + <attribute name="friendlyName" type="wstring" readonly="yes"> + <desc>Friendly subject name or similar.</desc> + </attribute> + <attribute name="validityPeriodNotBefore" type="wstring" readonly="yes"> + <desc>Certificate not valid before ISO timestamp.</desc> + </attribute> + <attribute name="validityPeriodNotAfter" type="wstring" readonly="yes"> + <desc>Certificate not valid after ISO timestamp.</desc> + </attribute> + <attribute name="publicKeyAlgorithmOID" type="wstring" readonly="yes"> + <desc>The dotted OID of the public key algorithm.</desc> + </attribute> + <attribute name="publicKeyAlgorithm" type="wstring" readonly="yes"> + <desc>The public key algorithm name (if known).</desc> + </attribute> + <attribute name="subjectPublicKey" type="octet" safearray="yes" readonly="yes"> + <desc>The raw public key bytes.</desc> + </attribute> + <attribute name="issuerUniqueIdentifier" type="wstring" readonly="yes"> + <desc>Unique identifier of the issuer (empty string if not present).</desc> + </attribute> + <attribute name="subjectUniqueIdentifier" type="wstring" readonly="yes"> + <desc>Unique identifier of this certificate (empty string if not present).</desc> + </attribute> + <attribute name="certificateAuthority" type="boolean" readonly="yes"> + <desc>Whether this certificate is a certificate authority. Will return E_FAIL + if this attribute is not present. + </desc> + </attribute> + <attribute name="keyUsage" type="unsigned long" readonly="yes"> + <desc>Key usage mask. Will return 0 if not present.</desc> + </attribute> + <attribute name="extendedKeyUsage" type="wstring" safearray="yes" readonly="yes"> + <desc>Array of dotted extended key usage OIDs. Empty array if not present.</desc> + </attribute> + <attribute name="rawCertData" type="octet" safearray="yes" readonly="yes"> + <desc>The raw certificate bytes.</desc> + </attribute> + <attribute name="selfSigned" type="boolean" readonly="yes"> + <desc>Set if self signed certificate.</desc> + </attribute> + + <!-- The following is subject to the parent object views. --> + <attribute name="trusted" type="boolean" readonly="yes"> + <desc>Set if the certificate is trusted (by the parent object).</desc> + </attribute> + <attribute name="expired" type="boolean" readonly="yes"> <!-- isCurrentlyExpired is clearer than isCurrentlyValid. --> + <desc>Set if the certificate has expired (relevant to the parent object)/</desc> + </attribute> + + <method name="isCurrentlyExpired"> + <desc> + Tests if the certificate has expired at the present time according to + the X.509 validity of the certificate.</desc> + <param name="result" type="boolean" dir="return" /> + </method> + + <method name="queryInfo"> + <desc>Way to extend the interface.</desc> + <param name="what" type="long" dir="in"/> + <param name="result" type="wstring" dir="return" /> + </method> + + </interface> + + + <!-- + // IAppliance + ///////////////////////////////////////////////////////////////////////// + --> + <interface + name="IAppliance" extends="$unknown" + uuid="86a98347-7619-41aa-aece-b21ac5c1a7e6" + wsmap="managed" + rest="managed" + reservedMethods="7" reservedAttributes="8" + > + <desc> + Represents a platform-independent appliance in OVF format. An instance of this is returned + by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export + virtual machines within an appliance with VirtualBox. + + The OVF standard suggests two different physical file formats: + + <ol> + <li>If the appliance is distributed as a set of files, there must be at least one XML descriptor + file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If + this descriptor file references other files such as disk images, as OVF appliances typically + do, those additional files must be in the same directory as the descriptor file. + </li> + + <li>If the appliance is distributed as a single file, it must be in TAR format and have the + <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor + files and optionally other files. + + At this time, VirtualBox does not not yet support the packed (TAR) variant; support will + be added with a later version. + </li> + </ol> + + <b>Importing</b> an OVF appliance into VirtualBox as instances of + <link to="IMachine" /> involves the following sequence of API calls: + + <ol> + <li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object. + </li> + + <li>On the new object, call <link to="#read" /> with the full path of the OVF file you + would like to import. So long as this file is syntactically valid, this will succeed + and fill the appliance object with the parsed data from the OVF file. + </li> + + <li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the + contents of the IAppliance attributes accordingly. These can be inspected by a + VirtualBox front-end such as the GUI, and the suggestions can be displayed to the + user. In particular, the <link to="#virtualSystemDescriptions" /> array contains + instances of <link to="IVirtualSystemDescription" /> which represent the virtual + systems (machines) in the OVF, which in turn describe the virtual hardware prescribed + by the OVF (network and hardware adapters, virtual disk images, memory size and so on). + The GUI can then give the user the option to confirm and/or change these suggestions. + </li> + + <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each + virtual system (machine) to override the suggestions made by the <link to="#interpret" /> routine. + </li> + + <li>Finally, call <link to="#importMachines" /> to create virtual machines in + VirtualBox as instances of <link to="IMachine" /> that match the information in the + virtual system descriptions. After this call succeeded, the UUIDs of the machines created + can be found in the <link to="#machines" /> array attribute. + </li> + </ol> + + <b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps: + + <ol> + <li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create + an empty IAppliance object. + </li> + + <li>For each machine you would like to export, call <link to="IMachine::exportTo" /> + with the IAppliance object you just created. Each such call creates one instance of + <link to="IVirtualSystemDescription" /> inside the appliance. + </li> + + <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each + virtual system (machine) to override the suggestions made by the <link to="IMachine::exportTo"/> routine. + </li> + + <li>Finally, call <link to="#write" /> with a path specification to have the OVF + file written.</li> + </ol> + + </desc> + + <attribute name="path" type="wstring" readonly="yes"> + <desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or + the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or + <link to="#write" /> (for export). + This attribute is empty until one of these methods has been called. + </desc> + </attribute> + + <attribute name="disks" type="wstring" readonly="yes" safearray="yes"> + <desc> + Array of virtual disk definitions. One such description exists for each + disk definition in the OVF; each string array item represents one such piece of + disk information, with the information fields separated by tab (\\t) characters. + + The caller should be prepared for additional fields being appended to + this string in future versions of VirtualBox and therefore check for + the number of tabs in the strings returned. + + In the current version, the following eight fields are returned per string + in the array: + + <ol> + <li>Disk ID (unique string identifier given to disk)</li> + + <li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li> + + <li>Populated size (optional unsigned integer indicating the current size of the + disk; can be approximate; -1 if unspecified)</li> + + <li>Format (string identifying the disk format, typically + "http://www.vmware.com/specifications/vmdk.html#sparse")</li> + + <li>Reference (where to find the disk image, typically a file name; if empty, + then the disk should be created on import)</li> + + <li>Image size (optional unsigned integer indicating the size of the image, + which need not necessarily be the same as the values specified above, since + the image may be compressed or sparse; -1 if not specified)</li> + + <li>Chunk size (optional unsigned integer if the image is split into chunks; + presently unsupported and always -1)</li> + + <li>Compression (optional string equaling "gzip" if the image is gzip-compressed)</li> + </ol> + </desc> + </attribute> + + <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes"> + <desc> Array of virtual system descriptions. One such description is created + for each virtual system (machine) found in the OVF. + This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::exportTo" /> + (for export) has been called. + </desc> + </attribute> + + <attribute name="machines" type="wstring" readonly="yes" safearray="yes"> + <desc> + Contains the UUIDs of the machines created from the information in this appliances. This is only + relevant for the import case, and will only contain data after a call to <link to="#importMachines" /> + succeeded. + </desc> + </attribute> + + <attribute name="certificate" type="ICertificate" readonly="yes"> + <desc> + The X.509 signing certificate, if the imported OVF was signed, @c null + if not signed. This is available after calling <link to="#read"/>. + </desc> + </attribute> + + <method name="read"> + <rest request="post" path="/appliances/{applianceid}/actions/"/> + <desc> + Reads an OVF file into the appliance object. + + This method succeeds if the OVF is syntactically valid and, by itself, without errors. The + mere fact that this method returns successfully does not mean that VirtualBox supports all + features requested by the appliance; this can only be examined after a call to <link to="#interpret" />. + </desc> + <param name="file" type="wstring" dir="in"> + <desc> + Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending + on whether the appliance is distributed as a set of files or as a single file, respectively). + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="interpret"> + <rest request="post" path="/appliances/{applianceid}/actions/"/> + <desc> + Interprets the OVF data that was read when the appliance was constructed. After + calling this method, one can inspect the + <link to="#virtualSystemDescriptions" /> array attribute, which will then contain + one <link to="IVirtualSystemDescription" /> for each virtual machine found in + the appliance. + + Calling this method is the second step of importing an appliance into VirtualBox; + see <link to="IAppliance" /> for an overview. + + After calling this method, one should call <link to="#getWarnings" /> to find out + if problems were encountered during the processing which might later lead to + errors. + </desc> + </method> + + <method name="importMachines"> + <rest request="post" path="/appliances/{applianceid}/actions/"/> + <desc> + Imports the appliance into VirtualBox by creating instances of <link to="IMachine" /> + and other interfaces that match the information contained in the appliance as + closely as possible, as represented by the import instructions in the + <link to="#virtualSystemDescriptions" /> array. + + Calling this method is the final step of importing an appliance into VirtualBox; + see <link to="IAppliance" /> for an overview. + + Since importing the appliance will most probably involve copying and converting + disk images, which can take a long time, this method operates asynchronously and + returns an IProgress object to allow the caller to monitor the progress. + + After the import succeeded, the UUIDs of the IMachine instances created can be + retrieved from the <link to="#machines" /> array attribute. + </desc> + + <param name="options" type="ImportOptions" dir="in" safearray="yes"> + <desc>Options for the importing operation.</desc> + </param> + + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="createVFSExplorer"> + <desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc> + + <param name="URI" type="wstring" dir="in"> + <desc>The URI describing the file system to use.</desc> + </param> + + <param name="explorer" type="IVFSExplorer" dir="return"> + <desc></desc> + </param> + </method> + + <method name="write"> + <rest request="post" path="/appliances/{applianceid}/actions/"/> + <desc> + Writes the contents of the appliance exports into a new OVF file. + + Calling this method is the final step of exporting an appliance from VirtualBox; + see <link to="IAppliance" /> for an overview. + + Since exporting the appliance will most probably involve copying and converting + disk images, which can take a long time, this method operates asynchronously and + returns an IProgress object to allow the caller to monitor the progress. + </desc> + <param name="format" type="wstring" dir="in"> + <desc> + Output format, as a string. Currently supported formats are "ovf-0.9", "ovf-1.0", + "ovf-2.0" and "opc-1.0"; future versions of VirtualBox may support additional formats. + The "opc-1.0" format is for creating tarballs for the Oracle Public Cloud. + </desc> + </param> + <param name="options" type="ExportOptions" dir="in" safearray="yes"> + <desc>Options for the exporting operation.</desc> + </param> + <param name="path" type="wstring" dir="in"> + <desc> + Name of appliance file to create. There are certain restrictions with regard + to the file name suffix. If the format parameter is "opc-1.0" a <tt>.tar.gz</tt> + suffix is required. Otherwise the suffix must either be <tt>.ovf</tt> or + <tt>.ova</tt>, depending on whether the appliance is distributed as a set of + files or as a single file, respectively. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="getWarnings"> + <rest request="get" path="/appliances/{applianceid}/configuration/"/> + <desc>Returns textual warnings which occurred during execution of <link to="#interpret" />.</desc> + + <param name="warnings" type="wstring" dir="return" safearray="yes"> + <desc></desc> + </param> + </method> + + <method name="getPasswordIds"> + <rest request="get" path="/appliances/{applianceid}/configuration/"/> + <desc> + Returns a list of password identifiers which must be supplied to import or export + encrypted virtual machines. + </desc> + + <param name="identifiers" type="wstring" dir="return" safearray="yes"> + <desc>The list of password identifiers required for export on success.</desc> + </param> + </method> + + <method name="getMediumIdsForPasswordId"> + <rest request="get" path="/appliances/{applianceid}/configuration/"/> + <desc> + Returns a list of medium identifiers which use the given password identifier. + </desc> + + <param name="passwordId" type="wstring" dir="in"> + <desc>The password identifier to get the medium identifiers for.</desc> + </param> + <param name="identifiers" type="uuid" mod="string" dir="return" safearray="yes"> + <desc>The list of medium identifiers returned on success.</desc> + </param> + </method> + + <method name="addPasswords"> + <rest request="post" path="/appliances/{applianceid}/configuration/"/> + <desc> + Adds a list of passwords required to import or export encrypted virtual + machines. + </desc> + + <param name="identifiers" type="wstring" dir="in" safearray="yes"> + <desc>List of identifiers.</desc> + </param> + + <param name="passwords" type="wstring" dir="in" safearray="yes"> + <desc>List of matching passwords.</desc> + </param> + </method> + + <method name="createVirtualSystemDescriptions"> + <rest request="post" path="/appliances/{applianceid}/configuration/"/> + <desc>Creates a number of <link to="IVirtualSystemDescription" /> objects and store them + in the <link to="#virtualSystemDescriptions" /> array. + </desc> + + <param name="requested" type="unsigned long" dir="in"> + <desc>Requested number of new virtual system description objects</desc> + </param> + + <param name="created" type="unsigned long" dir="return"> + <desc>Actually created number of virtual system description objects</desc> + </param> + </method> + + </interface> + + <enum + name="VirtualSystemDescriptionType" + uuid="247f8b6f-1042-4c15-8910-3e3c64395eb7" + > + <desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of + a configuration value.</desc> + + <const name="Ignore" value="1" /> + <const name="OS" value="2" /> + <const name="Name" value="3" /> + <const name="Product" value="4" /> + <const name="Vendor" value="5" /> + <const name="Version" value="6" /> + <const name="ProductUrl" value="7" /> + <const name="VendorUrl" value="8" /> + <const name="Description" value="9" /> + <const name="License" value="10" /> + <const name="Miscellaneous" value="11" /> + <const name="CPU" value="12" /> + <const name="Memory" value="13" /> + <const name="HardDiskControllerIDE" value="14" /> + <const name="HardDiskControllerSATA" value="15" /> + <const name="HardDiskControllerSCSI" value="16" /> + <const name="HardDiskControllerSAS" value="17" /> + <const name="HardDiskImage" value="18" /> + <const name="Floppy" value="19" /> + <const name="CDROM" value="20" /> + <const name="NetworkAdapter" value="21" /> + <const name="USBController" value="22" /> + <const name="SoundCard" value="23" /> + <const name="SettingsFile" value="24"> + <desc>Optional, may be unset by the API caller. If this is changed by the + API caller it defines the absolute path of the VM settings file and + therefore also the VM folder with highest priority.</desc> + </const> + <const name="BaseFolder" value="25"> + <desc>Optional, may be unset by the API caller. If set (and + <link to="VirtualSystemDescriptionType_SettingsFile"/> is not changed), + defines the VM base folder (taking the primary group into account if + also set).</desc> + </const> + <const name="PrimaryGroup" value="26"> + <desc>Optional, empty by default and may be unset by the API caller. + Defines the primary group of the VM after import. May influence the + selection of the VM folder. Additional groups may be configured later + using <link to="IMachine::groups"/>, after importing.</desc> + </const> + <const name="CloudInstanceShape" value="27" /> + <const name="CloudDomain" value="28" /> + <const name="CloudBootDiskSize" value="29" /> + <const name="CloudBucket" value="30" /> + <const name="CloudOCIVCN" value="31" /> + <const name="CloudPublicIP" value="32" /> + <const name="CloudProfileName" value="33" /> + <const name="CloudOCISubnet" value="34" /> + <const name="CloudKeepObject" value="35" /> + <const name="CloudLaunchInstance" value="36" /> + <const name="CloudInstanceId" value="37" /> + <const name="CloudImageId" value="38" /> + <const name="CloudInstanceState" value="39" /> + <const name="CloudImageState" value="40" /> + <const name="CloudInstanceDisplayName" value="41" /> + <const name="CloudImageDisplayName" value="42" /> + <const name="CloudOCILaunchMode" value="43" /> + <const name="CloudPrivateIP" value="44" /> + <const name="CloudBootVolumeId" value="45" /> + <const name="CloudOCIVCNCompartment" value="46" /> + <const name="CloudOCISubnetCompartment" value="47" /> + <const name="CloudPublicSSHKey" value="48" /> + <const name="BootingFirmware" value="49" /> + <const name="CloudInitScriptPath" value="50" /> + <const name="CloudCompartmentId" value="51" /> + <const name="CloudShapeCpus" value="52" /> + <const name="CloudShapeMemory" value="53" /> + <const name="HardDiskControllerVirtioSCSI" value="60" /> + </enum> + + <enum + name="VirtualSystemDescriptionValueType" + uuid="56d9403f-3425-4118-9919-36f2a9b8c77c" + > + <desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value + type to fetch.</desc> + + <const name="Reference" value="1" /> + <const name="Original" value="2" /> + <const name="Auto" value="3" /> + <const name="ExtraConfig" value="4" /> + + </enum> + + <interface + name="IVirtualSystemDescription" extends="$unknown" + uuid="01510f40-c196-4d26-b8db-4c8c389f1f82" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="4" + > + + <desc> + Represents one virtual system (machine) in an appliance. This interface is used in + the <link to="IAppliance::virtualSystemDescriptions" /> array. After + <link to="IAppliance::interpret" /> has been called, that array contains information + about how the virtual systems described in the OVF should best be imported into + VirtualBox virtual machines. See <link to="IAppliance" /> for the steps required to + import an OVF into VirtualBox. + </desc> + + <attribute name="count" type="unsigned long" readonly="yes"> + <desc>Return the number of virtual system description entries.</desc> + </attribute> + + <method name="getDescription"> + <desc>Returns information about the virtual system as arrays of instruction items. In each array, the + items with the same indices correspond and jointly represent an import instruction for VirtualBox. + + The list below identifies the value sets that are possible depending on the + <link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case, + the array item with the same index in @a OVFValues[] will contain the original value as contained + in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[] + will contain a suggested value to be used for VirtualBox. Depending on the description type, + the @a aExtraConfigValues[] array item may also be used. + + <ul> + <li> + "OS": the guest operating system type. There must be exactly one such array item on import. The + corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox. + This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding + item in @a OVFValues[] will contain a numerical value that described the operating system in the OVF. + </li> + <li> + "Name": the name to give to the new virtual machine. There can be at most one such array item; + if none is present on import, then an automatic name will be created from the operating system + type. The corresponding item im @a OVFValues[] will contain the suggested virtual machine name + from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox + <link to="IMachine" /> name that does not exist yet. + </li> + <li> + "Description": an arbitrary description. + </li> + <li> + "License": the EULA section from the OVF, if present. It is the responsibility of the calling + code to display such a license for agreement; the Main API does not enforce any such policy. + </li> + <li> + Miscellaneous: reserved for future use. + </li> + <li> + "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored. + </li> + <li> + "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none + is present on import, then VirtualBox will set a meaningful default based on the operating system + type. + </li> + <li> + "HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items. + An optional value in @a OVFValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify + the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox + writes into the OVF. + The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk" + type can use to specify which hard disk controller a virtual disk should be connected to. + Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave" + in traditional terminology, whereas the IDE storage controller that VirtualBox supports in + its virtual machines supports four channels (primary master, primary slave, secondary master, + secondary slave) and thus maps to two IDE controllers in the OVF sense. + </li> + <li> + "HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This + has no value in @a OVFValues[] or @a aVBoxValues[]. + The matching item in the @a aRefs[] array will be used as with IDE controllers (see above). + </li> + <li> + "HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item. + The items in @a OVFValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or + "LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller + whereas VirtualBox considers it a class of storage controllers of its own; see + <link to="StorageControllerType" />). + The matching item in the @a aRefs[] array will be used as with IDE controllers (see above). + </li> + <li> + "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an + arbitrary number of these items, one for each virtual disk image that accompanies the OVF. + + The array item in @a OVFValues[] will contain the file specification from the OVF file (without + a path since the image file should be in the same location as the OVF file itself), whereas the + item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the + hard disk image. This means that on import the image will be copied and converted from the + "ovf" location to the "vbox" location; on export, this will be handled the other way round. + + The matching item in the @a aExtraConfigValues[] array must contain a string of the following + format: "controller=<index>;channel=<c>" + In this string, <index> must be an integer specifying the hard disk controller to connect + the image to. That number must be the index of an array item with one of the hard disk controller + types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE). + In addition, <c> must specify the channel to use on that controller. For IDE controllers, + this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions + before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but + no longer exported. For SATA and SCSI controllers, the channel can range from 0-29. + </li> + <li> + "CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same + attachment information as with "HardDiskImage" items. + </li> + <li> + "CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same + attachment information as with "HardDiskImage" items. + </li> + <li> + "NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware + for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string + of the "type=<X>" format, where <X> must be either "NAT" or "Bridged". + </li> + <li> + "USBController": a USB controller. There can be at most one such item. If, and only if, such an + item is present, USB support will be enabled for the new virtual machine. + </li> + <li> + "SoundCard": a sound card. There can be at most one such item. If and only if such an item is + present, sound support will be enabled for the new virtual machine. Note that the virtual + machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which + may be different from the virtual soundcard expected by the appliance. + </li> + </ul> + + </desc> + + <param name="types" type="VirtualSystemDescriptionType" dir="out" safearray="yes"> + <desc></desc> + </param> + + <param name="refs" type="wstring" dir="out" safearray="yes"> + <desc></desc> + </param> + + <param name="OVFValues" type="wstring" dir="out" safearray="yes"> + <desc></desc> + </param> + + <param name="VBoxValues" type="wstring" dir="out" safearray="yes"> + <desc></desc> + </param> + + <param name="extraConfigValues" type="wstring" dir="out" safearray="yes"> + <desc></desc> + </param> + + </method> + + <method name="getDescriptionByType"> + <desc>This is the same as <link to="#getDescription" /> except that you can specify which types + should be returned.</desc> + + <param name="type" type="VirtualSystemDescriptionType" dir="in"> + <desc></desc> + </param> + + <param name="types" type="VirtualSystemDescriptionType" dir="out" safearray="yes"> + <desc></desc> + </param> + + <param name="refs" type="wstring" dir="out" safearray="yes"> + <desc></desc> + </param> + + <param name="OVFValues" type="wstring" dir="out" safearray="yes"> + <desc></desc> + </param> + + <param name="VBoxValues" type="wstring" dir="out" safearray="yes"> + <desc></desc> + </param> + + <param name="extraConfigValues" type="wstring" dir="out" safearray="yes"> + <desc></desc> + </param> + + </method> + + <method name="removeDescriptionByType"> + <desc>Delete all records which are equal to the passed type from the list</desc> + + <param name="type" type="VirtualSystemDescriptionType" dir="in"> + <desc></desc> + </param> + </method> + + <method name="getValuesByType"> + <desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which + value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible + values.</desc> + + <param name="type" type="VirtualSystemDescriptionType" dir="in"> + <desc></desc> + </param> + + <param name="which" type="VirtualSystemDescriptionValueType" dir="in"> + <desc></desc> + </param> + + <param name="values" type="wstring" dir="return" safearray="yes"> + <desc></desc> + </param> + + </method> + + <method name="setFinalValues"> + <desc> + This method allows the appliance's user to change the configuration for the virtual + system descriptions. For each array item returned from <link to="#getDescription" />, + you must pass in one boolean value and one configuration value. + + Each item in the boolean array determines whether the particular configuration item + should be enabled. + You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA, + HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController + and SoundCard. + + For the "vbox" and "extra configuration" values, if you pass in the same arrays + as returned in the aVBoxValues and aExtraConfigValues arrays from <link to="#getDescription"/>, + the configuration remains unchanged. Please see the documentation for <link to="#getDescription"/> + for valid configuration values for the individual array item types. If the + corresponding item in the aEnabled array is @c false, the configuration value is ignored. + </desc> + + <param name="enabled" type="boolean" dir="in" safearray="yes"> + <desc></desc> + </param> + + <param name="VBoxValues" type="wstring" dir="in" safearray="yes"> + <desc></desc> + </param> + + <param name="extraConfigValues" type="wstring" dir="in" safearray="yes"> + <desc></desc> + </param> + </method> + + <method name="addDescription"> + <desc> + This method adds an additional description entry to the stack of already + available descriptions for this virtual system. This is handy for writing + values which aren't directly supported by VirtualBox. One example would + be the License type of <link to="VirtualSystemDescriptionType" />. + </desc> + + <param name="type" type="VirtualSystemDescriptionType" dir="in"> + <desc></desc> + </param> + + <param name="VBoxValue" type="wstring" dir="in"> + <desc></desc> + </param> + + <param name="extraConfigValue" type="wstring" dir="in"> + <desc></desc> + </param> + </method> + + </interface> + + <!-- + // IUnattended + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IUnattended" extends="$unknown" + uuid="6f89464f-7773-436a-a4df-592e4e537fa0" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="16" + > + + <desc> + The IUnattended interface represents the pipeline for preparing + the Guest OS for fully automated install. + + The typical workflow is: + <ol> + <li>Call <link to="IVirtualBox::createUnattendedInstaller"/> to create the object</li> + <li>Set <link to="IUnattended::isoPath"/> and call <link to="IUnattended::detectIsoOS"/></li> + <li>Create, configure and register a machine according to <link to="IUnattended::detectedOSTypeId"/> + and the other detectedOS* attributes.</li> + <li>Set <link to="IUnattended::machine"/> to the new IMachine instance.</li> + <li>Set the other IUnattended attributes as desired.</li> + <li>Call <link to="IUnattended::prepare"/> for the object to check the + attribute values and create an internal installer instance.</li> + <li>Call <link to="IUnattended::constructMedia"/> to create additional + media files (ISO/floppy) needed.</li> + <li>Call <link to="IUnattended::reconfigureVM"/> to reconfigure the VM + with the installation ISO, additional media files and whatnot </li> + <li>Optionally call <link to="IUnattended::done"/> to destroy the internal + installer and allow restarting from the second step.</li> + </ol> + + Note! Step two is currently not implemented. + </desc> + + <attribute name="isoPath" type="wstring"> + <desc> + Guest operating system ISO image + </desc> + </attribute> + + <attribute name="machine" type="IMachine"> + <desc> + The associated machine object. + + This must be set before <link to="IUnattended::prepare"/> is called. + The VM must be registered. + </desc> + </attribute> + + <attribute name="user" type="wstring"> + <desc> + Assign an user login name. + </desc> + </attribute> + + <attribute name="password" type="wstring"> + <desc> + Assign a password to the user. The password is the same for both + normal user and for Administrator / 'root' accounts. + </desc> + </attribute> + + <attribute name="fullUserName" type="wstring"> + <desc> + The full name of the user. This is optional and defaults to + <link to="IUnattended::user"/>. Please note that not all guests picks + up this attribute. + </desc> + </attribute> + + <attribute name="productKey" type="wstring"> + <desc> + Any key which is used as authorization of access to install genuine OS + </desc> + </attribute> + + <attribute name="additionsIsoPath" type="wstring"> + <desc> + Guest Additions ISO image path. This defaults to + <link to="ISystemProperties::defaultAdditionsISO"/> when the Unattended + object is instantiated. + + This property is ignored when <link to="IUnattended::installGuestAdditions"/> is false. + </desc> + </attribute> + + <attribute name="installGuestAdditions" type="boolean"> + <desc> + Indicates whether the Guest Additions should be installed or not. + + Setting this to false does not affect additions shipped with the linux + distribution, only the installation of additions pointed to by + <link to="IUnattended::additionsIsoPath"/>. + </desc> + </attribute> + + <attribute name="validationKitIsoPath" type="wstring"> + <desc> + VirtualBox ValidationKit ISO image path. This is used when + <link to="IUnattended::installTestExecService"/> is set to true. + </desc> + </attribute> + + <attribute name="installTestExecService" type="boolean"> + <desc> + Indicates whether the test execution service (TXS) from the VBox + ValidationKit should be installed. + + The TXS binary will be taken from the ISO indicated by + <link to="IUnattended::validationKitIsoPath"/>. + </desc> + </attribute> + + <attribute name="timeZone" type="wstring"> + <desc> + The guest time zone specifier. + + This is unfortunately guest OS specific. + + Windows XP and earlier takes the index number from this table: + https://support.microsoft.com/en-gb/help/973627/microsoft-time-zone-index-values + + Windows Vista and later takes the time zone string from this table: + https://technet.microsoft.com/en-us/library/cc749073(v=ws.10).aspx + + Linux usually takes the TZ string from this table: + https://en.wikipedia.org/wiki/List_of_tz_database_time_zones + + The default is currently UTC/GMT, but this may change to be same as + the host later. + + TODO: Investigate automatic mapping between linux and the two windows + time zone formats. + TODO: Take default from host (this requires mapping). + </desc> + </attribute> + + <attribute name="locale" type="wstring"> + <desc> + The 5 letter locale identifier, no codesets or such. + + The format is two lower case language letters (ISO 639-1), underscore ('_'), + and two upper case country letters (ISO 3166-1 alpha-2). For instance + 'en_US', 'de_DE', or 'ny_NO'. + + The default is taken from the host if possible, with 'en_US' as fallback. + </desc> + </attribute> + + <attribute name="language" type="wstring"> + <desc> + This is more or less a Windows specific setting for choosing the UI language + setting of the installer. + + The value should be from the list available via <link to="IUnattended::detectedOSLanguages"/>. + The typical format is {language-code}-{COUNTRY} but windows may also use + {16-bit code}:{32-bit code} or insert another component between the language + and country codes. We consider the format guest OS specific. + + Note that it is crucial that this is correctly specified for Windows + installations. If an unsupported value is given the installer will ask + for an installation language and wait for user input. Best to leave it + to the default value. + + The default is the first one from <link to="IUnattended::detectedOSLanguages"/>. + </desc> + </attribute> + + <attribute name="country" type="wstring"> + <desc> + The 2 upper case letter country identifier, ISO 3166-1 alpha-2. + + This is used for mirrors and such. + + The default is taken from the host when possible, falling back on + <link to="IUnattended::locale"/>. + </desc> + </attribute> + + <attribute name="proxy" type="wstring"> + <desc> + Proxy incantation to pass on to the guest OS installer. + + This is important to get right if the guest OS installer is of the type + that goes online to fetch the packages (e.g. debian-*-netinst.iso) or + to fetch updates during the install process. + + Format: [schema=]schema://[login[:password]@]proxy[:port][;...] + + The default is taken from the host proxy configuration (once implemented). + </desc> + </attribute> + + <attribute name="packageSelectionAdjustments" type="wstring"> + <desc> + Guest OS specific package selection adjustments. + + This is a semicolon separated list of keywords, and later maybe guest OS + package specifiers. Currently the 'minimal' is the only recognized value, + and this only works with a selection of linux installers. + </desc> + </attribute> + + <attribute name="hostname" type="wstring"> + <desc> + The fully qualified guest hostname. + + This defaults to machine-name + ".myguest.virtualbox.org", though it may + change to the host domain name later. + </desc> + </attribute> + + <attribute name="auxiliaryBasePath" type="wstring"> + <desc> + The path + basename for auxiliary files generated by the unattended + installation. This defaults to the VM folder + Unattended + VM UUID. + + The files which gets generated depends on the OS being installed. When + installing Windows there is currently only a auxiliaryBasePath + "floppy.img" + being created. But for linux, a "cdrom.viso" and one or more configuration + files are generate generated. + </desc> + </attribute> + + <attribute name="imageIndex" type="unsigned long"> + <desc> + The image index on installation CD/DVD used to install. This index should be + one of the indices of <link to="IUnattended::detectedImageIndices"/>. + + Changing this after ISO detection may cause + <link to="IUnattended::detectedOSTypeId"/>, <link to="IUnattended::detectedOSVersion"/>, + <link to="IUnattended::detectedOSFlavor"/>, <link to="IUnattended::detectedOSLanguages"/>, + and <link to="IUnattended::detectedOSHints"/> to be updated with values + specific to the selected image. + + Used only with Windows installation CD/DVD: + https://technet.microsoft.com/en-us/library/cc766022%28v=ws.10%29.aspx + </desc> + </attribute> + + <attribute name="scriptTemplatePath" type="wstring"> + <desc> + The unattended installation script template file. + + The template default is based on the guest OS type and is determined by the + internal installer when when <link to="IUnattended::prepare"/> is invoked. + Most users will want the defaults. + + After <link to="IUnattended::prepare"/> is called, it can be read to see + which file is being used. + </desc> + </attribute> + + <attribute name="postInstallScriptTemplatePath" type="wstring"> + <desc> + The post installation (shell/batch) script template file. + + The template default is based on the guest OS type and is determined by the + internal installer when when <link to="IUnattended::prepare"/> is invoked. + Most users will want the defaults. + + After <link to="IUnattended::prepare"/> is called, it can be read to see + which file is being used. + </desc> + </attribute> + + <attribute name="postInstallCommand" type="wstring"> + <desc> + Custom post installation command. + + Exactly what is expected as input here depends on the guest OS installer + and the post installation script template (see + <link to="IUnattended::postInstallScriptTemplatePath"/>). + Most users will not need to set this attribute. + </desc> + </attribute> + + <attribute name="extraInstallKernelParameters" type="wstring"> + <desc> + Extra kernel arguments passed to the install kernel of some guests. + + This is currently only picked up by linux guests. The exact parameters + are specific to the guest OS being installed of course. + + After <link to="IUnattended::prepare"/> is called, it can be read to see + which parameters are being used. + </desc> + </attribute> + + <attribute name="detectedOSTypeId" type="wstring" readonly="yes"> + <desc> + The detected OS type ID (<link to="IGuestOSType::id"/>). + + Set by <link to="IUnattended::detectIsoOS"/> or <link to="IUnattended::prepare"/>. + + Not yet implemented. + </desc> + </attribute> + + <attribute name="detectedOSVersion" type="wstring" readonly="yes"> + <desc> + The detected OS version string. + + Set by <link to="IUnattended::detectIsoOS"/> or <link to="IUnattended::prepare"/>. + + Not yet implemented. + </desc> + </attribute> + + <attribute name="detectedOSFlavor" type="wstring" readonly="yes"> + <desc> + The detected OS flavor (e.g. server, desktop, etc) + + Set by <link to="IUnattended::detectIsoOS"/> or <link to="IUnattended::prepare"/>. + + Not yet implemented. + </desc> + </attribute> + + <attribute name="detectedOSLanguages" type="wstring" readonly="yes"> + <desc> + The space separated list of (Windows) installation UI languages we detected (lang.ini). + + The language specifier format is specific to the guest OS. They are + used to set <link to="IUnattended::language"/>. + + Set by <link to="IUnattended::detectIsoOS"/> or <link to="IUnattended::prepare"/>. + + Partially implemented. + </desc> + </attribute> + + <attribute name="detectedOSHints" type="wstring" readonly="yes"> + <desc> + Space separated list of other stuff detected about the OS and the + installation ISO. + + Set by <link to="IUnattended::detectIsoOS"/> or <link to="IUnattended::prepare"/>. + + Not yet implemented. + </desc> + </attribute> + + <attribute name="detectedImageNames" type="wstring" readonly="yes" safearray="yes"> + <desc> + A list of names of the images detected from install.wim file of a Windows Vista + or later ISO. This array is parallel to <link to="IUnattended::detectedImageIndices"/>. + This will be empty for older Windows ISOs and non-Windows ISOs. + </desc> + </attribute> + + <attribute name="detectedImageIndices" type="unsigned long" readonly="yes" safearray="yes"> + <desc> + A list of image indexes detected from install.wim file of a Windows ISO. This array + is parallel to <link to="IUnattended::detectedImageNames"/>. <link to="IUnattended::imageIndex"/> + should be set to one of these indices for Vista and later Windows ISOs. + </desc> + </attribute> + + <attribute name="isUnattendedInstallSupported" type="boolean" readonly="yes"> + <desc> + Checks the detected OS type and version against a set of rules and returns + whether unattended install is supported or not. Note that failing detecting + OS type from the ISO causes this attribute to be false by default. + </desc> + </attribute> + + <attribute name="avoidUpdatesOverNetwork" type="boolean"> + <desc> + When set to true installation is configured to abstain from + using network to update/get data. Especially useful when network + is not available (as in our test boxes). + </desc> + </attribute> + + <method name="detectIsoOS"> + <desc> + Detects the OS on the ISO given by <link to="IUnattended::isoPath"/> and sets + <link to="IUnattended::detectedOSTypeId"/>, <link to="IUnattended::detectedOSVersion"/> + <link to="IUnattended::detectedOSFlavor"/>, <link to="IUnattended::detectedOSLanguages"/>, + <link to="IUnattended::detectedOSHints"/>, <link to="IUnattended::detectedImageNames"/>, + and <link to="IUnattended::detectedImageIndices"/>, + + Not really yet implemented. + </desc> + </method> + + <method name="prepare"> + <desc> + Prepare for running the unattended process of installation. + + This will perform <link to="IUnattended::detectIsoOS"/> if not yet called on the + current <link to="IUnattended::isoPath"/> value. It may then may cause + <link to="IUnattended::detectedOSTypeId"/>, <link to="IUnattended::detectedOSVersion"/>, + <link to="IUnattended::detectedOSFlavor"/>, <link to="IUnattended::detectedOSLanguages"/>, + and <link to="IUnattended::detectedOSHints"/> to be updated with values + specific to the image selected by <link to="IUnattended::imageIndex"/> if the ISO + contains images. + + This method will then instantiate the installer based on the detected guest type + (see <link to="IUnattended::detectedOSTypeId"/>). + </desc> + </method> + + <method name="constructMedia"> + <desc> + Constructors the necessary ISO/VISO/Floppy images, with unattended scripts + and all necessary bits on them. + </desc> + </method> + + <method name="reconfigureVM"> + <desc> + Reconfigures the machine to start the installation. + + This involves mounting the ISOs and floppy images created by + <link to="IUnattended::constructMedia"/>, attaching new DVD and floppy + drives as necessary, and possibly modifying the boot order. + </desc> + </method> + + <method name="done"> + <desc> + Done - time to start the VM. + + This deletes the internal installer instance that <link to="IUnattended::prepare"/> + created. Before done() is called, it is not possible to start over again + from <link to="IUnattended::prepare"/>. + </desc> + </method> + + </interface> + + <!-- + // IMachine + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IInternalMachineControl" extends="$unknown" + uuid="EA05E40C-CB31-423B-B3B7-A5B19300F40C" + internal="yes" + wsmap="suppress" + > + + <method name="updateState"> + <desc> + Updates the VM state. + <note> + This operation will also update the settings file with the correct + information about the saved state file and delete this file from disk + when appropriate. + </note> + </desc> + <param name="state" type="MachineState" dir="in"/> + </method> + + <method name="beginPowerUp"> + <desc> + Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and + gives it the progress object that should be part of any pending + <link to="IMachine::launchVMProcess"/> operations. The progress + object may be called back to reflect an early cancelation, so some care + have to be taken with respect to any cancelation callbacks. The console + object will call <link to="IInternalMachineControl::endPowerUp"/> + to signal the completion of the progress object. + </desc> + <param name="progress" type="IProgress" dir="in" /> + </method> + + <method name="endPowerUp"> + <desc> + Tells VBoxSVC that <link to="IConsole::powerUp"/> has completed. + This method may query status information from the progress object it + received in <link to="IInternalMachineControl::beginPowerUp"/> and copy + it over to any in-progress <link to="IMachine::launchVMProcess"/> + call in order to complete that progress object. + </desc> + <param name="result" type="long" dir="in"/> + </method> + + <method name="beginPoweringDown"> + <desc> + Called by the VM process to inform the server it wants to + stop the VM execution and power down. + </desc> + <param name="progress" type="IProgress" dir="out"> + <desc> + Progress object created by VBoxSVC to wait until + the VM is powered down. + </desc> + </param> + </method> + + <method name="endPoweringDown"> + <desc> + Called by the VM process to inform the server that powering + down previously requested by #beginPoweringDown is either + successfully finished or there was a failure. + + <result name="VBOX_E_FILE_ERROR"> + Settings file not accessible. + </result> + <result name="VBOX_E_XML_ERROR"> + Could not parse the settings file. + </result> + + </desc> + + <param name="result" type="long" dir="in"> + <desc>@c S_OK to indicate success. + </desc> + </param> + <param name="errMsg" type="wstring" dir="in"> + <desc>@c human readable error message in case of failure. + </desc> + </param> + </method> + + <method name="runUSBDeviceFilters"> + <desc> + Asks the server to run USB devices filters of the associated + machine against the given USB device and tell if there is + a match. + <note> + Intended to be used only for remote USB devices. Local + ones don't require to call this method (this is done + implicitly by the Host and USBProxyService). + </note> + </desc> + <param name="device" type="IUSBDevice" dir="in"/> + <param name="matched" type="boolean" dir="out"/> + <param name="maskedInterfaces" type="unsigned long" dir="out"/> + </method> + + <method name="captureUSBDevice"> + <desc> + Requests a capture of the given host USB device. + When the request is completed, the VM process will + get a <link to="IInternalSessionControl::onUSBDeviceAttach"/> + notification. + </desc> + <param name="id" type="uuid" mod="string" dir="in"/> + <param name="captureFilename" type="wstring" dir="in"/> + </method> + + <method name="detachUSBDevice"> + <desc> + Notification that a VM is going to detach (@a done = @c false) or has + already detached (@a done = @c true) the given USB device. + When the @a done = @c true request is completed, the VM process will + get a <link to="IInternalSessionControl::onUSBDeviceDetach"/> + notification. + <note> + In the @a done = @c true case, the server must run its own filters + and filters of all VMs but this one on the detached device + as if it were just attached to the host computer. + </note> + </desc> + <param name="id" type="uuid" mod="string" dir="in"/> + <param name="done" type="boolean" dir="in"/> + </method> + + <method name="autoCaptureUSBDevices"> + <desc> + Requests a capture all matching USB devices attached to the host. + When the request is completed, the VM process will + get a <link to="IInternalSessionControl::onUSBDeviceAttach"/> + notification per every captured device. + </desc> + </method> + + <method name="detachAllUSBDevices"> + <desc> + Notification that a VM that is being powered down. The done + parameter indicates whether which stage of the power down + we're at. When @a done = @c false the VM is announcing its + intentions, while when @a done = @c true the VM is reporting + what it has done. + <note> + In the @a done = @c true case, the server must run its own filters + and filters of all VMs but this one on all detach devices as + if they were just attached to the host computer. + </note> + </desc> + <param name="done" type="boolean" dir="in"/> + </method> + + <method name="onSessionEnd"> + <desc> + Triggered by the given session object when the session is about + to close normally. + </desc> + <param name="session" type="ISession" dir="in"> + <desc>Session that is being closed</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Used to wait until the corresponding machine is actually + dissociated from the given session on the server. + Returned only when this session is a direct one. + </desc> + </param> + </method> + + <method name="finishOnlineMergeMedium"> + <desc> + Gets called by <link to="IInternalSessionControl::onlineMergeMedium"/>. + All necessary state information is available at the called object. + </desc> + </method> + + <method name="pullGuestProperties"> + <desc> + Get the list of the guest properties matching a set of patterns along + with their values, timestamps and flags and give responsibility for + managing properties to the console. + </desc> + <param name="names" type="wstring" dir="out" safearray="yes"> + <desc> + The names of the properties returned. + </desc> + </param> + <param name="values" type="wstring" dir="out" safearray="yes"> + <desc> + The values of the properties returned. The array entries match the + corresponding entries in the @a name array. + </desc> + </param> + <param name="timestamps" type="long long" dir="out" safearray="yes"> + <desc> + The timestamps of the properties returned. The array entries match + the corresponding entries in the @a name array. + </desc> + </param> + <param name="flags" type="wstring" dir="out" safearray="yes"> + <desc> + The flags of the properties returned. The array entries match the + corresponding entries in the @a name array. + </desc> + </param> + </method> + <method name="pushGuestProperty"> + <desc> + Update a single guest property in IMachine. + </desc> + <param name="name" type="wstring" dir="in"> + <desc> + The name of the property to be updated. + </desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc> + The value of the property. + </desc> + </param> + <param name="timestamp" type="long long" dir="in"> + <desc> + The timestamp of the property. + </desc> + </param> + <param name="flags" type="wstring" dir="in"> + <desc> + The flags of the property. + </desc> + </param> + <param name="fWasDeleted" type="boolean" dir="in"> + <desc> + The flag which indicates if property was deleted. + </desc> + </param> + </method> + + <method name="lockMedia"> + <desc> + Locks all media attached to the machine for writing and parents of + attached differencing media (if any) for reading. This operation is + atomic so that if it fails no media is actually locked. + + This method is intended to be called when the machine is in Starting or + Restoring state. The locked media will be automatically unlocked when + the machine is powered off or crashed. + </desc> + </method> + <method name="unlockMedia"> + <desc> + Unlocks all media previously locked using + <link to="IInternalMachineControl::lockMedia"/>. + + This method is intended to be used with teleportation so that it is + possible to teleport between processes on the same machine. + </desc> + </method> + + <method name="ejectMedium"> + <desc> + Tells VBoxSVC that the guest has ejected the medium associated with + the medium attachment. + </desc> + <param name="attachment" type="IMediumAttachment" dir="in"> + <desc> + The medium attachment where the eject happened. + </desc> + </param> + <param name="newAttachment" type="IMediumAttachment" dir="return"> + <desc> + A new reference to the medium attachment, as the config change can + result in the creation of a new instance. + </desc> + </param> + </method> + + <method name="reportVmStatistics"> + <desc> + Passes statistics collected by VM (including guest statistics) to VBoxSVC. + </desc> + <param name="validStats" type="unsigned long" dir="in"> + <desc> + Mask defining which parameters are valid. For example: 0x11 means + that cpuIdle and XXX are valid. Other parameters should be ignored. + </desc> + </param> + <param name="cpuUser" type="unsigned long" dir="in"> + <desc>Percentage of processor time spent in user mode as seen by the guest.</desc> + </param> + <param name="cpuKernel" type="unsigned long" dir="in"> + <desc>Percentage of processor time spent in kernel mode as seen by the guest.</desc> + </param> + <param name="cpuIdle" type="unsigned long" dir="in"> + <desc>Percentage of processor time spent idling as seen by the guest.</desc> + </param> + <param name="memTotal" type="unsigned long" dir="in"> + <desc>Total amount of physical guest RAM.</desc> + </param> + <param name="memFree" type="unsigned long" dir="in"> + <desc>Free amount of physical guest RAM.</desc> + </param> + <param name="memBalloon" type="unsigned long" dir="in"> + <desc>Amount of ballooned physical guest RAM.</desc> + </param> + <param name="memShared" type="unsigned long" dir="in"> + <desc>Amount of shared physical guest RAM.</desc> + </param> + <param name="memCache" type="unsigned long" dir="in"> + <desc>Total amount of guest (disk) cache memory.</desc> + </param> + <param name="pagedTotal" type="unsigned long" dir="in"> + <desc>Total amount of space in the page file.</desc> + </param> + <param name="memAllocTotal" type="unsigned long" dir="in"> + <desc>Total amount of memory allocated by the hypervisor.</desc> + </param> + <param name="memFreeTotal" type="unsigned long" dir="in"> + <desc>Total amount of free memory available in the hypervisor.</desc> + </param> + <param name="memBalloonTotal" type="unsigned long" dir="in"> + <desc>Total amount of memory ballooned by the hypervisor.</desc> + </param> + <param name="memSharedTotal" type="unsigned long" dir="in"> + <desc>Total amount of shared memory in the hypervisor.</desc> + </param> + <param name="vmNetRx" type="unsigned long" dir="in"> + <desc>Network receive rate for VM.</desc> + </param> + <param name="vmNetTx" type="unsigned long" dir="in"> + <desc>Network transmit rate for VM.</desc> + </param> + </method> + + <method name="authenticateExternal"> + <desc> + Verify credentials using the external auth library. + </desc> + <param name="authParams" type="wstring" dir="in" safearray="yes"> + <desc> + The auth parameters, credentials, etc. + </desc> + </param> + <param name="result" type="wstring" dir="out"> + <desc> + The authentification result. + </desc> + </param> + </method> + </interface> + + <interface + name="IGraphicsAdapter" extends="$unknown" + uuid="f692806f-febe-4049-b476-1292a8e45b09" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + The IGraphicsAdapter interface represents the graphics adapter + of the virtual machine. + </desc> + + <attribute name="graphicsControllerType" type="GraphicsControllerType"> + <desc>Graphics controller type.</desc> + </attribute> + + <attribute name="VRAMSize" type="unsigned long"> + <desc>Video memory size in megabytes.</desc> + </attribute> + + <attribute name="accelerate3DEnabled" type="boolean" default="false"> + <desc> + This setting determines whether VirtualBox allows this machine to make + use of the 3D graphics support available on the host.</desc> + </attribute> + + <attribute name="accelerate2DVideoEnabled" type="boolean" default="false"> + <desc> + This setting determines whether VirtualBox allows this machine to make + use of the 2D video acceleration support available on the host.</desc> + </attribute> + + <attribute name="monitorCount" type="unsigned long"> + <desc> + Number of virtual monitors. + <note> + Only effective on Windows XP and later guests with + Guest Additions installed. + </note> + </desc> + </attribute> + + </interface> + + <interface + name="IBIOSSettings" extends="$unknown" + uuid="a0a7f210-b857-4468-be26-c29f36a84345" + wsmap="managed" + rest="managed" + reservedMethods="2" reservedAttributes="8" + > + <desc> + The IBIOSSettings interface represents BIOS settings of the virtual + machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute. + </desc> + <attribute name="logoFadeIn" type="boolean"> + <desc>Fade in flag for BIOS logo animation.</desc> + </attribute> + + <attribute name="logoFadeOut" type="boolean"> + <desc>Fade out flag for BIOS logo animation.</desc> + </attribute> + + <attribute name="logoDisplayTime" type="unsigned long"> + <desc>BIOS logo display time in milliseconds (0 = default).</desc> + </attribute> + + <attribute name="logoImagePath" type="wstring"> + <desc> + Local file system path for external BIOS splash image. Empty string + means the default image is shown on boot. + </desc> + </attribute> + + <attribute name="bootMenuMode" type="BIOSBootMenuMode"> + <desc>Mode of the BIOS boot device menu.</desc> + </attribute> + + <attribute name="ACPIEnabled" type="boolean"> + <desc>ACPI support flag.</desc> + </attribute> + + <attribute name="IOAPICEnabled" type="boolean"> + <desc> + I/O-APIC support flag. If set, VirtualBox will provide an I/O-APIC + and support IRQs above 15. + </desc> + </attribute> + + <attribute name="APICMode" type="APICMode"> + <desc> + APIC mode to set up by the firmware. + </desc> + </attribute> + + <attribute name="timeOffset" type="long long"> + <desc> + Offset in milliseconds from the host system time. This allows for + guests running with a different system date/time than the host. + It is equivalent to setting the system date/time in the BIOS except + it is not an absolute value but a relative one. Guest Additions + time synchronization honors this offset. + </desc> + </attribute> + + <attribute name="PXEDebugEnabled" type="boolean"> + <desc> + PXE debug logging flag. If set, VirtualBox will write extensive + PXE trace information to the release log. + </desc> + </attribute> + + <attribute name="SMBIOSUuidLittleEndian" type="boolean"> + <desc> + Flag to control whether the SMBIOS system UUID is presented in little endian + form to the guest as mandated by the SMBIOS spec chapter 7.2.1. + Before VirtualBox version 6.1 it was always presented in big endian form + and to retain the old behavior this flag was introduced so it can be changed. + VMs created with VBox 6.1 will default to true for this flag. + </desc> + </attribute> + + </interface> + + <enum + name="TpmType" + uuid="c669b9f7-a547-42b6-8464-636aa53401eb" + > + <desc> + TPM type enumeration. + </desc> + + <const name="None" value="0"> + <desc>No TPM present in the virtual machine.</desc> + </const> + <const name="v1_2" value="1"> + <desc>A TPM compliant to the 1.2 TCG specification is emulated.</desc> + </const> + <const name="v2_0" value="2"> + <desc>A TPM compliant to the 2.0 TCG specification is emulated.</desc> + </const> + <const name="Host" value="3"> + <desc>The host TPM is passed through, might not be available on all host platforms.</desc> + </const> + <const name="Swtpm" value="4"> + <desc>The VM will attach to an external software TPM emulation compliant to swtpm.</desc> + </const> + </enum> + + <interface + name="ITrustedPlatformModule" extends="$unknown" + uuid="cf11d345-0241-4ea9-ac4c-c69ed3d674e3" + wsmap="managed" + reservedMethods="2" reservedAttributes="8" + > + <desc> + The ITrustedPlatformModule interface represents the settings of the virtual + machine's trusted platform module. This is used only in the <link to="IMachine::trustedPlatformModule"/> attribute. + </desc> + + <attribute name="type" type="TpmType"> + <desc> + Type of TPM configured for the virtual machine. + </desc> + </attribute> + + <attribute name="location" type="wstring"> + <desc> + Location of the TPM. This is only used for the TpmType_Swtpm type of TPM + where the location denotes a <b>hostname:port</b> where to connect to. + </desc> + </attribute> + + </interface> + + <enum + name="RecordingDestination" + uuid="11E3F06B-DEC1-48B9-BDC4-1E618D72893C" + > + <desc> + Recording destination enumeration. + </desc> + + <const name="None" value="0"> + <desc>No destination.</desc> + </const> + <const name="File" value="1"> + <desc>Destination is a regular file.</desc> + </const> + </enum> + + <enum + name="RecordingFeature" + uuid="A7DDC6A5-DAA8-4485-B860-E9F2E98A7794" + > + <desc> + Recording feature flags. More than one flag may be set. + </desc> + + <const name="None" value="0x0"> + <desc>No feature set.</desc> + </const> + <const name="Video" value="0x1"> + <desc>Video recording.</desc> + </const> + <const name="Audio" value="0x2"> + <desc>Audio recording.</desc> + </const> + </enum> + + <enum + name="RecordingAudioCodec" + uuid="16c42be8-1713-4717-a8b9-c65a6549fbcd" + > + <desc> + Recording audio codec enumeration. + </desc> + + <const name="None" value="0"> + <desc>No codec set.</desc> + </const> + <const name="WavPCM" value="1"> + <desc>WAV format, linear PCM, uncompressed.</desc> + </const> + <const name="MP3" value="2"> + <desc>MPEG-2 Audio Layer III.</desc> + </const> + <const name="OggVorbis" value="3"> + <desc>Ogg Vorbis.</desc> + </const> + <const name="Opus" value="4"> + <desc>Opus Audio.</desc> + </const> + <const name="Other" value="5"> + <desc>Other codec.</desc> + </const> + </enum> + + <enum + name="RecordingCodecDeadline" + uuid="53627ae1-31cf-4303-9cd5-0c22fd2637cf" + > + <desc> + Recording codec deadline. + + How (and if at all) this deadline is being implemented depends on the codec being used. + </desc> + + <const name="Default" value="0"> + <desc>Default deadline.</desc> + </const> + <const name="Realtime" value="1"> + <desc>Realtime quality, often resulting in poor / basic quality.</desc> + </const> + <const name="Good" value="2"> + <desc>Balance between realtime and best deadline.</desc> + </const> + <const name="Best" value="3"> + <desc>Best quality, slowest.</desc> + </const> + </enum> + + <enum + name="RecordingVideoCodec" + uuid="93791063-3e8c-4310-987c-ddb43ff03ffe" + > + <desc> + Recording video codec enumeration. + </desc> + + <const name="None" value="0"> + <desc>No codec set.</desc> + </const> + <const name="MJPEG" value="1"> + <desc>Motion JPEG.</desc> + </const> + <const name="H262" value="2"> + <desc>MPEG-2, Part 2.</desc> + </const> + <const name="H264" value="3"> + <desc>Advanced Video Coding (AVC), MPEG-4 Part 10.</desc> + </const> + <const name="H265" value="4"> + <desc>High Efficiency Video Coding (HEVC), MPEG-H Part 2.</desc> + </const> + <const name="H266" value="5"> + <desc>Versatile Video Coding (VVC), MPEG-I Part 3.</desc> + </const> + <const name="VP8" value="6"> + <desc>VP8 codec.</desc> + </const> + <const name="VP9" value="7"> + <desc>VP9 codec.</desc> + </const> + <const name="AV1" value="8"> + <desc>AOMedia Video 1 codec.</desc> + </const> + <const name="Other" value="9"> + <desc>Other codec.</desc> + </const> + </enum> + + <enum + name="RecordingVideoScalingMode" + uuid="0dd1127d-4f62-4b82-beee-91086a9f1d24" + > + <desc> + Recording video scaling method enumeration. + </desc> + + <const name="None" value="0"> + <desc>No scaling performed. + The image wil be cropped when the source is bigger than the target size.</desc> + </const> + <const name="NearestNeighbor" value="1"> + <desc>Performs scaling via nearest-neighbor interpolation. + Not yet implemented.</desc> + </const> + <const name="Bilinear" value="2"> + <desc>Performs scaling via bilinear interpolation. + Not yet implemented.</desc> + </const> + <const name="Bicubic" value="3"> + <desc>Performs scaling via bicubic interpolation. + Not yet implemented.</desc> + </const> + </enum> + + <enum + name="RecordingRateControlMode" + uuid="d07a33ac-b4ea-4917-942d-c03be14fbe2f" + > + <desc> + Recording video rate control mode enumeration. + <note>Not all codecs may support all rate control modes.</note> + </desc> + + <const name="ABR" value="0"> + <desc>Average bit rate (ABR). Constrained to a certain size.</desc> + </const> + <const name="CBR" value="1"> + <desc>Constant bit rate (CBR). Constrained to a certain size.</desc> + </const> + <const name="VBR" value="2"> + <desc>Variable bit rate (VBR). Constrained to a certain quality.</desc> + </const> + </enum> + + <interface + name="IRecordingScreenSettings" extends="$unknown" + uuid="c1844087-ec6b-488d-afbb-c90f6452a04b" + wsmap="managed" + rest="managed" + > + + <desc> + The IRecordingScreenSettings interface represents recording settings of a + single virtual screen. This is used only in the <link to="IRecordingSettings" /> + interface. + </desc> + + <method name="isFeatureEnabled"> + <desc>Returns whether a particular recording feature is enabled for this + screen or not.</desc> + <param name="feature" type="RecordingFeature" dir="in"> + <desc>Feature to check for.</desc> + </param> + <param name="enabled" type="boolean" dir="return"> + <desc>@c true if the feature is enabled, @c false if not.</desc> + </param> + </method> + + <attribute name="id" type="unsigned long" readonly="yes"> + <desc> + This attribute contains the screen ID bound to these settings. + </desc> + </attribute> + + <attribute name="enabled" type="boolean" default="false"> + <desc> + This setting determines whether this screen is enabled while recording. + </desc> + </attribute> + + <attribute name="features" type="RecordingFeature" safearray="yes"> + <desc>This setting determines all enabled recording features for this + screen.</desc> + </attribute> + + <attribute name="destination" type="RecordingDestination"> + <desc>This setting determines the recording destination for this + screen.</desc> + </attribute> + + <attribute name="filename" type="wstring"> + <desc> + This setting determines the filename VirtualBox uses to save + the recorded content. This setting cannot be changed while video + recording is enabled. + <note> + When setting this attribute, the specified path has to be + absolute (full path). When reading this attribute, a full path is + always returned. + </note> + </desc> + </attribute> + + <attribute name="maxTime" type="unsigned long" default="0"> + <desc> + This setting defines the maximum amount of time in seconds + to record. Recording will stop as soon as the defined time + interval has elapsed. If this value is zero, recording will not be + limited by time. This setting cannot be changed while recording is + enabled. + </desc> + </attribute> + + <attribute name="maxFileSize" type="unsigned long" default="0"> + <desc> + This setting determines the maximal number of recording file + size in MB. Recording will stop as soon as the file size has + reached the defined value. If this value is zero, recording + will not be limited by the file size. This setting cannot be changed + while recording is enabled. + </desc> + </attribute> + + <attribute name="options" type="wstring"> + <desc> + This setting contains any additional recording options required in + comma-separated key=value format, which are currently not represented + via own attribtues. Consider these options as experimental and mostly + for codec-specific settings, and are subject to change. This setting + cannot be changed while recording is enabled. + </desc> + </attribute> + + <attribute name="audioCodec" type="RecordingAudioCodec"> + <desc> + Determines the audio codec to use for encoding the + recorded audio data. This setting cannot be changed while recording is + enabled. + + <note> + Only the Opus codec is supported currently. + </note> + </desc> + </attribute> + + <attribute name="audioRateControlMode" type="RecordingRateControlMode"> + <desc> + Determines the audio rate control mode. This setting cannot be changed + while recording is enabled. + </desc> + </attribute> + + <attribute name="audioDeadline" type="RecordingCodecDeadline" default="Default"> + <desc> + Determines the audio deadline to use. + This setting cannot be changed while recording is enabled. + </desc> + </attribute> + + <attribute name="audioHz" type="unsigned long" default="22050"> + <desc> + Determines the Hertz (Hz) rate of the recorded audio data. This setting + cannot be changed while recording is enabled. + </desc> + </attribute> + + <attribute name="audioBits" type="unsigned long" default="16"> + <desc> + Determines the bits per sample of the recorded audio data. This setting + cannot be changed while recording is enabled. + </desc> + </attribute> + + <attribute name="audioChannels" type="unsigned long" default="2"> + <desc> + Determines the audio channels of the recorded audio data. + Specifiy 2 for stereo or 1 for mono. More than stereo (2) channels + are not supported at the moment. This setting cannot be changed while + recording is enabled. + </desc> + </attribute> + + <attribute name="videoCodec" type="RecordingVideoCodec"> + <desc> + Determines the video codec to use for encoding the recorded video data. + This setting cannot be changed while recording is enabled. + + <note> + Only the VP8 codec is supported currently. + </note> + </desc> + </attribute> + + <attribute name="videoDeadline" type="RecordingCodecDeadline" default="Default"> + <desc> + Determines the video deadline to use. + This setting cannot be changed while recording is enabled. + </desc> + </attribute> + + <attribute name="videoWidth" type="unsigned long" default="1024"> + <desc> + Determines the horizontal resolution of the recorded video data. This + setting cannot be changed while recording is enabled. + </desc> + </attribute> + + <attribute name="videoHeight" type="unsigned long" default="768"> + <desc> + Determines the vertical resolution of the recorded video data. This + setting cannot be changed while recording is enabled. + </desc> + </attribute> + + <attribute name="videoRate" type="unsigned long" default="512"> + <desc> + Determines the bitrate in kilobits per second. Increasing this value + makes the video look better for the cost of an increased file size or + transfer rate. This setting cannot be changed while recording is enabled. + </desc> + </attribute> + + <attribute name="videoRateControlMode" type="RecordingRateControlMode"> + <desc> + Determines the video rate control mode. This setting cannot be changed + while recording is enabled. + </desc> + </attribute> + + <attribute name="videoFPS" type="unsigned long" default="25"> + <desc> + Determines the maximum number of frames per second (FPS). Frames with + a higher frequency will be skipped. Reducing this value increases the + number of skipped frames and reduces the file size or transfer rate. + This setting cannot be changed while recording is enabled. + </desc> + </attribute> + + <attribute name="videoScalingMode" type="RecordingVideoScalingMode"> + <desc> + Determines the video scaling mode to use. + This setting cannot be changed while recording is enabled. + </desc> + </attribute> + + </interface> + + <interface + name="IRecordingSettings" extends="$unknown" + uuid="D88F2A5A-47C7-4A3F-AAE1-1B516817DB41" + wsmap="managed" + rest="managed" + > + + <desc> + The IRecordingSettings interface represents recording settings of the virtual + machine. This is used only in the <link to="IMachine::recordingSettings" /> + attribute. + </desc> + + <method name="getScreenSettings"> + <desc>Returns the recording settings for a particular screen.</desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc>Screen ID to retrieve recording screen settings for.</desc> + </param> + <param name="recordScreenSettings" type="IRecordingScreenSettings" dir="return"> + <desc>Recording screen settings for the requested screen.</desc> + </param> + </method> + + <attribute name="enabled" type="boolean" default="false"> + <desc> + This setting determines whether VirtualBox uses recording to record a + VM session.</desc> + </attribute> + + <attribute name="screens" type="IRecordingScreenSettings" readonly="yes" safearray="yes"> + <desc> + This setting returns an array for recording settings of all configured + virtual screens.</desc> + </attribute> + + </interface> + + <interface + name="IPCIAddress" extends="$unknown" + uuid="c984d15f-e191-400b-840e-970f3dad7296" + wsmap="managed" + rest="managed" + > + + <desc> + Address on the PCI bus. + </desc> + + <attribute name="bus" type="short"> + <desc> + Bus number. + </desc> + </attribute> + + <attribute name="device" type="short"> + <desc> + Device number. + </desc> + </attribute> + + <attribute name="devFunction" type="short"> + <desc> + Device function number. + </desc> + </attribute> + + <method name="asLong"> + <desc> + Convert PCI address into long. + </desc> + <param name="result" type="long" dir="return" /> + </method> + + <method name="fromLong"> + <desc> + Make PCI address from long. + </desc> + <param name="number" type="long" dir="in" /> + </method> + </interface> + + <interface + name="IPCIDeviceAttachment" extends="$unknown" + uuid="91f33d6f-e621-4f70-a77e-15f0e3c714d5" + wsmap="struct" + rest="managed" + > + + <desc> + Information about PCI attachments. + </desc> + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + Device name. + </desc> + </attribute> + + <attribute name="isPhysicalDevice" type="boolean" readonly="yes"> + <desc> + If this is physical or virtual device. + </desc> + </attribute> + + <attribute name="hostAddress" type="long" readonly="yes"> + <desc> + Address of device on the host, applicable only to host devices. + </desc> + </attribute> + + <attribute name="guestAddress" type="long" readonly="yes"> + <desc> + Address of device in the guest. + </desc> + </attribute> + + </interface> + + <enum + name="SignatureType" + uuid="6f6e67ef-9a32-4084-af84-5702679f882a" + > + <desc> + UEFI signature type enumeration. + </desc> + + <const name="X509" value="0"> + <desc>X.509 certificate.</desc> + </const> + <const name="Sha256" value="1"> + <desc>SHA256 hash.</desc> + </const> + </enum> + + <enum + name="UefiVariableAttributes" + uuid="cda505ec-b444-4aef-b55c-b687717bdac5" + > + <desc> + Possible variable attributes. More than one flag may be set. + <see><link to="IUefiVariableStore"/></see> + </desc> + + <const name="None" value="0"> + <desc>No attributes set.</desc> + </const> + <const name="NonVolatile" value="0x01"> + <desc>Variable is stored in non volatile storage.</desc> + </const> + <const name="BootServiceAccess" value="0x02"> + <desc>Variable can be accessed from the boot services.</desc> + </const> + <const name="RuntimeAccess" value="0x04"> + <desc>Variable can be accessed from the runtime.</desc> + </const> + <const name="HwErrorRecord" value="0x08"> + <desc>Variable contains a hardware error record.</desc> + </const> + <const name="AuthWriteAccess" value="0x100"> + <desc>Writing to this variable requires an authenticated source.</desc> + </const> + <const name="AuthTimeBasedWriteAccess" value="0x200"> + <desc>Variable was written with a time based authentication.</desc> + </const> + <const name="AuthAppendWrite" value="0x400"> + <desc>The variable can be appended only.</desc> + </const> + </enum> + + <interface + name="IUefiVariableStore" extends="$unknown" + uuid="d134c6b6-4479-430d-bb73-68a452ba3e67" + wsmap="managed" + reservedMethods="10" reservedAttributes="5" + > + <desc> + The IUefiVariableStore interface allows inspecting and manipulating the content + of an existing UEFI variable store in a NVRAM file. This is used only in the + <link to="INvramStore::uefiVariableStore" /> attribute. + </desc> + + <attribute name="secureBootEnabled" type="boolean"> + <desc>Flag whether secure boot is currently enabled for the VM.</desc> + </attribute> + + <method name="addVariable"> + <desc>Adds a new variable to the non volatile storage area.</desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the variable.</desc> + </param> + <param name="owner" type="uuid" mod="string" dir="in"> + <desc>UUID of the variable owner.</desc> + </param> + <param name="attributes" type="UefiVariableAttributes" safearray="yes" dir="in"> + <desc>Attributes of the variable.</desc> + </param> + <param name="data" type="octet" dir="in" safearray="yes"> + <desc>The variable data.</desc> + </param> + </method> + + <method name="deleteVariable"> + <desc>Deletes the given variable from the non volatile storage area.</desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the variable.</desc> + </param> + <param name="owner" type="uuid" mod="string" dir="in"> + <desc>UUID of the variable owner.</desc> + </param> + </method> + + <method name="changeVariable"> + <desc>Changes the data of the given variable.</desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the variable.</desc> + </param> + <param name="data" type="octet" dir="in" safearray="yes"> + <desc>The new variable data.</desc> + </param> + </method> + + <method name="queryVariableByName"> + <desc>Queries the variable content variable by the given name.</desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the variable to look for.</desc> + </param> + <param name="owner" type="uuid" mod="string" dir="out"> + <desc>UUID of the variable owner returned on success.</desc> + </param> + <param name="attributes" type="UefiVariableAttributes" safearray="yes" dir="out"> + <desc>Attributes of the variable.</desc> + </param> + <param name="data" type="octet" dir="out" safearray="yes"> + <desc>The variable data returned on success.</desc> + </param> + </method> + + <method name="queryVariables"> + <desc> + Queries all variables in the non volatile storage and returns their names. + </desc> + <param name="names" type="wstring" dir="out" safearray="yes"> + <desc>The variable names returned on success.</desc> + </param> + <param name="owners" type="uuid" mod="string" dir="out" safearray="yes"> + <desc>UUID of the variable owners returned on success.</desc> + </param> + </method> + + <method name="enrollOraclePlatformKey"> + <desc> + Enroll the default platform key from Oracle for enabling Secure Boot. + </desc> + </method> + + <method name="enrollPlatformKey"> + <desc> + Convenience method to enroll a new platform key (PK) for enabling Secure Boot. + </desc> + <param name="platformKey" type="octet" safearray="yes" dir="in"> + <desc>The platform key (PK) to enroll.</desc> + </param> + <param name="owner" type="uuid" mod="string" dir="in"> + <desc>UUID of the PK owner.</desc> + </param> + </method> + + <method name="addKek"> + <desc> + Convenience method to add a new Key Encryption Key (KEK) for Secure Boot. + </desc> + <param name="keyEncryptionKey" type="octet" safearray="yes" dir="in"> + <desc>The Key Encryption Key (KEK) to add.</desc> + </param> + <param name="owner" type="uuid" mod="string" dir="in"> + <desc>UUID of the KEK owner.</desc> + </param> + <param name="signatureType" type="SignatureType" dir="in"> + <desc>Type of the signature.</desc> + </param> + </method> + + <method name="addSignatureToDb"> + <desc> + Convenience method to add a new entry to the signature database. + </desc> + <param name="signature" type="octet" safearray="yes" dir="in"> + <desc>The signature to add.</desc> + </param> + <param name="owner" type="uuid" mod="string" dir="in"> + <desc>UUID of the signature owner.</desc> + </param> + <param name="signatureType" type="SignatureType" dir="in"> + <desc>Type of the signature.</desc> + </param> + </method> + + <method name="addSignatureToDbx"> + <desc> + Convenience method to add a new entry to the forbidden signature database. + </desc> + <param name="signature" type="octet" safearray="yes" dir="in"> + <desc>The signature to add.</desc> + </param> + <param name="owner" type="uuid" mod="string" dir="in"> + <desc>UUID of the signature owner.</desc> + </param> + <param name="signatureType" type="SignatureType" dir="in"> + <desc>Type of the signature.</desc> + </param> + </method> + + <method name="enrollDefaultMsSignatures"> + <desc> + Convenience method to enroll the standard Microsoft KEK and signatures + in the signature databases. + </desc> + </method> + + </interface> + + <interface + name="INvramStore" extends="$unknown" + uuid="5bfd8965-b81b-469f-8649-f717ce97a5d5" + wsmap="managed" + > + + <desc> + Provides access to the NVRAM store collecting all permanent states from different sources + (UEFI, TPM, etc.). + </desc> + + <attribute name="nonVolatileStorageFile" type="wstring" readonly="yes"> + <desc> + The location of the file storing the non-volatile memory content when + the VM is powered off. The file does not always exist. + </desc> + </attribute> + + <attribute name="uefiVariableStore" type="IUefiVariableStore" readonly="yes"> + <desc>Object to manipulate the data in an existing UEFI variable store.</desc> + </attribute> + + <attribute name="keyId" type="wstring" readonly="yes"> + <desc> + Key Id of the password used for encrypting the NVRAM file. + Internal use only for now. + </desc> + </attribute> + + <attribute name="keyStore" type="wstring" readonly="yes"> + <desc> + Key store used for encrypting the NVRAM file. + Internal use only for now. + </desc> + </attribute> + + <method name="initUefiVariableStore"> + <desc>Initializes the UEFI variable store.</desc> + <param name="size" type="unsigned long" dir="in"> + <desc> + Size in bytes of the UEFI variable store. Must be 0 for now to initialize to the + default size. + </desc> + </param> + </method> + + </interface> + + <enum + name="GraphicsControllerType" + uuid="3e009bb0-2b57-4283-a39b-4c363d4f0808" + > + <desc>Graphics controller type, used with <link to="IGraphicsAdapter::graphicsControllerType" />. + </desc> + <const name="Null" value="0"> + <desc>Reserved value, invalid.</desc> + </const> + <const name="VBoxVGA" value="1"> + <desc>VirtualBox VGA device.</desc> + </const> + <const name="VMSVGA" value="2"> + <desc>VMware SVGA II device.</desc> + </const> + <const name="VBoxSVGA" value="3"> + <desc>VirtualBox VGA device with VMware SVGA II extensions.</desc> + </const> + </enum> + + <enum + name="CleanupMode" + uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441" + > + <desc>Cleanup mode, used with <link to="IMachine::unregister" />. + </desc> + <const name="UnregisterOnly" value="1"> + <desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc> + </const> + <const name="DetachAllReturnNone" value="2"> + <desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc> + </const> + <const name="DetachAllReturnHardDisksOnly" value="3"> + <desc>Delete all snapshots, detach all media and return hard disks for closing, but not removable media.</desc> + </const> + <const name="Full" value="4"> + <desc>Delete all snapshots, detach all media and return all media for closing.</desc> + </const> + <const name="DetachAllReturnHardDisksAndVMRemovable" value="5"> + <desc>Delete all snapshots, detach all media and return hard disks and removable locating in the folder of the machine to be deleted and referenced only to this machine, for closing.</desc> + </const> + </enum> + + <enum + name="CloneMode" + uuid="A7A159FE-5096-4B8D-8C3C-D033CB0B35A8" + > + + <desc> + Clone mode, used with <link to="IMachine::cloneTo" />. + </desc> + + <const name="MachineState" value="1"> + <desc>Clone the state of the selected machine.</desc> + </const> + <const name="MachineAndChildStates" value="2"> + <desc>Clone the state of the selected machine and its child snapshots if present.</desc> + </const> + <const name="AllStates" value="3"> + <desc>Clone all states (including all snapshots) of the machine, regardless of the machine object used.</desc> + </const> + + </enum> + + <enum + name="CloneOptions" + uuid="22243f8e-96ab-497c-8cf0-f40a566c630b" + > + + <desc> + Clone options, used with <link to="IMachine::cloneTo" />. + </desc> + + <const name="Link" value="1"> + <desc>Create a clone VM where all virtual disks are linked to the original VM.</desc> + </const> + <const name="KeepAllMACs" value="2"> + <desc>Don't generate new MAC addresses of the attached network adapters.</desc> + </const> + <const name="KeepNATMACs" value="3"> + <desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc> + </const> + <const name="KeepDiskNames" value="4"> + <desc>Don't change the disk names.</desc> + </const> + <const name="KeepHwUUIDs" value="5"> + <desc>Don't change UUID of the machine hardware.</desc> + </const> + + </enum> + + <enum + name="AutostopType" + uuid="6bb96740-cf34-470d-aab2-2cd48ea2e10e" + > + + <desc> + Autostop types, used with <link to="IMachine::autostopType" />. + </desc> + + <const name="Disabled" value="1"> + <desc>Stopping the VM during system shutdown is disabled.</desc> + </const> + <const name="SaveState" value="2"> + <desc>The state of the VM will be saved when the system shuts down.</desc> + </const> + <const name="PowerOff" value="3"> + <desc>The VM is powered off when the system shuts down.</desc> + </const> + <const name="AcpiShutdown" value="4"> + <desc>An ACPI shutdown event is generated.</desc> + </const> + + </enum> + + <enum + name="VMProcPriority" + uuid="6fa72dd5-19b7-46ba-bc52-f223c98c7d80" + > + <desc> + Virtual machine process priorities. + </desc> + + <const name="Invalid" value="0"> + <desc>Invalid priority, do not use.</desc> + </const> + <const name="Default" value="1"> + <desc>Default process priority determined by the OS.</desc> + </const> + <const name="Flat" value="2"> + <desc> + Assumes a scheduling policy which puts the process at the default + priority and with all threads at the same priority + </desc> + </const> + <const name="Low" value="3"> + <desc> + Assumes a scheduling policy which puts the process mostly below the + default priority of the host OS. + </desc> + </const> + <const name="Normal" value="5"> + <desc> + Assume a scheduling policy which shares the CPU resources fairly with + other processes running with the default priority of the host OS. + </desc> + </const> + <const name="High" value="6"> + <desc> + Assumes a scheduling policy which puts the task above the default + priority of the host OS. This policy might easily cause other tasks + in the system to starve. + </desc> + </const> + </enum> + + <enum + name="IommuType" + uuid="f47339cb-b94e-48fe-b507-2900103d7b9f" + > + <desc> + The IOMMU type. This enumeration represents possible + values for the <link to="IMachine::iommuType"/> attribute. + </desc> + <const name="None" value="0"> + <desc>No IOMMU is present.</desc> + </const> + <const name="Automatic" value="1"> + <desc>No IOMMU is present.</desc> + </const> + <const name="AMD" value="2"> + <desc>An AMD IOMMU.</desc> + </const> + <const name="Intel" value="3"> + <desc>An Intel IOMMU.</desc> + </const> + </enum> + + <interface + name="IMachine" extends="$unknown" + uuid="300763af-5d6b-46e6-aa96-273eac15538a" + wsmap="managed" + rest="managed" + wrap-hint-server-addinterfaces="IInternalMachineControl" + wrap-hint-server="manualaddinterfaces" + reservedMethods="8" reservedAttributes="16" + > + <!-- Note! This interface is not compatible between 5.0 and 5.1 as it had too many + methods/attributes for midl and the reservedAttributes had to be + decreased. Max methods+attributes is 256, so in 6.0 this interface must + be refactored a little! In the mean time, take from reservedMethods and + reservedAttributes and update the UUID like always. --> + <desc> + The IMachine interface represents a virtual machine, or guest, created + in VirtualBox. + + This interface is used in two contexts. First of all, a collection of + objects implementing this interface is stored in the + <link to="IVirtualBox::machines"/> attribute which lists all the virtual + machines that are currently registered with this VirtualBox + installation. Also, once a session has been opened for the given virtual + machine (e.g. the virtual machine is running), the machine object + associated with the open session can be queried from the session object; + see <link to="ISession"/> for details. + + The main role of this interface is to expose the settings of the virtual + machine and provide methods to change various aspects of the virtual + machine's configuration. For machine objects stored in the + <link to="IVirtualBox::machines"/> collection, all attributes are + read-only unless explicitly stated otherwise in individual attribute + and method descriptions. + + In order to change a machine setting, a session for this machine must be + opened using one of the <link to="IMachine::lockMachine" /> or + <link to="IMachine::launchVMProcess"/> methods. After the + machine has been successfully locked for a session, a mutable machine object + needs to be queried from the session object and then the desired settings + changes can be applied to the returned object using IMachine attributes and + methods. See the <link to="ISession"/> interface description for more + information about sessions. + + Note that IMachine does not provide methods to control virtual machine + execution (such as start the machine, or power it down) -- these methods + are grouped in a separate interface called <link to="IConsole" />. + + <see><link to="ISession"/>, <link to="IConsole"/></see> + </desc> + + <attribute name="parent" type="IVirtualBox" readonly="yes" wrap-hint-server="limitedcaller" rest="suppress"> + <desc>Associated parent object.</desc> + </attribute> + + <attribute name="icon" type="octet" safearray="yes"> + <desc>Overridden VM Icon details.</desc> + </attribute> + + <attribute name="accessible" type="boolean" readonly="yes" wrap-hint-server="limitedcaller"> + <desc> + Whether this virtual machine is currently accessible or not. + + A machine is always deemed accessible unless it is registered <i>and</i> + its settings file cannot be read or parsed (either because the file itself + is unavailable or has invalid XML contents). + + Every time this property is read, the accessibility state of + this machine is re-evaluated. If the returned value is @c false, + the <link to="#accessError"/> property may be used to get the + detailed error information describing the reason of + inaccessibility, including XML error messages. + + When the machine is inaccessible, only the following properties + can be used on it: + <ul> + <li><link to="#parent"/></li> + <li><link to="#id"/></li> + <li><link to="#settingsFilePath"/></li> + <li><link to="#accessible"/></li> + <li><link to="#accessError"/></li> + </ul> + + An attempt to access any other property or method will return + an error. + + The only possible action you can perform on an inaccessible + machine is to unregister it using the + <link to="IMachine::unregister"/> call (or, to check + for the accessibility state once more by querying this + property). + + <note> + In the current implementation, once this property returns + @c true, the machine will never become inaccessible + later, even if its settings file cannot be successfully + read/written any more (at least, until the VirtualBox + server is restarted). This limitation may be removed in + future releases. + </note> + </desc> + </attribute> + + <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes" wrap-hint-server="limitedcaller"> + <desc> + Error information describing the reason of machine + inaccessibility. + + Reading this property is only valid after the last call to + <link to="#accessible"/> returned @c false (i.e. the + machine is currently inaccessible). Otherwise, a @c null + IVirtualBoxErrorInfo object will be returned. + </desc> + </attribute> + + <attribute name="name" type="wstring"> + <desc> + Name of the virtual machine. + + Besides being used for human-readable identification purposes + everywhere in VirtualBox, the virtual machine name is also used + as a name of the machine's settings file and as a name of the + subdirectory this settings file resides in. Thus, every time you + change the value of this property, the settings file will be + renamed once you call <link to="#saveSettings"/> to confirm the + change. The containing subdirectory will be also renamed, but + only if it has exactly the same name as the settings file + itself prior to changing this property (for backward compatibility + with previous API releases). The above implies the following + limitations: + <ul> + <li>The machine name cannot be empty.</li> + <li>The machine name can contain only characters that are valid + file name characters according to the rules of the file + system used to store VirtualBox configuration.</li> + <li>You cannot have two or more machines with the same name + if they use the same subdirectory for storing the machine + settings files.</li> + <li>You cannot change the name of the machine if it is running, + or if any file in the directory containing the settings file + is being used by another running machine or by any other + process in the host operating system at a time when + <link to="#saveSettings"/> is called. + </li> + </ul> + If any of the above limitations are hit, <link to="#saveSettings"/> + will return an appropriate error message explaining the exact + reason and the changes you made to this machine will not be saved. + + Starting with VirtualBox 4.0, a ".vbox" extension of the settings + file is recommended, but not enforced. (Previous versions always + used a generic ".xml" extension.) + </desc> + </attribute> + + <attribute name="description" type="wstring"> + <desc> + Description of the virtual machine. + + The description attribute can contain any text and is + typically used to describe the hardware and software + configuration of the virtual machine in detail (i.e. network + settings, versions of the installed software and so on). + </desc> + </attribute> + + <attribute name="id" type="uuid" mod="string" readonly="yes" wrap-hint-server="limitedcaller"> + <desc>UUID of the virtual machine.</desc> + </attribute> + + <attribute name="groups" type="wstring" safearray="yes"> + <desc> + Array of machine group names of which this machine is a member. + <tt>""</tt> and <tt>"/"</tt> are synonyms for the toplevel group. Each + group is only listed once, however they are listed in no particular + order and there is no guarantee that there are no gaps in the group + hierarchy (i.e. <tt>"/group"</tt>, + <tt>"/group/subgroup/subsubgroup"</tt> is a valid result). + </desc> + </attribute> + + <attribute name="OSTypeId" type="wstring"> + <desc> + User-defined identifier of the Guest OS type. + You may use <link to="IVirtualBox::getGuestOSType"/> to obtain + an IGuestOSType object representing details about the given + Guest OS type. All Guest OS types are considered valid, even those + which are not known to <link to="IVirtualBox::getGuestOSType"/>. + <note> + This value may differ from the value returned by + <link to="IGuest::OSTypeId"/> if Guest Additions are + installed to the guest OS. + </note> + </desc> + </attribute> + + <attribute name="hardwareVersion" type="wstring"> + <desc>Hardware version identifier. Internal use only for now.</desc> + </attribute> + + <attribute name="hardwareUUID" type="uuid" mod="string"> + <desc> + The UUID presented to the guest via memory tables, hardware and guest + properties. For most VMs this is the same as the @a id, but for VMs + which have been cloned or teleported it may be the same as the source + VM. The latter is because the guest shouldn't notice that it was + cloned or teleported. + </desc> + </attribute> + + <attribute name="CPUCount" type="unsigned long"> + <desc>Number of virtual CPUs in the VM.</desc> + </attribute> + + <attribute name="CPUHotPlugEnabled" type="boolean"> + <desc> + This setting determines whether VirtualBox allows CPU + hotplugging for this machine.</desc> + </attribute> + + <attribute name="CPUExecutionCap" type="unsigned long"> + <desc> + Means to limit the number of CPU cycles a guest can use. The unit + is percentage of host CPU cycles per second. The valid range + is 1 - 100. 100 (the default) implies no limit. + </desc> + </attribute> + + <attribute name="CPUIDPortabilityLevel" type="unsigned long"> + <desc>Virtual CPUID portability level, the higher number the fewer newer + or vendor specific CPU feature is reported to the guest (via the CPUID + instruction). The default level of zero (0) means that all virtualized + features supported by the host is pass thru to the guest. While the + three (3) is currently the level supressing the most features. + + Exactly which of the CPUID features are left out by the VMM at which + level is subject to change with each major version. + </desc> + </attribute> + + <attribute name="memorySize" type="unsigned long"> + <desc>System memory size in megabytes.</desc> + </attribute> + + <attribute name="memoryBalloonSize" type="unsigned long"> + <desc>Memory balloon size in megabytes.</desc> + </attribute> + + <attribute name="pageFusionEnabled" type="boolean"> + <desc> + This setting determines whether VirtualBox allows page + fusion for this machine (64-bit hosts only). + </desc> + </attribute> + + <attribute name="graphicsAdapter" type="IGraphicsAdapter" readonly="yes"> + <desc>Graphics adapter object.</desc> + </attribute> + + <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes"> + <desc>Object containing all BIOS settings.</desc> + </attribute> + + <attribute name="trustedPlatformModule" type="ITrustedPlatformModule" readonly="yes"> + <desc>Object containing all TPM settings.</desc> + </attribute> + + <attribute name="nonVolatileStore" type="INvramStore" readonly="yes"> + <desc>Object to manipulate data in the non volatile storage file.</desc> + </attribute> + + <attribute name="recordingSettings" type="IRecordingSettings" readonly="yes"> + <desc>Object containing all recording settings.</desc> + </attribute> + + <attribute name="firmwareType" type="FirmwareType"> + <desc>Type of firmware (such as legacy BIOS or EFI), used for initial + bootstrap in this VM.</desc> + </attribute> + + <attribute name="pointingHIDType" type="PointingHIDType"> + <desc>Type of pointing HID (such as mouse or tablet) used in this VM. + The default is typically "PS2Mouse" but can vary depending on the + requirements of the guest operating system.</desc> + </attribute> + + <attribute name="keyboardHIDType" type="KeyboardHIDType"> + <desc>Type of keyboard HID used in this VM. + The default is typically "PS2Keyboard" but can vary depending on the + requirements of the guest operating system.</desc> + </attribute> + + <attribute name="HPETEnabled" type="boolean"> + <desc>This attribute controls if High Precision Event Timer (HPET) is + enabled in this VM. Use this property if you want to provide guests + with additional time source, or if guest requires HPET to function correctly. + Default is false.</desc> + </attribute> + + <attribute name="chipsetType" type="ChipsetType"> + <desc>Chipset type used in this VM.</desc> + </attribute> + + <attribute name="iommuType" type="IommuType"> + <desc>IOMMU type used in this VM.</desc> + </attribute> + + <attribute name="snapshotFolder" type="wstring"> + <desc> + Full path to the directory used to store snapshot data + (differencing media and saved state files) of this machine. + + The initial value of this property is + <tt><</tt><link to="#settingsFilePath"> + path_to_settings_file</link><tt>>/<</tt> + <link to="#id">machine_uuid</link> + <tt>></tt>. + + Currently, it is an error to try to change this property on + a machine that has snapshots (because this would require to + move possibly large files to a different location). + A separate method will be available for this purpose later. + + <note> + Setting this property to @c null or to an empty string will restore + the initial value. + </note> + <note> + When setting this property, the specified path can be + absolute (full path) or relative to the directory where the + <link to="#settingsFilePath">machine settings file</link> + is located. When reading this property, a full path is + always returned. + </note> + <note> + The specified path may not exist, it will be created + when necessary. + </note> + </desc> + </attribute> + + <attribute name="VRDEServer" type="IVRDEServer" readonly="yes"> + <desc>VirtualBox Remote Desktop Extension (VRDE) server object.</desc> + </attribute> + + <attribute name="emulatedUSBCardReaderEnabled" type="boolean" default="false"/> + + <attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes"> + <desc>Array of media attached to this machine.</desc> + </attribute> + + <attribute name="USBControllers" type="IUSBController" readonly="yes" safearray="yes"> + <desc> + Array of USB controllers attached to this machine. + + <note> + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + </note> + </desc> + </attribute> + + <attribute name="USBDeviceFilters" type="IUSBDeviceFilters" readonly="yes"> + <desc> + Associated USB device filters object. + + <note> + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + </note> + </desc> + </attribute> + + <attribute name="audioSettings" type="IAudioSettings" readonly="yes"> + <desc> + The machine's audio settings. + </desc> + </attribute> + + <attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes"> + <desc>Array of storage controllers attached to this machine.</desc> + </attribute> + + <attribute name="settingsFilePath" type="wstring" readonly="yes" wrap-hint-server="limitedcaller"> + <desc> + Full name of the file containing machine settings data. + </desc> + </attribute> + + <attribute name="settingsAuxFilePath" type="wstring" readonly="yes" wrap-hint-server="limitedcaller" rest="suppress"> + <desc> + Full name of the file containing auxiliary machine settings data. + </desc> + </attribute> + + <attribute name="settingsModified" type="boolean" readonly="yes" rest="suppress"> + <desc> + Whether the settings of this machine have been modified + (but neither yet saved nor discarded). + <note> + Reading this property is only valid on instances returned + by <link to="ISession::machine"/> and on new machines + created by <link to="IVirtualBox::createMachine"/> or opened + by <link to="IVirtualBox::openMachine"/> but not + yet registered, or on unregistered machines after calling + <link to="IMachine::unregister"/>. For all other + cases, the settings can never be modified. + </note> + <note> + For newly created unregistered machines, the value of this + property is always @c true until <link to="#saveSettings"/> + is called (no matter if any machine settings have been + changed after the creation or not). For opened machines + the value is set to @c false (and then follows to normal rules). + </note> + </desc> + </attribute> + + <attribute name="sessionState" type="SessionState" readonly="yes"> + <desc>Current session state for this machine.</desc> + </attribute> + + <attribute name="sessionName" type="wstring" readonly="yes"> + <desc> + Name of the session. If <link to="#sessionState"/> is + Spawning or Locked, this attribute contains the + same value as passed to the + <link to="IMachine::launchVMProcess"/> method in the + @a name parameter. If the session was established with + <link to="IMachine::lockMachine" />, it is the name of the session + (if set, otherwise empty string). If + <link to="#sessionState"/> is SessionClosed, the value of this + attribute is an empty string. + </desc> + </attribute> + + <attribute name="sessionPID" type="unsigned long" readonly="yes"> + <desc> + Identifier of the session process. This attribute contains the + platform-dependent identifier of the process whose session was + used with <link to="IMachine::lockMachine" /> call. The returned + value is only valid if <link to="#sessionState"/> is Locked or + Unlocking by the time this property is read. + </desc> + </attribute> + + <attribute name="state" type="MachineState" readonly="yes"> + <desc>Current execution state of this machine.</desc> + </attribute> + + <attribute name="lastStateChange" type="long long" readonly="yes"> + <desc> + Timestamp of the last execution state change, + in milliseconds since 1970-01-01 UTC. + </desc> + </attribute> + + <attribute name="stateFilePath" type="wstring" readonly="yes"> + <desc> + Full path to the file that stores the execution state of + the machine when it is in either the <link to="MachineState_Saved"/> + or <link to="MachineState_AbortedSaved"/> state. + <note> + When the machine is not in the Saved or AbortedSaved state, this + attribute is an empty string. + </note> + </desc> + </attribute> + + <attribute name="logFolder" type="wstring" readonly="yes"> + <desc> + Full path to the folder that stores a set of rotated log files + recorded during machine execution. The most recent log file is + named <tt>VBox.log</tt>, the previous log file is + named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt> + in the current version). + </desc> + </attribute> + + <attribute name="currentSnapshot" type="ISnapshot" readonly="yes"> + <desc> + Current snapshot of this machine. This is @c null if the machine + currently has no snapshots. If it is not @c null, then it was + set by one of <link to="#takeSnapshot" />, <link to="#deleteSnapshot" /> + or <link to="#restoreSnapshot" />, depending on which was called last. + See <link to="ISnapshot"/> for details. + </desc> + </attribute> + + <attribute name="snapshotCount" type="unsigned long" readonly="yes"> + <desc> + Number of snapshots taken on this machine. Zero means the + machine doesn't have any snapshots. + </desc> + </attribute> + + <attribute name="currentStateModified" type="boolean" readonly="yes"> + <desc> + Returns @c true if the current state of the machine is not + identical to the state stored in the current snapshot. + + The current state is identical to the current snapshot only + directly after one of the following calls are made: + + <ul> + <li><link to="#restoreSnapshot"/> + </li> + <li><link to="#takeSnapshot"/> (issued on a "powered off" or "saved" + machine, for which <link to="#settingsModified"/> returns @c false) + </li> + </ul> + + The current state remains identical until one of the following + happens: + <ul> + <li>settings of the machine are changed</li> + <li>the saved state is deleted</li> + <li>the current snapshot is deleted</li> + <li>an attempt to execute the machine is made</li> + </ul> + + <note> + For machines that don't have snapshots, this property is + always @c false. + </note> + </desc> + </attribute> + + <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes"> + <desc> + Collection of shared folders for this machine (permanent shared + folders). These folders are shared automatically at machine startup + and available only to the guest OS installed within this machine. + + New shared folders are added to the collection using + <link to="#createSharedFolder"/>. Existing shared folders can be + removed using <link to="#removeSharedFolder"/>. + </desc> + </attribute> + + <attribute name="clipboardMode" type="ClipboardMode"> + <desc> + Synchronization mode between the host OS clipboard + and the guest OS clipboard. + </desc> + </attribute> + + <attribute name="clipboardFileTransfersEnabled" type="boolean"> + <desc> + Sets or retrieves whether clipboard file transfers are allowed or not. + + When set to @a true, clipboard file transfers between supported + host and guest OSes are allowed. + </desc> + </attribute> + + <attribute name="dnDMode" type="DnDMode"> + <desc> + Sets or retrieves the current drag'n drop mode. + </desc> + </attribute> + + <attribute name="teleporterEnabled" type="boolean"> + <desc> + When set to @a true, the virtual machine becomes a target teleporter + the next time it is powered on. This can only set to @a true when the + VM is in the @a PoweredOff or @a Aborted state. + + <!-- This property is automatically set to @a false when the VM is powered + on. (bird: This doesn't work yet ) --> + </desc> + </attribute> + + <attribute name="teleporterPort" type="unsigned long"> + <desc> + The TCP port the target teleporter will listen for incoming + teleportations on. + + 0 means the port is automatically selected upon power on. The actual + value can be read from this property while the machine is waiting for + incoming teleportations. + </desc> + </attribute> + + <attribute name="teleporterAddress" type="wstring"> + <desc> + The address the target teleporter will listen on. If set to an empty + string, it will listen on all addresses. + </desc> + </attribute> + + <attribute name="teleporterPassword" type="wstring"> + <desc> + The password to check for on the target teleporter. This is just a + very basic measure to prevent simple hacks and operators accidentally + beaming a virtual machine to the wrong place. + + Note that you SET a plain text password while reading back a HASHED + password. Setting a hashed password is currently not supported. + </desc> + </attribute> + + <attribute name="paravirtProvider" type="ParavirtProvider"> + <desc> + The paravirtualized guest interface provider. + </desc> + </attribute> + + <attribute name="RTCUseUTC" type="boolean"> + <desc> + When set to @a true, the RTC device of the virtual machine will run + in UTC time, otherwise in local time. Especially Unix guests prefer + the time in UTC. + </desc> + </attribute> + + <attribute name="IOCacheEnabled" type="boolean"> + <desc> + When set to @a true, the builtin I/O cache of the virtual machine + will be enabled. + </desc> + </attribute> + + <attribute name="IOCacheSize" type="unsigned long"> + <desc> + Maximum size of the I/O cache in MB. + </desc> + </attribute> + + <attribute name="PCIDeviceAssignments" type="IPCIDeviceAttachment" readonly="yes" safearray="yes"> + <desc>Array of PCI devices assigned to this machine, to get list of all + PCI devices attached to the machine use + <link to="IConsole::attachedPCIDevices"/> attribute, as this attribute + is intended to list only devices additional to what described in + virtual hardware config. Usually, this list keeps host's physical + devices assigned to the particular machine. + </desc> + </attribute> + + <attribute name="bandwidthControl" type="IBandwidthControl" readonly="yes"> + <desc> + Bandwidth control manager. + </desc> + </attribute> + + <attribute name="tracingEnabled" type="boolean"> + <desc> + Enables the tracing facility in the VMM (including PDM devices + + drivers). The VMM will consume about 0.5MB of more memory when + enabled and there may be some extra overhead from tracepoints that are + always enabled. + </desc> + </attribute> + + <attribute name="tracingConfig" type="wstring"> + <desc> + Tracepoint configuration to apply at startup when + <link to="IMachine::tracingEnabled" /> is true. The string specifies + a space separated of tracepoint group names to enable. The special + group 'all' enables all tracepoints. Check DBGFR3TracingConfig for + more details on available tracepoint groups and such. + + Note that on hosts supporting DTrace (or similar), a lot of the + tracepoints may be implemented exclusively as DTrace probes. So, the + effect of the same config may differ between Solaris and Windows for + example. + </desc> + </attribute> + + <attribute name="allowTracingToAccessVM" type="boolean"> + <desc> + Enables tracepoints in PDM devices and drivers to use the VMCPU or VM + structures when firing off trace points. This is especially useful + with DTrace tracepoints, as it allows you to use the VMCPU or VM + pointer to obtain useful information such as guest register state. + + This is disabled by default because devices and drivers normally has no + business accessing the VMCPU or VM structures, and are therefore unable + to get any pointers to these. + </desc> + </attribute> + + <attribute name="autostartEnabled" type="boolean"> + <desc> + Enables autostart of the VM during system boot. + </desc> + </attribute> + + <attribute name="autostartDelay" type="unsigned long"> + <desc> + Number of seconds to wait until the VM should be started during system boot. + </desc> + </attribute> + + <attribute name="autostopType" type="AutostopType"> + <desc> + Action type to do when the system is shutting down. + </desc> + </attribute> + + <attribute name="defaultFrontend" type="wstring"> + <desc> + Selects which VM frontend should be used by default when launching + this VM through the <link to="IMachine::launchVMProcess" /> method. + Empty or @c null strings do not define a particular default, it is up + to <link to="IMachine::launchVMProcess" /> to select one. See the + description of <link to="IMachine::launchVMProcess" /> for the valid + frontend types. + + This per-VM setting overrides the default defined by + <link to="ISystemProperties::defaultFrontend" /> attribute, and is + overridden by a frontend type passed to + <link to="IMachine::launchVMProcess" />. + </desc> + </attribute> + + <attribute name="USBProxyAvailable" type="boolean" readonly="yes"> + <desc> + Returns whether there is an USB proxy available. + </desc> + </attribute> + + <attribute name="VMProcessPriority" type="VMProcPriority"> + <desc> + Sets the priority of the VM process. It is a VM setting which can + be changed both before starting the VM and at runtime. + + The default value is 'Default', which selects the default + process priority. + + <result name="E_NOTIMPL"> + This attribute is currently not implemented. + </result> + </desc> + </attribute> + + <attribute name="paravirtDebug" type="wstring"> + <desc> + Debug parameters for the paravirtualized guest interface provider. + </desc> + </attribute> + + <attribute name="CPUProfile" type="wstring"> + <desc> + Experimental feature to select the guest CPU profile. The default + is "host", which indicates the host CPU. All other names are subject + to change. + + Use the <link to="ISystemProperties::getCPUProfiles" /> method to get + currently available CPU profiles. + </desc> + </attribute> + + <attribute name="stateKeyId" type="wstring" readonly="yes"> + <desc> + Key Id of the password used for encrypting the state file. + Internal use only for now. + </desc> + </attribute> + + <attribute name="stateKeyStore" type="wstring" readonly="yes"> + <desc> + Key store used for encrypting the state file. + Internal use only for now. + </desc> + </attribute> + <attribute name="logKeyId" type="wstring" readonly="yes"> + <desc> + Key Id of the password used for encrypting the log files. + Internal use only for now. + </desc> + </attribute> + + <attribute name="logKeyStore" type="wstring" readonly="yes"> + <desc> + Key store used for encrypting the log files. + Internal use only for now. + </desc> + </attribute> + + <attribute name="guestDebugControl" type="IGuestDebugControl" readonly="yes"> + <desc> + Guest debugging configuration. + </desc> + </attribute> + + <method name="lockMachine"> + <rest name="lock" request="post" path="/vms/{vmid}/actions/"/> + <desc> + Locks the machine for the given session to enable the caller + to make changes to the machine or start the VM or control + VM execution. + + There are two ways to lock a machine for such uses: + + <ul> + <li>If you want to make changes to the machine settings, + you must obtain an exclusive write lock on the machine + by setting @a lockType to @c Write. + + This will only succeed if no other process has locked + the machine to prevent conflicting changes. Only after + an exclusive write lock has been obtained using this method, one + can change all VM settings or execute the VM in the process + space of the session object. (Note that the latter is only of + interest if you actually want to write a new front-end for + virtual machines; but this API gets called internally by + the existing front-ends such as VBoxHeadless and the VirtualBox + GUI to acquire a write lock on the machine that they are running.) + + On success, write-locking the machine for a session creates + a second copy of the IMachine object. It is this second object + upon which changes can be made; in VirtualBox terminology, the + second copy is "mutable". It is only this second, mutable machine + object upon which you can call methods that change the + machine state. After having called this method, you can + obtain this second, mutable machine object using the + <link to="ISession::machine" /> attribute. + </li> + <li>If you only want to check the machine state or control + machine execution without actually changing machine + settings (e.g. to get access to VM statistics or take + a snapshot or save the machine state), then set the + @a lockType argument to @c Shared. + + If no other session has obtained a lock, you will obtain an + exclusive write lock as described above. However, if another + session has already obtained such a lock, then a link to that + existing session will be established which allows you + to control that existing session. + + To find out which type of lock was obtained, you can + inspect <link to="ISession::type" />, which will have been + set to either @c WriteLock or @c Shared. + </li> + </ul> + + In either case, you can get access to the <link to="IConsole" /> + object which controls VM execution. + + Also in all of the above cases, one must always call + <link to="ISession::unlockMachine" /> to release the lock on the machine, or + the machine's state will eventually be set to "Aborted". + + To change settings on a machine, the following sequence is typically + performed: + + <ol> + <li>Call this method to obtain an exclusive write lock for the current session.</li> + + <li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li> + + <li>Change the settings of the machine by invoking IMachine methods.</li> + + <li>Call <link to="IMachine::saveSettings" />.</li> + + <li>Release the write lock by calling <link to="ISession::unlockMachine"/>.</li> + </ol> + + <result name="E_UNEXPECTED"> + Virtual machine not registered. + </result> + <result name="E_ACCESSDENIED"> + Process not started by <link to="IMachine::launchVMProcess"/>. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session already open or being opened. + </result> + <result name="VBOX_E_VM_ERROR"> + Failed to assign machine to session. + </result> + </desc> + <param name="session" type="ISession" dir="in"> + <desc> + Session object for which the machine will be locked. + </desc> + </param> + <param name="lockType" type="LockType" dir="in"> + <desc> + If set to @c Write, then attempt to acquire an exclusive write lock or fail. + If set to @c Shared, then either acquire an exclusive write lock or establish + a link to an existing session. + </desc> + </param> + </method> + + <method name="launchVMProcess"> + <rest name="launch" request="post" path="/vms/{vmid}/actions/"/> + <desc> + Spawns a new process that will execute the virtual machine and obtains a shared + lock on the machine for the calling session. + + If launching the VM succeeds, the new VM process will create its own session + and write-lock the machine for it, preventing conflicting changes from other + processes. If the machine is already locked (because it is already running or + because another session has a write lock), launching the VM process will therefore + fail. Reversely, future attempts to obtain a write lock will also fail while the + machine is running. + + The caller's session object remains separate from the session opened by the new + VM process. It receives its own <link to="IConsole" /> object which can be used + to control machine execution, but it cannot be used to change all VM settings + which would be available after a <link to="#lockMachine" /> call. + + The caller must eventually release the session's shared lock by calling + <link to="ISession::unlockMachine" /> on the local session object once this call + has returned. However, the session's state (see <link to="ISession::state" />) + will not return to "Unlocked" until the remote session has also unlocked + the machine (i.e. the machine has stopped running). + + Launching a VM process 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 <link to="IProgress" /> object is returned to allow the caller to wait + for this asynchronous operation to be completed. Until then, the caller's + session object remains in the "Unlocked" state, and its <link to="ISession::machine" /> + and <link to="ISession::console" /> attributes cannot be accessed. + It is recommended to use <link to="IProgress::waitForCompletion" /> or + similar calls to wait for completion. Completion is signalled when the VM + is powered on. If launching the VM fails, error messages can be queried + via the progress object, if available. + + The progress object will have at least 2 sub-operations. The first + operation covers the period up to the new VM process calls powerUp. + The subsequent operations mirror the <link to="IConsole::powerUp"/> + progress object. Because <link to="IConsole::powerUp"/> may require + some extra sub-operations, the <link to="IProgress::operationCount"/> + may change at the completion of operation. + + For details on the teleportation progress operation, see + <link to="IConsole::powerUp"/>. + + The @a environmentChanges argument is a list of strings where every string contains + environment variable in the putenv style, i.e. "VAR=VALUE" for setting/replacing + and "VAR" for unsetting. These environment variables will be applied 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 list is empty, the server + environment is inherited by the started process as is. + + <result name="E_UNEXPECTED"> + Virtual machine not registered. + </result> + <result name="E_INVALIDARG"> + Invalid session type @a type. + </result> + <result name="VBOX_E_OBJECT_NOT_FOUND"> + No machine matching @a machineId found. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session already open or being opened. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Launching process for machine failed. + </result> + <result name="VBOX_E_VM_ERROR"> + Failed to assign machine to session. + </result> + </desc> + <param name="session" type="ISession" dir="in"> + <desc> + Client session object to which the VM process will be connected (this + must be in "Unlocked" state). + </desc> + </param> + <param name="name" type="wstring" dir="in"> + <desc> + Front-end to use for the new VM process. The following are currently supported: + <ul> + <li><tt>"gui"</tt>: VirtualBox Qt GUI front-end</li> + <li><tt>"headless"</tt>: VBoxHeadless (VRDE Server) front-end</li> + <li><tt>"sdl"</tt>: VirtualBox SDL front-end</li> + <li><tt>"emergencystop"</tt>: reserved value, used for aborting + the currently running VM or session owner. In this case the + @a session parameter may be @c null (if it is non-null it isn't + used in any way), and the @a progress return value will be always + @c null. The operation completes immediately.</li> + <li><tt>""</tt>: use the per-VM default frontend if set, otherwise + the global default defined in the system properties. If neither + are set, the API will launch a <tt>"gui"</tt> session, which may + fail if there is no windowing environment available. See + <link to="IMachine::defaultFrontend"/> and + <link to="ISystemProperties::defaultFrontend"/>.</li> + </ul> + </desc> + </param> + <param name="environmentChanges" type="wstring" safearray="yes" dir="in"> + <desc> + The list of putenv-style changes to the VM process environment. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="setBootOrder"> + <rest name="bootorder" request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Puts the given device to the specified position in + the boot order. + + To indicate that no device is associated with the given position, + <link to="DeviceType_Null"/> should be used. + + @todo setHardDiskBootOrder(), setNetworkBootOrder() + + <result name="E_INVALIDARG"> + Boot @a position out of range. + </result> + <result name="E_NOTIMPL"> + Booting from USB @a device currently not supported. + </result> + + </desc> + <param name="position" type="unsigned long" dir="in"> + <desc> + Position in the boot order (@c 1 to the total number of + devices the machine can boot from, as returned by + <link to="ISystemProperties::maxBootPosition"/>). + </desc> + </param> + <param name="device" type="DeviceType" dir="in"> + <desc> + The type of the device used to boot at the given position. + </desc> + </param> + </method> + + <method name="getBootOrder" const="yes"> + <rest name="bootorder" request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns the device type that occupies the specified + position in the boot order. + + @todo [remove?] + If the machine can have more than one device of the returned type + (such as hard disks), then a separate method should be used to + retrieve the individual device that occupies the given position. + + If here are no devices at the given position, then + <link to="DeviceType_Null"/> is returned. + + @todo getHardDiskBootOrder(), getNetworkBootOrder() + + <result name="E_INVALIDARG"> + Boot @a position out of range. + </result> + + </desc> + <param name="position" type="unsigned long" dir="in"> + <desc> + Position in the boot order (@c 1 to the total number of + devices the machine can boot from, as returned by + <link to="ISystemProperties::maxBootPosition"/>). + </desc> + </param> + <param name="device" type="DeviceType" dir="return"> + <desc> + Device at the given position. + </desc> + </param> + </method> + + <method name="attachDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Attaches a device and optionally mounts a medium to the given storage + controller (<link to="IStorageController" />, identified by @a name), + at the indicated port and device. + + This method is intended for managing storage devices in general while a + machine is powered off. It can be used to attach and detach fixed + and removable media. The following kind of media can be attached + to a machine: + + <ul> + <li>For fixed and removable media, you can pass in a medium that was + previously opened using <link to="IVirtualBox::openMedium" />. + </li> + + <li>Only for storage devices supporting removable media (such as + DVDs and floppies), you can also specify a null pointer to + indicate an empty drive or one of the medium objects listed + in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/> + arrays to indicate a host drive. + For removable devices, you can also use <link to="IMachine::mountMedium"/> + to change the media while the machine is running. + </li> + </ul> + + In a VM's default configuration of virtual machines, the secondary + master of the IDE controller is used for a CD/DVD drive. + + After calling this returns successfully, a new instance of + <link to="IMediumAttachment"/> will appear in the machine's list of medium + attachments (see <link to="IMachine::mediumAttachments"/>). + + See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more + information about attaching media. + + The specified device slot must not have a device attached to it, + or this method will fail. + + <note> + You cannot attach a device to a newly created machine until + this machine's settings are saved to disk using + <link to="#saveSettings"/>. + </note> + <note> + If the medium is being attached indirectly, a new differencing medium + will implicitly be created for it and attached instead. If the + changes made to the machine settings (including this indirect + attachment) are later cancelled using <link to="#discardSettings"/>, + this implicitly created differencing medium will implicitly + be deleted. + </note> + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range, or + file or UUID not found. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Machine must be registered before media can be attached. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + <result name="VBOX_E_OBJECT_IN_USE"> + A medium is already attached to this or another virtual machine. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller to attach the device to.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Port to attach the device to. For an IDE controller, 0 specifies + the primary controller and 1 specifies the secondary controller. + For a SCSI controller, this must range from 0 to 15; for a SATA controller, + from 0 to 29; for an SAS controller, from 0 to 7.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port to attach the device to. This is only + relevant for IDE controllers, for which 0 specifies the master device and + 1 specifies the slave device. For all other controller types, this must + be 0.</desc> + </param> + <param name="type" type="DeviceType" dir="in"> + <desc>Device type of the attached device. For media opened by + <link to="IVirtualBox::openMedium" />, this must match the device type + specified there.</desc> + </param> + <param name="medium" type="IMedium" dir="in"> + <desc>Medium to mount or @c null for an empty drive.</desc> + </param> + </method> + + <method name="attachDeviceWithoutMedium"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Attaches a device and optionally mounts a medium to the given storage + controller (<link to="IStorageController" />, identified by @a name), + at the indicated port and device. + + This method is intended for managing storage devices in general while a + machine is powered off. It can be used to attach and detach fixed + and removable media. The following kind of media can be attached + to a machine: + <ul> + <li> + For fixed and removable media, you can pass in a medium that was + previously opened using <link to="IVirtualBox::openMedium" />. + </li> + + <li>Only for storage devices supporting removable media (such as + DVDs and floppies) with an empty drive or one of the medium objects listed + in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/> + arrays to indicate a host drive. + For removable devices, you can also use <link to="IMachine::mountMedium"/> + to change the media while the machine is running. + </li> + </ul> + + In a VM's default configuration of virtual machines, the secondary + master of the IDE controller is used for a CD/DVD drive. + <link to="IMediumAttachment"/> will appear in the machine's list of medium + attachments (see <link to="IMachine::mediumAttachments"/>). + + See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more + information about attaching media. + + The specified device slot must not have a device attached to it, + or this method will fail. + <note> + You cannot attach a device to a newly created machine until + this machine's settings are saved to disk using + <link to="#saveSettings"/>. + </note> + <note> + If the medium is being attached indirectly, a new differencing medium + will implicitly be created for it and attached instead. If the + changes made to the machine settings (including this indirect + attachment) are later cancelled using <link to="#discardSettings"/>, + this implicitly created differencing medium will implicitly + be deleted. + </note> + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range, or + file or UUID not found. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Machine must be registered before media can be attached. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + <result name="VBOX_E_OBJECT_IN_USE"> + A medium is already attached to this or another virtual machine. + </result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller to attach the device to.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Port to attach the device to. For an IDE controller, 0 specifies + the primary controller and 1 specifies the secondary controller. + For a SCSI controller, this must range from 0 to 15; for a SATA controller, + from 0 to 29; for an SAS controller, from 0 to 7.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port to attach the device to. This is only + relevant for IDE controllers, for which 0 specifies the master device and + 1 specifies the slave device. For all other controller types, this must + be 0.</desc> + </param> + <param name="type" type="DeviceType" dir="in"> + <desc>Device type of the attached device. For media opened by + <link to="IVirtualBox::openMedium" />, this must match the device type + specified there.</desc> + </param> + </method> + + <method name="detachDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Detaches the device attached to a device slot of the specified bus. + + Detaching the device from the virtual machine is deferred. This means + that the medium remains associated with the machine when this method + returns and gets actually de-associated only after a successful + <link to="#saveSettings"/> call. See <link to="IMedium"/> + for more detailed information about attaching media. + + <note> + You cannot detach a device from a running machine. + </note> + <note> + Detaching differencing media implicitly created by <link + to="#attachDevice"/> for the indirect attachment using this + method will <b>not</b> implicitly delete them. The + <link to="IMedium::deleteStorage"/> operation should be + explicitly performed by the caller after the medium is successfully + detached and the settings are saved with + <link to="#saveSettings"/>, if it is the desired action. + </note> + + <result name="VBOX_E_INVALID_VM_STATE"> + Attempt to detach medium from a running virtual machine. + </result> + <result name="VBOX_E_OBJECT_NOT_FOUND"> + No medium attached to given slot/bus. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Medium format does not support storage deletion (only for implicitly + created differencing media, should not happen). + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller to detach the medium from.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Port number to detach the medium from.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot number to detach the medium from.</desc> + </param> + </method> + + <method name="passthroughDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets the passthrough mode of an existing DVD device. Changing the + setting while the VM is running is forbidden. The setting is only used + if at VM start the device is configured as a host DVD drive, in all + other cases it is ignored. The device must already exist; see + <link to="IMachine::attachDevice"/> for how to attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with <link to="IMachine::attachDevice" />. + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to modify an unregistered virtual machine. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Storage controller port.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port.</desc> + </param> + <param name="passthrough" type="boolean" dir="in"> + <desc>New value for the passthrough setting.</desc> + </param> + </method> + + <method name="temporaryEjectDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets the behavior for guest-triggered medium eject. In some situations + it is desirable that such ejects update the VM configuration, and in + others the eject should keep the VM configuration. The device must + already exist; see <link to="IMachine::attachDevice"/> for how to + attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with <link to="IMachine::attachDevice" />. + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to modify an unregistered virtual machine. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Storage controller port.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port.</desc> + </param> + <param name="temporaryEject" type="boolean" dir="in"> + <desc>New value for the eject behavior.</desc> + </param> + </method> + + <method name="nonRotationalDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets a flag in the device information which indicates that the medium + is not based on rotational technology, i.e. that the access times are + more or less independent of the position on the medium. This may or may + not be supported by a particular drive, and is silently ignored in the + latter case. At the moment only hard disks (which is a misnomer in this + context) accept this setting. Changing the setting while the VM is + running is forbidden. The device must already exist; see + <link to="IMachine::attachDevice"/> for how to attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with <link to="IMachine::attachDevice" />. + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to modify an unregistered virtual machine. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Storage controller port.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port.</desc> + </param> + <param name="nonRotational" type="boolean" dir="in"> + <desc>New value for the non-rotational device flag.</desc> + </param> + </method> + + <method name="setAutoDiscardForDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets a flag in the device information which indicates that the medium + supports discarding unused blocks (called trimming for SATA or unmap + for SCSI devices) .This may or may not be supported by a particular drive, + and is silently ignored in the latter case. At the moment only hard disks + (which is a misnomer in this context) accept this setting. Changing the + setting while the VM is running is forbidden. The device must already + exist; see <link to="IMachine::attachDevice"/> for how to attach a new + device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with <link to="IMachine::attachDevice" />. + + <result name="E_INVALIDARG"> + SATA device, SATA port, SCSI port out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to modify an unregistered virtual machine. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Storage controller port.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port.</desc> + </param> + <param name="discard" type="boolean" dir="in"> + <desc>New value for the discard device flag.</desc> + </param> + </method> + + <method name="setHotPluggableForDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets a flag in the device information which indicates that the attached + device is hot pluggable or not. This may or may not be supported by a + particular controller and/or drive, and is silently ignored in the + latter case. Changing the setting while the VM is running is forbidden. + The device must already exist; see <link to="IMachine::attachDevice"/> + for how to attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with <link to="IMachine::attachDevice" />. + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to modify an unregistered virtual machine. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Controller doesn't support hot plugging. + </result> + </desc> + + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Storage controller port.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port.</desc> + </param> + <param name="hotPluggable" type="boolean" dir="in"> + <desc>New value for the hot-pluggable device flag.</desc> + </param> + </method> + + <method name="setBandwidthGroupForDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets the bandwidth group of an existing storage device. + The device must already exist; see <link to="IMachine::attachDevice"/> + for how to attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with <link to="IMachine::attachDevice" />. + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to modify an unregistered virtual machine. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Storage controller port.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port.</desc> + </param> + <param name="bandwidthGroup" type="IBandwidthGroup" dir="in"> + <desc>New value for the bandwidth group or @c null for no group.</desc> + </param> + </method> + + <method name="setNoBandwidthGroupForDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets no bandwidth group for an existing storage device. + The device must already exist; see <link to="IMachine::attachDevice"/> + for how to attach a new device. + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with <link to="IMachine::attachDevice" />. + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to modify an unregistered virtual machine. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Storage controller port.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port.</desc> + </param> + </method> + + <method name="unmountMedium"> + <rest name="unmount" request="post" path="/vms/{vmid}/mediums/{mediumid}/actions/"/> + <desc> + Unmounts any currently mounted medium (<link to="IMedium" />, + identified by the given UUID @a id) to the given storage controller + (<link to="IStorageController" />, identified by @a name), + at the indicated port and device. The device must already exist; + + This method is intended only for managing removable media, where the + device is fixed but media is changeable at runtime (such as DVDs + and floppies). It cannot be used for fixed media such as hard disks. + + The @a controllerPort and @a device parameters specify the device slot + and have have the same meaning as with + <link to="IMachine::attachDevice" />. + + The specified device slot must have a medium mounted, which will be + unmounted. If there is no mounted medium it will do nothing. + See <link to="IMedium"/> for more detailed information about + attaching/unmounting media. + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to unmount medium that is not removable - not DVD or floppy. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + <result name="VBOX_E_OBJECT_IN_USE"> + Medium already attached to this or another virtual machine. + </result> + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Medium not attached to specified port, device, controller. + </result> + </desc> + + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller to unmount the medium from.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Port to unmount the medium from.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port to unmount the medium from.</desc> + </param> + <param name="force" type="boolean" dir="in"> + <desc>Allows to force unmount of a medium which is locked by + the device slot in the given port medium is attached to.</desc> + </param> + </method> + + <method name="mountMedium"> + <rest name="mount" request="post" path="/vms/{vmid}/mediums/{mediumid}/actions/"/> + <desc> + Mounts a medium (<link to="IMedium" />, identified + by the given UUID @a id) to the given storage controller + (<link to="IStorageController" />, identified by @a name), + at the indicated port and device. The device must already exist; + see <link to="IMachine::attachDevice"/> for how to attach a new device. + + This method is intended only for managing removable media, where the + device is fixed but media is changeable at runtime (such as DVDs + and floppies). It cannot be used for fixed media such as hard disks. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with <link to="IMachine::attachDevice" />. + + The specified device slot can have a medium mounted, which will be + unmounted first. Specifying a zero UUID (or an empty string) for + @a medium does just an unmount. + + See <link to="IMedium"/> for more detailed information about + attaching media. + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to attach medium to an unregistered virtual machine. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + <result name="VBOX_E_OBJECT_IN_USE"> + Medium already attached to this or another virtual machine. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller to attach the medium to.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Port to attach the medium to.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port to attach the medium to.</desc> + </param> + <param name="medium" type="IMedium" dir="in"> + <desc>Medium to mount or @c null for an empty drive.</desc> + </param> + <param name="force" type="boolean" dir="in"> + <desc>Allows to force unmount/mount of a medium which is locked by + the device slot in the given port to attach the medium to.</desc> + </param> + </method> + + <method name="getMedium" const="yes"> + <rest name="find" request="get" path="/vms/{vmid}/mediums/{mediumid}/"/> + <desc> + Returns the virtual medium attached to a device slot of the specified + bus. + + Note that if the medium was indirectly attached by + <link to="#mountMedium"/> to the given device slot then this + method will return not the same object as passed to the + <link to="#mountMedium"/> call. See <link to="IMedium"/> for + more detailed information about mounting a medium. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + No medium attached to given slot/bus. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller the medium is attached to.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Port to query.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port to query.</desc> + </param> + <param name="medium" type="IMedium" dir="return"> + <desc>Attached medium object.</desc> + </param> + </method> + + <method name="getMediumAttachmentsOfController" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns an array of medium attachments which are attached to the + the controller with the given name. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + A storage controller with given name doesn't exist. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + <param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/> + </method> + + <method name="getMediumAttachment" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns a medium attachment which corresponds to the controller with + the given name, on the given port and device slot. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + No attachment exists for the given controller/port/device combination. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + <param name="controllerPort" type="long" dir="in"/> + <param name="device" type="long" dir="in"/> + <param name="attachment" type="IMediumAttachment" dir="return"/> + </method> + + <method name="attachHostPCIDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Attaches host PCI device with the given (host) PCI address to the + PCI bus of the virtual machine. Please note, that this operation + is two phase, as real attachment will happen when VM will start, + and most information will be delivered as IHostPCIDevicePlugEvent + on IVirtualBox event source. + + <see><link to="IHostPCIDevicePlugEvent"/></see> + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine state is not stopped (PCI hotplug not yet implemented). + </result> + <result name="VBOX_E_PDM_ERROR"> + Virtual machine does not have a PCI controller allowing attachment of physical devices. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Hardware or host OS doesn't allow PCI device passthrough. + </result> + </desc> + <param name="hostAddress" type="long" dir="in"> + <desc>Address of the host PCI device.</desc> + </param> + <param name="desiredGuestAddress" type="long" dir="in"> + <desc>Desired position of this device on guest PCI bus.</desc> + </param> + <param name="tryToUnbind" type="boolean" dir="in"> + <desc>If VMM shall try to unbind existing drivers from the + device before attaching it to the guest.</desc> + </param> + </method> + + <method name="detachHostPCIDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Detach host PCI device from the virtual machine. + Also HostPCIDevicePlugEvent on IVirtualBox event source + will be delivered. As currently we don't support hot device + unplug, IHostPCIDevicePlugEvent event is delivered immediately. + + <see><link to="IHostPCIDevicePlugEvent"/></see> + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine state is not stopped (PCI hotplug not yet implemented). + </result> + <result name="VBOX_E_OBJECT_NOT_FOUND"> + This host device is not attached to this machine. + </result> + <result name="VBOX_E_PDM_ERROR"> + Virtual machine does not have a PCI controller allowing attachment of physical devices. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Hardware or host OS doesn't allow PCI device passthrough. + </result> + </desc> + <param name="hostAddress" type="long" dir="in"> + <desc>Address of the host PCI device.</desc> + </param> + </method> + + <method name="getNetworkAdapter" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns the network adapter associated with the given slot. + Slots are numbered sequentially, starting with zero. The total + number of adapters per machine is defined by the + <link to="ISystemProperties::getMaxNetworkAdapters"/> property, + so the maximum slot number is one less than that property's value. + + <result name="E_INVALIDARG"> + Invalid @a slot number. + </result> + + </desc> + <param name="slot" type="unsigned long" dir="in"/> + <param name="adapter" type="INetworkAdapter" dir="return"/> + </method> + + <method name="addStorageController"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Adds a new storage controller (SCSI, SAS or SATA controller) to the + machine and returns it as an instance of + <link to="IStorageController" />. + + @a name identifies the controller for subsequent calls such as + <link to="#getStorageControllerByName" />, + <link to="#getStorageControllerByInstance" />, + <link to="#removeStorageController" />, + <link to="#attachDevice" /> or <link to="#mountMedium" />. + + After the controller has been added, you can set its exact + type by setting the <link to="IStorageController::controllerType" />. + + <result name="VBOX_E_OBJECT_IN_USE"> + A storage controller with given name exists already. + </result> + <result name="E_INVALIDARG"> + Invalid @a controllerType. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + <param name="connectionType" type="StorageBus" dir="in"/> + <param name="controller" type="IStorageController" dir="return"/> + </method> + + <method name="getStorageControllerByName" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns a storage controller with the given name. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + A storage controller with given name doesn't exist. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + <param name="storageController" type="IStorageController" dir="return"/> + </method> + + <method name="getStorageControllerByInstance" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns a storage controller of a specific storage bus + with the given instance number. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + A storage controller with given instance number doesn't exist. + </result> + </desc> + <param name="connectionType" type="StorageBus" dir="in"/> + <param name="instance" type="unsigned long" dir="in"/> + <param name="storageController" type="IStorageController" dir="return"/> + </method> + + <method name="removeStorageController"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Removes a storage controller from the machine with all devices attached to it. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + A storage controller with given name doesn't exist. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Medium format does not support storage deletion (only for implicitly + created differencing media, should not happen). + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + </method> + + <method name="setStorageControllerBootable"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets the bootable flag of the storage controller with the given name. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + A storage controller with given name doesn't exist. + </result> + <result name="VBOX_E_OBJECT_IN_USE"> + Another storage controller is marked as bootable already. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + <param name="bootable" type="boolean" dir="in"/> + </method> + + <method name="addUSBController"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Adds a new USB controller to the machine and returns it as an instance of + <link to="IUSBController" />. + + <result name="VBOX_E_OBJECT_IN_USE"> + A USB controller with given type exists already. + </result> + <result name="E_INVALIDARG"> + Invalid @a controllerType. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + <param name="type" type="USBControllerType" dir="in"/> + <param name="controller" type="IUSBController" dir="return"/> + </method> + + <method name="removeUSBController"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Removes a USB controller from the machine. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + A USB controller with given type doesn't exist. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + </method> + + <method name="getUSBControllerByName" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns a USB controller with the given type. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + A USB controller with given name doesn't exist. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + <param name="controller" type="IUSBController" dir="return"/> + </method> + + <method name="getUSBControllerCountByType" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns the number of USB controllers of the given type attached to the VM. + </desc> + <param name="type" type="USBControllerType" dir="in"/> + <param name="controllers" type="unsigned long" dir="return"/> + </method> + + <method name="getSerialPort" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns the serial port associated with the given slot. + Slots are numbered sequentially, starting with zero. The total + number of serial ports per machine is defined by the + <link to="ISystemProperties::serialPortCount"/> property, + so the maximum slot number is one less than that property's value. + + <result name="E_INVALIDARG"> + Invalid @a slot number. + </result> + + </desc> + <param name="slot" type="unsigned long" dir="in"/> + <param name="port" type="ISerialPort" dir="return"/> + </method> + + <method name="getParallelPort" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns the parallel port associated with the given slot. + Slots are numbered sequentially, starting with zero. The total + number of parallel ports per machine is defined by the + <link to="ISystemProperties::parallelPortCount"/> property, + so the maximum slot number is one less than that property's value. + + <result name="E_INVALIDARG"> + Invalid @a slot number. + </result> + + </desc> + <param name="slot" type="unsigned long" dir="in"/> + <param name="port" type="IParallelPort" dir="return"/> + </method> + + <method name="getExtraDataKeys"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns an array representing the machine-specific extra data keys + which currently have values defined. + </desc> + <param name="keys" type="wstring" dir="return" safearray="yes"> + <desc>Array of extra data keys.</desc> + </param> + </method> + + <method name="getExtraData"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns associated machine-specific extra data. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + <result name="VBOX_E_FILE_ERROR"> + Settings file not accessible. + </result> + <result name="VBOX_E_XML_ERROR"> + Could not parse the settings file. + </result> + + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the data key to get.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc>Value of the requested data key.</desc> + </param> + </method> + + <method name="setExtraData"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets associated machine-specific extra data. + + If you pass @c null or an empty string as a key @a value, the given + @a key will be deleted. + + <note> + Key must contain printable (non-control) UTF-8 characters only. + </note> + <note> + Before performing the actual data change, this method will ask all + registered event listeners using the + <link to="IExtraDataCanChangeEvent"/> + notification for a permission. If one of the listeners refuses the + new value, the change will not be performed. + </note> + <note> + On success, the + <link to="IExtraDataChangedEvent"/> notification + is called to inform all registered listeners about a successful data + change. + </note> + <note> + This method can be called outside the machine session and therefore + it's a caller's responsibility to handle possible race conditions + when several clients change the same key at the same time. + </note> + + <result name="VBOX_E_FILE_ERROR"> + Settings file not accessible. + </result> + <result name="VBOX_E_XML_ERROR"> + Could not parse the settings file. + </result> + <result name="E_INVALIDARG"> + Key contains invalid characters. + </result> + + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the data key to set.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc>Value to assign to the key.</desc> + </param> + </method> + + <method name="getCPUProperty" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns the virtual CPU boolean value of the specified property. + + <result name="E_INVALIDARG"> + Invalid property. + </result> + + </desc> + <param name="property" type="CPUPropertyType" dir="in"> + <desc> + Property type to query. + </desc> + </param> + <param name="value" type="boolean" dir="return"> + <desc> + Property value. + </desc> + </param> + </method> + + <method name="setCPUProperty"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets the virtual CPU boolean value of the specified property. + + <result name="E_INVALIDARG"> + Invalid property. + </result> + + </desc> + <param name="property" type="CPUPropertyType" dir="in"> + <desc> + Property type to query. + </desc> + </param> + <param name="value" type="boolean" dir="in"> + <desc> + Property value. + </desc> + </param> + </method> + + <method name="getCPUIDLeafByOrdinal" const="yes"> + <desc> + Used to enumerate CPUID information override values. + + <result name="E_INVALIDARG"> + Invalid ordinal number is out of range. + </result> + </desc> + <param name="ordinal" type="unsigned long" dir="in"> + <desc> + The ordinal number of the leaf to get. + </desc> + </param> + <param name="idx" type="unsigned long" dir="out"> + <desc> + CPUID leaf index. + </desc> + </param> + <param name="idxSub" type="unsigned long" dir="out"> + <desc> + CPUID leaf sub-index. + </desc> + </param> + <param name="valEax" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register eax. + </desc> + </param> + <param name="valEbx" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register ebx. + </desc> + </param> + <param name="valEcx" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register ecx. + </desc> + </param> + <param name="valEdx" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register edx. + </desc> + </param> + </method> + + <method name="getCPUIDLeaf" const="yes"> + <desc> + Returns the virtual CPU cpuid information for the specified leaf. + + Currently supported index values for cpuid: + Standard CPUID leaves: 0 - 0x1f + Extended CPUID leaves: 0x80000000 - 0x8000001f + VIA CPUID leaves: 0xc0000000 - 0xc000000f + + See the Intel, AMD and VIA programmer's manuals for detailed information + about the CPUID instruction and its leaves. + <result name="E_INVALIDARG"> + Invalid index. + </result> + + </desc> + <param name="idx" type="unsigned long" dir="in"> + <desc> + CPUID leaf index. + </desc> + </param> + <param name="idxSub" type="unsigned long" dir="in"> + <desc> + CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. + </desc> + </param> + <param name="valEax" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register eax. + </desc> + </param> + <param name="valEbx" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register ebx. + </desc> + </param> + <param name="valEcx" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register ecx. + </desc> + </param> + <param name="valEdx" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register edx. + </desc> + </param> + </method> + + <method name="setCPUIDLeaf"> + <desc> + Sets the virtual CPU cpuid information for the specified leaf. Note that these values + are not passed unmodified. VirtualBox clears features that it doesn't support. + + Currently supported index values for cpuid: + Standard CPUID leaves: 0 - 0x1f + Extended CPUID leaves: 0x80000000 - 0x8000001f + VIA CPUID leaves: 0xc0000000 - 0xc000000f + + The subleaf index is only applicable to certain leaves (see manuals as this is + subject to change). + + See the Intel, AMD and VIA programmer's manuals for detailed information + about the cpuid instruction and its leaves. + + Do not use this method unless you know exactly what you're doing. Misuse can lead to + random crashes inside VMs. + <result name="E_INVALIDARG"> + Invalid index. + </result> + + </desc> + <param name="idx" type="unsigned long" dir="in"> + <desc> + CPUID leaf index. + </desc> + </param> + <param name="idxSub" type="unsigned long" dir="in"> + <desc> + CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. + The 0xffffffff causes it to remove all other subleaves before adding one + with sub-index 0. + </desc> + </param> + <param name="valEax" type="unsigned long" dir="in"> + <desc> + CPUID leaf value for register eax. + </desc> + </param> + <param name="valEbx" type="unsigned long" dir="in"> + <desc> + CPUID leaf value for register ebx. + </desc> + </param> + <param name="valEcx" type="unsigned long" dir="in"> + <desc> + CPUID leaf value for register ecx. + </desc> + </param> + <param name="valEdx" type="unsigned long" dir="in"> + <desc> + CPUID leaf value for register edx. + </desc> + </param> + </method> + + <method name="removeCPUIDLeaf"> + <desc> + Removes the virtual CPU cpuid leaf for the specified index + + <result name="E_INVALIDARG"> + Invalid index. + </result> + + </desc> + <param name="idx" type="unsigned long" dir="in"> + <desc> + CPUID leaf index. + </desc> + </param> + <param name="idxSub" type="unsigned long" dir="in"> + <desc> + CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. + The 0xffffffff value works like a wildcard. + </desc> + </param> + </method> + + <method name="removeAllCPUIDLeaves"> + <desc> + Removes all the virtual CPU cpuid leaves + </desc> + </method> + + <method name="getHWVirtExProperty" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns the value of the specified hardware virtualization boolean property. + + <result name="E_INVALIDARG"> + Invalid property. + </result> + + </desc> + <param name="property" type="HWVirtExPropertyType" dir="in"> + <desc> + Property type to query. + </desc> + </param> + <param name="value" type="boolean" dir="return"> + <desc> + Property value. + </desc> + </param> + </method> + + <method name="setHWVirtExProperty"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Sets a new value for the specified hardware virtualization boolean property. + + <result name="E_INVALIDARG"> + Invalid property. + </result> + + </desc> + <param name="property" type="HWVirtExPropertyType" dir="in"> + <desc> + Property type to set. + </desc> + </param> + <param name="value" type="boolean" dir="in"> + <desc> + New property value. + </desc> + </param> + </method> + + <method name="setSettingsFilePath"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Currently, it is an error to change this property on any machine. + Later this will allow setting a new path for the settings file, with + automatic relocation of all files (including snapshots and disk images) + which are inside the base directory. This operation is only allowed + when there are no pending unsaved settings. + + <note> + Setting this property to @c null or to an empty string is forbidden. + When setting this property, the specified path must be absolute. + The specified path may not exist, it will be created when necessary. + </note> + + <result name="E_NOTIMPL"> + The operation is not implemented yet. + </result> + </desc> + + <param name="settingsFilePath" type="wstring" dir="in"> + <desc>New settings file path, will be used to determine the new + location for the attached media if it is in the same directory or + below as the original settings file.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="saveSettings"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Saves any changes to machine settings made since the session + has been opened or a new machine has been created, or since the + last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>. + For registered machines, new settings become visible to all + other VirtualBox clients after successful invocation of this + method. + <note> + The method sends <link to="IMachineDataChangedEvent"/> + notification event after the configuration has been successfully + saved (only for registered machines). + </note> + <note> + Calling this method is only valid on instances returned + by <link to="ISession::machine"/> and on new machines + created by <link to="IVirtualBox::createMachine"/> but not + yet registered, or on unregistered machines after calling + <link to="IMachine::unregister"/>. + </note> + + <result name="VBOX_E_FILE_ERROR"> + Settings file not accessible. + </result> + <result name="VBOX_E_XML_ERROR"> + Could not parse the settings file. + </result> + <result name="E_ACCESSDENIED"> + Modification request refused. + </result> + + </desc> + </method> + + <method name="discardSettings"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Discards any changes to the machine settings made since the session + has been opened or since the last call to <link to="#saveSettings"/> + or <link to="#discardSettings"/>. + <note> + Calling this method is only valid on instances returned + by <link to="ISession::machine"/> and on new machines + created by <link to="IVirtualBox::createMachine"/> or + opened by <link to="IVirtualBox::openMachine"/> but not + yet registered, or on unregistered machines after calling + <link to="IMachine::unregister"/>. + </note> + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is not mutable. + </result> + + </desc> + </method> + + <method name="unregister" wrap-hint-server="limitedcaller,passcaller"> + <rest request="post" path="/vms/{vmid}/actions/"/> + <desc> + Unregisters a machine previously registered with + <link to="IVirtualBox::registerMachine"/> and optionally do additional + cleanup before the machine is unregistered. + + This method does not delete any files. It only changes the machine configuration and + the list of registered machines in the VirtualBox object. To delete the files which + belonged to the machine, including the XML file of the machine itself, call + <link to="#deleteConfig"/>, optionally with the array of IMedium objects which was returned + from this method. + + How thoroughly this method cleans up the machine configuration before unregistering + the machine depends on the @a cleanupMode argument. + + <ul> + <li>With "UnregisterOnly", the machine will only be unregistered, but no additional + cleanup will be performed. The call will fail if the machine has any snapshots or + any media attached (see <link to="IMediumAttachment" />). It is the responsibility + of the caller to delete all such configuration in this mode. In this mode, the API + behaves like the former @c IVirtualBox::unregisterMachine() API which it replaces.</li> + <li>With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved" + state or if it has snapshots or media attached. All media attached to the current machine + state or in snapshots will be detached. No medium objects will be returned; + all of the machine's media will remain open.</li> + <li>With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone", + except that all the hard disk medium objects which were detached from the machine will + be returned as an array. This allows for quickly passing them to the <link to="#deleteConfig" /> + API for closing and deletion.</li> + <li>With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except + that all media will be returned in the array, including removable media like DVDs and + floppies. This might be useful if the user wants to inspect in detail which media were + attached to the machine. Be careful when passing the media array to <link to="#deleteConfig" /> + in that case because users will typically want to preserve ISO and RAW image files.</li> + </ul> + + A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the + resulting IMedium array to <link to="#deleteConfig"/>. This way, the machine is completely + deleted with all its saved states and hard disk images, but images for removable + drives (such as ISO and RAW files) will remain on disk. + + This API does not verify whether the media files returned in the array are still + attached to other machines (i.e. shared between several machines). If such a shared + image is passed to <link to="#deleteConfig" /> however, closing the image will fail there + and the image will be silently skipped. + + This API may, however, move media from this machine's media registry to other media + registries (see <link to="IMedium" /> for details on media registries). For machines + created with VirtualBox 4.0 or later, if media from this machine's media registry + are also attached to another machine (shared attachments), each such medium will be + moved to another machine's registry. This is because without this machine's media + registry, the other machine cannot find its media any more and would become inaccessible. + + This API implicitly calls <link to="#saveSettings"/> to save all current machine settings + before unregistering it. It may also silently call <link to="#saveSettings"/> on other machines + if media are moved to other machines' media registries. + + After successful method invocation, the <link to="IMachineRegisteredEvent"/> event + is fired. + + The call will fail if the machine is currently locked (see <link to="ISession" />). + + <note> + If the given machine is inaccessible (see <link to="#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 + <b>any</b> method will return the "Object not ready" error. + </note> + + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Machine is currently locked for a session. + </result> + </desc> + + <param name="cleanupMode" type="CleanupMode" dir="in"> + <desc>How to clean up after the machine has been unregistered.</desc> + </param> + <param name="media" type="IMedium" safearray="yes" dir="return"> + <desc>List of media detached from the machine, depending on the @a cleanupMode parameter.</desc> + </param> + </method> + + <method name="deleteConfig"> + <rest name="remove" request="delete" path="/vms/{vmid}/"/> + <desc> + Deletes the files associated with this machine from disk. If medium objects are passed + in with the @a aMedia argument, they are closed and, if closing was successful, their + storage files are deleted as well. For convenience, this array of media files can be + the same as the one returned from a previous <link to="#unregister" /> call. + + This method must only be called on machines which are either write-locked (i.e. on instances + returned by <link to="ISession::machine"/>) or on unregistered machines (i.e. not yet + registered machines created by <link to="IVirtualBox::createMachine"/> or opened by + <link to="IVirtualBox::openMachine"/>, or after having called <link to="#unregister"/>). + + The following files will be deleted by this method: + <ul> + <li>If <link to="#unregister" /> had been previously called with a @a cleanupMode + argument other than "UnregisterOnly", this will delete all saved state files that + the machine had in use; possibly one if the machine was in either the "Saved" or + "AbortedSaved" state and one for each online snapshot that the machine had.</li> + <li>On each medium object passed in the @a aMedia array, this will call + <link to="IMedium::close" />. If that succeeds, this will attempt to delete the + medium's storage on disk. Since the <link to="IMedium::close"/> call will fail if the medium is still + in use, e.g. because it is still attached to a second machine; in that case the + storage will not be deleted.</li> + <li>Finally, the machine's own XML file will be deleted.</li> + </ul> + + Since deleting large disk image files can be a time-consuming I/O operation, this + method operates asynchronously and returns an IProgress object to allow the caller + to monitor the progress. There will be one sub-operation for each file that is + being deleted (saved state or medium storage file). + + <note> + <link to="#settingsModified"/> will return @c true after this + method successfully returns. + </note> + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine is registered but not write-locked. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Could not delete the settings file. + </result> + </desc> + <param name="media" type="IMedium" safearray="yes" dir="in"> + <desc>List of media to be closed and whose storage files will be deleted.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="exportTo"> + <rest name="export" request="post" path="/vms/{vmid}/actions/"/> + <desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the + steps required to export VirtualBox machines to OVF. + </desc> + + <param name="appliance" type="IAppliance" dir="in"> + <desc>Appliance to export this machine to.</desc> + </param> + <param name="location" type="wstring" dir="in"> + <desc>The target location.</desc> + </param> + <param name="description" type="IVirtualSystemDescription" dir="return"> + <desc>VirtualSystemDescription object which is created for this machine.</desc> + </param> + </method> + + <method name="findSnapshot"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns a snapshot of this machine with the given name or UUID. + + Returns a snapshot of this machine with the given UUID. + A @c null argument can be used to obtain the first snapshot + taken on this machine. To traverse the whole tree of snapshots + starting from the root, inspect the root snapshot's + <link to="ISnapshot::children" /> attribute and recurse over those children. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Virtual machine has no snapshots or snapshot not found. + </result> + + </desc> + <param name="nameOrId" type="wstring" dir="in"> + <desc>What to search for. Name or UUID of the snapshot to find</desc> + </param> + <param name="snapshot" type="ISnapshot" dir="return"> + <desc>Snapshot object with the given name.</desc> + </param> + </method> + + <method name="createSharedFolder"> + <rest request="post" path="/vms/{vmid}/methods/"/> + <desc> + Creates a new permanent 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 + <link to="ISharedFolder"/> to read more about logical names. + + <result name="VBOX_E_OBJECT_IN_USE"> + Shared folder already exists. + </result> + <result name="VBOX_E_FILE_ERROR"> + Shared folder @a hostPath not accessible. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Unique logical name of the shared folder.</desc> + </param> + <param name="hostPath" type="wstring" dir="in"> + <desc>Full path to the shared folder in the host file system.</desc> + </param> + <param name="writable" type="boolean" dir="in"> + <desc>Whether the share is writable or read-only.</desc> + </param> + <param name="automount" type="boolean" dir="in"> + <desc>Whether the share gets automatically mounted by the guest + or not.</desc> + </param> + <param name="autoMountPoint" type="wstring" dir="in"> + <desc>Where the guest should automatically mount the folder, if possible. + For Windows and OS/2 guests this should be a drive letter, while other + guests it should be a absolute directory. + </desc> + </param> + </method> + + <method name="removeSharedFolder"> + <rest request="delete" path="/vms/{vmid}/methods/"/> + <desc> + Removes the permanent shared folder with the given name previously + created by <link to="#createSharedFolder"/> from the collection of + shared folders and stops sharing it. + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is not mutable. + </result> + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Shared folder @a name does not exist. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Logical name of the shared folder to remove.</desc> + </param> + </method> + + <method name="canShowConsoleWindow"> + <desc> + Returns @c true if the VM console process can activate the + console window and bring it to foreground on the desktop of + the host PC. + <note> + This method will fail if a session for this machine is not + currently open. + </note> + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + + </desc> + <param name="canShow" type="boolean" dir="return"> + <desc> + @c true if the console window can be shown and @c false otherwise. + </desc> + </param> + </method> + + <method name="showConsoleWindow"> + <desc> + Activates the console window and brings it to foreground on + the desktop of the host PC. Many modern window managers on + many platforms implement some sort of focus stealing + prevention logic, so that it may be impossible to activate + a window without the help of the currently active + application. In this case, this method will return a non-zero + identifier that represents the top-level window of the VM + console process. The caller, if it represents a currently + active process, is responsible to use this identifier (in a + platform-dependent manner) to perform actual window + activation. + <note> + This method will fail if a session for this machine is not + currently open. + </note> + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + + </desc> + <param name="winId" type="long long" dir="return"> + <desc> + Platform-dependent identifier of the top-level VM console + window, or zero if this method has performed all actions + necessary to implement the <i>show window</i> semantics for + the given platform and/or VirtualBox front-end. + </desc> + </param> + </method> + + <method name="getGuestProperty" const="yes"> + <rest name="Property" request="get" path="/vms/{vmid}/guest/"/> + + <desc> + Reads an entry from the machine's guest property store. + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc> + The name of the property to read. + </desc> + </param> + <param name="value" type="wstring" dir="out"> + <desc> + The value of the property. If the property does not exist then this + will be empty. + </desc> + </param> + <param name="timestamp" type="long long" dir="out"> + <desc> + The time at which the property was last modified, as seen by the + server process. + </desc> + </param> + <param name="flags" type="wstring" dir="out"> + <desc> + Additional property parameters, passed as a comma-separated list of + "name=value" type entries. + </desc> + </param> + </method> + + <method name="getGuestPropertyValue" const="yes"> + <desc> + Reads a value from the machine's guest property store. + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + + </desc> + <param name="property" type="wstring" dir="in"> + <desc> + The name of the property to read. + </desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc> + The value of the property. If the property does not exist then this + will be empty. + </desc> + </param> + </method> + + <method name="getGuestPropertyTimestamp" const="yes"> + <desc> + Reads a property timestamp from the machine's guest property store. + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + + </desc> + <param name="property" type="wstring" dir="in"> + <desc> + The name of the property to read. + </desc> + </param> + <param name="value" type="long long" dir="return"> + <desc> + The timestamp. If the property does not exist then this will be + empty. + </desc> + </param> + </method> + + <method name="setGuestProperty"> + <rest name="Property" request="patch" path="/vms/{vmid}/guest/"/> + <desc> + Sets, changes or deletes an entry in the machine's guest property + store. + + <result name="E_ACCESSDENIED"> + Property cannot be changed. + </result> + <result name="E_INVALIDARG"> + Invalid @a flags. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is not mutable or session not open. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Cannot set transient property when machine not running. + </result> + + </desc> + <param name="property" type="wstring" dir="in"> + <desc> + The name of the property to set, change or delete. + </desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc> + The new value of the property to set, change or delete. If the + property does not yet exist and value is non-empty, it will be + created. If the value is @c null or empty, the property will be + deleted if it exists. + </desc> + </param> + <param name="flags" type="wstring" dir="in"> + <desc> + Additional property parameters, passed as a comma-separated list of + "name=value" type entries. + </desc> + </param> + </method> + + <method name="setGuestPropertyValue"> + <desc> + Sets or changes a value in the machine's guest property + store. The flags field will be left unchanged or created empty for a + new property. + + <result name="E_ACCESSDENIED"> + Property cannot be changed. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is not mutable or session not open. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Cannot set transient property when machine not running. + </result> + </desc> + + <param name="property" type="wstring" dir="in"> + <desc> + The name of the property to set or change. + </desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc> + The new value of the property to set or change. If the + property does not yet exist and value is non-empty, it will be + created. + </desc> + </param> + </method> + + <method name="deleteGuestProperty" const="yes"> + <rest name="Property" request="delete" path="/vms/{vmid}/guest/"/> + <desc> + Deletes an entry from the machine's guest property store. + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc> + The name of the property to delete. + </desc> + </param> + </method> + + <method name="enumerateGuestProperties" const="yes"> + <desc> + Return a list of the guest properties matching a set of patterns along + with their values, timestamps and flags. + </desc> + <param name="patterns" type="wstring" dir="in"> + <desc> + The patterns to match the properties against, separated by '|' + characters. If this is empty or @c null, all properties will match. + </desc> + </param> + <param name="names" type="wstring" dir="out" safearray="yes"> + <desc> + The names of the properties returned. + </desc> + </param> + <param name="values" type="wstring" dir="out" safearray="yes"> + <desc> + The values of the properties returned. The array entries match the + corresponding entries in the @a name array. + </desc> + </param> + <param name="timestamps" type="long long" dir="out" safearray="yes"> + <desc> + The timestamps of the properties returned. The array entries match + the corresponding entries in the @a name array. + </desc> + </param> + <param name="flags" type="wstring" dir="out" safearray="yes"> + <desc> + The flags of the properties returned. The array entries match the + corresponding entries in the @a name array. + </desc> + </param> + </method> + + <method name="querySavedGuestScreenInfo" const="yes"> + <desc> + Returns the guest dimensions from the saved state. + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc> + Saved guest screen to query info from. + </desc> + </param> + <param name="originX" type="unsigned long" dir="out"> + <desc> + The X position of the guest monitor top left corner. + </desc> + </param> + <param name="originY" type="unsigned long" dir="out"> + <desc> + The Y position of the guest monitor top left corner. + </desc> + </param> + <param name="width" type="unsigned long" dir="out"> + <desc> + Guest width at the time of the saved state was taken. + </desc> + </param> + <param name="height" type="unsigned long" dir="out"> + <desc> + Guest height at the time of the saved state was taken. + </desc> + </param> + <param name="enabled" type="boolean" dir="out"> + <desc> + Whether the monitor is enabled in the guest. + </desc> + </param> + </method> + + <method name="readSavedThumbnailToArray"> + <desc> + Thumbnail is retrieved to an array of bytes in the requested format. + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc> + Saved guest screen to read from. + </desc> + </param> + <param name="bitmapFormat" type="BitmapFormat" dir="in"> + <desc> + The requested format. + </desc> + </param> + <param name="width" type="unsigned long" dir="out"> + <desc> + Bitmap width. + </desc> + </param> + <param name="height" type="unsigned long" dir="out"> + <desc> + Bitmap height. + </desc> + </param> + <param name="data" type="octet" safearray="yes" dir="return"> + <desc> + Array with resulting bitmap data. + </desc> + </param> + </method> + + <method name="querySavedScreenshotInfo"> + <desc> + Returns available formats and size of the screenshot from saved state. + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc> + Saved guest screen to query info from. + </desc> + </param> + <param name="width" type="unsigned long" dir="out"> + <desc> + Image width. + </desc> + </param> + <param name="height" type="unsigned long" dir="out"> + <desc> + Image height. + </desc> + </param> + <param name="bitmapFormats" type="BitmapFormat" safearray="yes" dir="return"> + <desc> + Formats supported by readSavedScreenshotToArray. + </desc> + </param> + </method> + + <method name="readSavedScreenshotToArray"> + <desc> + Screenshot in requested format is retrieved to an array of bytes. + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc> + Saved guest screen to read from. + </desc> + </param> + <param name="bitmapFormat" type="BitmapFormat" dir="in"> + <desc> + The requested format. + </desc> + </param> + <param name="width" type="unsigned long" dir="out"> + <desc> + Image width. + </desc> + </param> + <param name="height" type="unsigned long" dir="out"> + <desc> + Image height. + </desc> + </param> + <param name="data" type="octet" dir="return" safearray="yes"> + <desc> + Array with resulting image data. + </desc> + </param> + </method> + + <method name="hotPlugCPU"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Plugs a CPU into the machine. + </desc> + <param name="cpu" type="unsigned long" dir="in"> + <desc> + The CPU id to insert. + </desc> + </param> + </method> + + <method name="hotUnplugCPU"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Removes a CPU from the machine. + </desc> + <param name="cpu" type="unsigned long" dir="in"> + <desc> + The CPU id to remove. + </desc> + </param> + </method> + + <method name="getCPUStatus"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns the current status of the given CPU. + </desc> + <param name="cpu" type="unsigned long" dir="in"> + <desc> + The CPU id to check for. + </desc> + </param> + <param name="attached" type="boolean" dir="return"> + <desc> + Status of the CPU. + </desc> + </param> + </method> + + <method name="getEffectiveParavirtProvider" const="yes"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Returns the effective paravirtualization provider for this VM. + </desc> + <param name="paravirtProvider" type="ParavirtProvider" dir="return"> + <desc> + The effective paravirtualization provider for this VM. + </desc> + </param> + </method> + + <method name="queryLogFilename"> + <rest request="get" path="/vms/{vmid}/logs/"/> + <desc> + Queries for the VM log file name of an given index. Returns an empty + string if a log file with that index doesn't exists. + </desc> + <param name="idx" type="unsigned long" dir="in"> + <desc> + Which log file name to query. 0=current log file. + </desc> + </param> + <param name="filename" type="wstring" dir="return"> + <desc> + On return the full path to the log file or an empty string on error. + </desc> + </param> + </method> + + <method name="readLog"> + <desc> + Reads the VM log file. The chunk size is limited, so even if you + ask for a big piece there might be less data returned. + </desc> + <param name="idx" type="unsigned long" dir="in"> + <desc> + Which log file to read. 0=current log file. + </desc> + </param> + <param name="offset" type="long long" dir="in"> + <desc> + Offset in the log file. + </desc> + </param> + <param name="size" type="long long" dir="in"> + <desc> + Chunk size to read in the log file. + </desc> + </param> + <param name="data" type="octet" dir="return" safearray="yes"> + <desc> + Data read from the log file. A data size of 0 means end of file + if the requested chunk size was not 0. This is the unprocessed + file data, i.e. the line ending style depends on the platform of + the system the server is running on. + </desc> + </param> + </method> + + <method name="cloneTo"> + <rest name="clone" request="put" path="/vms/{vmid}/actions/"/> + <desc> + Creates a clone of this machine, either as a full clone (which means + creating independent copies of the hard disk media, save states and so + on), or as a linked clone (which uses its own differencing media, + sharing the parent media with the source machine). + + The target machine object must have been created previously with <link + to="IVirtualBox::createMachine"/>, and all the settings will be + transferred except the VM name and the hardware UUID. You can set the + VM name and the new hardware UUID when creating the target machine. The + network MAC addresses are newly created for all enabled network + adapters. You can change that behaviour with the options parameter. + The operation is performed asynchronously, so the machine object will + be not be usable until the @a progress object signals completion. + + <result name="E_INVALIDARG"> + @a target is @c null. + </result> + </desc> + + <param name="target" type="IMachine" dir="in"> + <desc>Target machine object.</desc> + </param> + <param name="mode" type="CloneMode" dir="in"> + <desc>Which states should be cloned.</desc> + </param> + <param name="options" type="CloneOptions" dir="in" safearray="yes"> + <desc>Options for the cloning operation.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="moveTo"> + <rest name="move" request="post" path="/vms/{vmid}/actions/"/> + <desc> + Move machine on to new place/folder + </desc> + + <param name="folder" type="wstring" dir="in"> + <desc>Target folder where machine is moved. May be the same folder + where the VM already is located or the empty string, in which + case the machine is kept in this location and the disk images + and other files which are stored elsewhere are moved.</desc> + </param> + + <param name="type" type="wstring" dir="in"> + <desc>Type of moving. + Possible values: + basic - Only the files which belong solely to this machine + are moved from the original machine's folder to + a new folder. + </desc> + </param> + + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="saveState"> + <rest name="save" request="post" path="/vms/{vmid}/actions/"/> + <desc> + Saves the current execution state of a running virtual machine + and stops its execution. + + After this operation completes, the machine will go to the + Saved state. The next time it is powered up this state will + be restored and the machine will continue its execution from + the place where it was saved. + + This operation differs from taking a snapshot to the effect + that it doesn't create new differencing media. Also, once + the machine is powered up from the state saved using this method, + the saved state is deleted, so it will be impossible to return + to this state later. + + <note> + On success, this method implicitly calls + <link to="#saveSettings"/> to save all current machine + settings (including runtime changes to the DVD medium, etc.). + Together with the impossibility to change any VM settings when it is + in the Saved state, this guarantees adequate hardware + configuration of the machine when it is restored from the saved + state file. + </note> + + <note> + The machine must be in the Running or Paused state, otherwise + the operation will fail. + </note> + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine state neither Running nor Paused. + </result> + <result name="VBOX_E_FILE_ERROR"> + Failed to create directory for saved state file. + </result> + + <see><link to="#takeSnapshot"/></see> + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="adoptSavedState"> + <desc> + Associates the given saved state file to the virtual machine. + + On success, the machine will go to the Saved state. The next time it is + powered up it will be restored from the adopted saved state and + continue execution from the place where the saved state file was + created. + + The specified saved state file path may be absolute or relative to the + folder the VM normally saves the state to (usually, + <link to="#snapshotFolder"/>). + + <note> + It's a caller's responsibility to make sure the given saved state + file is compatible with the settings of this virtual machine that + represent its virtual hardware (memory size, storage disk configuration + etc.). If there is a mismatch, the behavior of the virtual machine + is undefined. + </note> + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine state neither PoweredOff nor Aborted. + </result> + </desc> + <param name="savedStateFile" type="wstring" dir="in"> + <desc>Path to the saved state file to adopt.</desc> + </param> + </method> + + <method name="discardSavedState"> + <rest request="post" path="/vms/{vmid}/actions/"/> + <desc> + Forcibly resets the machine to "Powered Off" state if it is + currently in the "Saved" state previously created by <link to="#saveState"/>) + or in the "AbortedSaved" state. The next time the machine is powered up + a clean boot will occur. + <note> + This operation is equivalent to resetting or powering off + the machine without doing a proper shutdown of the guest + operating system; as with resetting a running phyiscal + computer, it can can lead to data loss. + </note> + If @a fRemoveFile is @c true, the file in the machine directory + into which the machine state was saved is also deleted. If + this is @c false, then the state can be recovered and later + re-inserted into a machine using <link to="#adoptSavedState" />. + The location of the file can be found in the + <link to="#stateFilePath" /> attribute. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in either the Saved or AbortedSaved state. + </result> + </desc> + <param name="fRemoveFile" type="boolean" dir="in" > + <desc>Whether to also remove the saved state file.</desc> + </param> + </method> + + <method name="takeSnapshot"> + <rest request="put" path="/vms/{vmid}/actions/"/> + <desc> + Saves the current execution state + and all settings of the machine and creates differencing images + for all normal (non-independent) media. + See <link to="ISnapshot" /> for an introduction to snapshots. + + This method can be called for a PoweredOff, Saved (see + <link to="#saveState"/>), AbortedSaved, Running or + Paused virtual machine. When the machine is PoweredOff, an + offline snapshot is created. When the machine is Running a live + snapshot is created, and an online snapshot is created when Paused. + + The taken snapshot is always based on the + <link to="#currentSnapshot">current snapshot</link> + of the associated virtual machine and becomes a new current snapshot. + + <note> + This method implicitly calls <link to="#saveSettings"/> to + save all current machine settings before taking an offline snapshot. + </note> + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine currently changing state. + </result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Short name for the snapshot.</desc> + </param> + <param name="description" type="wstring" dir="in"> + <desc>Optional description of the snapshot.</desc> + </param> + <param name="pause" type="boolean" dir="in"> + <desc>Whether the VM should be paused while taking the snapshot. Only + relevant when the VM is running, and distinguishes between online + (@c true) and live (@c false) snapshots. When the VM is not running + the result is always an offline snapshot.</desc> + </param> + <param name="id" type="uuid" mod="string" dir="out"> + <desc>UUID of the snapshot which will be created. Useful for follow-up + operations after the snapshot has been created.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="deleteSnapshot"> + <rest request="delete" path="/vms/{vmid}/actions/"/> + <desc> + Starts deleting the specified snapshot asynchronously. + See <link to="ISnapshot" /> for an introduction to snapshots. + + The execution state and settings of the associated machine stored in + the snapshot will be deleted. The contents of all differencing media of + this snapshot will be merged with the contents of their dependent child + media to keep the medium chain valid (in other words, all changes + represented by media being deleted will be propagated to their child + medium). After that, this snapshot's differencing medium will be + deleted. The parent of this snapshot will become a new parent for all + its child snapshots. + + If the deleted snapshot is the current one, its parent snapshot will + become a new current snapshot. The current machine state is not directly + affected in this case, except that currently attached differencing + media based on media of the deleted snapshot will be also merged as + described above. + + If the deleted snapshot is the first or current snapshot, then the + respective IMachine attributes will be adjusted. Deleting the current + snapshot will also implicitly call <link to="#saveSettings"/> + to make all current machine settings permanent. + + Deleting a snapshot has the following preconditions: + + <ul> + <li>Child media of all normal media of the deleted snapshot + must be accessible (see <link to="IMedium::state"/>) for this + operation to succeed. If only one running VM refers to all images + which participates in merging the operation can be performed while + the VM is running. Otherwise all virtual machines whose media are + directly or indirectly based on the media of deleted snapshot must + be powered off. In any case, online snapshot deleting usually is + slower than the same operation without any running VM.</li> + + <li>You cannot delete the snapshot if a medium attached to it has + more than one child medium (differencing images) because otherwise + merging would be impossible. This might be the case if there is + more than one child snapshot or differencing images were created + for other reason (e.g. implicitly because of multiple machine + attachments).</li> + </ul> + + The virtual machine's <link to="#state">state</link> is + changed to "DeletingSnapshot", "DeletingSnapshotOnline" or + "DeletingSnapshotPaused" while this operation is in progress. + + <note> + Merging medium contents can be very time and disk space + consuming, if these media are big in size and have many + children. However, if the snapshot being deleted is the last + (head) snapshot on the branch, the operation will be rather + quick. + </note> + <result name="VBOX_E_INVALID_VM_STATE"> + The running virtual machine prevents deleting this snapshot. This + happens only in very specific situations, usually snapshots can be + deleted without trouble while a VM is running. The error message + text explains the reason for the failure. + </result> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc>UUID of the snapshot to delete.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="deleteSnapshotAndAllChildren"> + <rest request="post" path="/vms/{vmid}/actions/"/> + <desc> + Starts deleting the specified snapshot and all its children + asynchronously. See <link to="ISnapshot" /> for an introduction to + snapshots. The conditions and many details are the same as with + <link to="#deleteSnapshot"/>. + + This operation is very fast if the snapshot subtree does not include + the current state. It is still significantly faster than deleting the + snapshots one by one if the current state is in the subtree and there + are more than one snapshots from current state to the snapshot which + marks the subtree, since it eliminates the incremental image merging. + + <note>This API method is right now not implemented!</note> + + <result name="VBOX_E_INVALID_VM_STATE"> + The running virtual machine prevents deleting this snapshot. This + happens only in very specific situations, usually snapshots can be + deleted without trouble while a VM is running. The error message + text explains the reason for the failure. + </result> + <result name="E_NOTIMPL"> + The method is not implemented yet. + </result> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc>UUID of the snapshot to delete, including all its children.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="deleteSnapshotRange"> + <rest request="post" path="/vms/{vmid}/actions/"/> + <desc> + Starts deleting the specified snapshot range. This is limited to + linear snapshot lists, which means there may not be any other child + snapshots other than the direct sequence between the start and end + snapshot. If the start and end snapshot point to the same snapshot this + method is completely equivalent to <link to="#deleteSnapshot"/>. See + <link to="ISnapshot" /> for an introduction to snapshots. The + conditions and many details are the same as with + <link to="#deleteSnapshot"/>. + + This operation is generally faster than deleting snapshots one by one + and often also needs less extra disk space before freeing up disk space + by deleting the removed disk images corresponding to the snapshot. + + <note>This API method is right now not implemented!</note> + + <result name="VBOX_E_INVALID_VM_STATE"> + The running virtual machine prevents deleting this snapshot. This + happens only in very specific situations, usually snapshots can be + deleted without trouble while a VM is running. The error message + text explains the reason for the failure. + </result> + <result name="E_NOTIMPL"> + The method is not implemented yet. + </result> + </desc> + <param name="startId" type="uuid" mod="string" dir="in"> + <desc>UUID of the first snapshot to delete.</desc> + </param> + <param name="endId" type="uuid" mod="string" dir="in"> + <desc>UUID of the last snapshot to delete.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="restoreSnapshot"> + <rest request="post" path="/vms/{vmid}/actions/"/> + <desc> + Starts resetting the machine's current state to the state contained + in the given snapshot, asynchronously. All current settings of the + machine will be reset and changes stored in differencing media + will be lost. + See <link to="ISnapshot" /> for an introduction to snapshots. + + After this operation is successfully completed, new empty differencing + media are created for all normal media of the machine. + + If the given snapshot is an online snapshot, the machine will go to + the <link to="MachineState_Saved">Saved</link> state, so that the + next time it is powered on, the execution state will be restored + from the state of the snapshot. + + <note> + The machine must not be running, otherwise the operation will fail. + </note> + + <note> + If the machine is in the <link to="MachineState_Saved">Saved</link> + state prior to this operation, the saved state file will be implicitly + deleted (as if <link to="IMachine::discardSavedState"/> were + called). + </note> + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is running. + </result> + </desc> + <param name="snapshot" type="ISnapshot" dir="in"> + <desc>The snapshot to restore the VM state from.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="applyDefaults"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Applies the defaults for the configured guest OS type. This is + primarily for getting sane settings straight after creating a + new VM, but it can also be applied later. + + <note> + This is primarily a shortcut, centralizing the tedious job of + getting the recommended settings and translating them into + settings updates. The settings are made at the end of the call, + but not saved. + </note> + + <result name="E_FAIL"> + General error. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + The machine is in invalid state. + </result> + <result name="VBOX_E_OBJECT_IN_USE"> + Some of the applied objects already exist. The method has been + called to already configured machine. + </result> + </desc> + <param name="flags" type="wstring" dir="in"> + <desc> + Additional flags, to be defined later. + </desc> + </param> + </method> + + <method name="changeEncryption" wrap-hint-server="limitedcaller"> + <desc> + Starts encryption of this VM. This means that the stored data of the VM is encrypted. + + Please note that the results can be either returned straight away, + or later as the result of the background operation via the object + returned via the @a progress parameter. + + <result name="VBOX_E_NOT_SUPPORTED"> + Encryption is not supported for various reasons e.g. unsupported cipher. + </result> + </desc> + <param name="currentPassword" type="wstring" dir="in"> + <desc> + The current password the VM is protected with. Use an empty string to indicate + that the VM isn't encrypted. + </desc> + </param> + <param name="cipher" type="wstring" dir="in"> + <desc> + The cipher to use for encryption. An empty string indicates no encryption for the + result. + </desc> + </param> + <param name="newPassword" type="wstring" dir="in"> + <desc> + The new password the VM should be protected with. An empty password and password ID + will result in the VM being encrypted with the current password. + </desc> + </param> + <param name="newPasswordId" type="wstring" dir="in"> + <desc>The ID of the new password when unlocking the VM.</desc> + </param> + <param name="force" type="boolean" dir="in"> + <desc> + Force reencryption of the data if just password is changed. + Otherwise, if data already encrypted and cipher doesn't changed + only the password is changed. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="getEncryptionSettings" const="yes" wrap-hint-server="limitedcaller"> + <desc> + Returns the encryption settings for this VM. + + <result name="VBOX_E_NOT_SUPPORTED"> + Encryption is not configured for this VM. + </result> + </desc> + <param name="cipher" type="wstring" dir="out"> + <desc>The cipher used for encryption.</desc> + </param> + <param name="passwordId" type="wstring" dir="out"> + <desc>The ID of the password when unlocking the VM.</desc> + </param> + </method> + + <method name="checkEncryptionPassword" const="yes" wrap-hint-server="limitedcaller"> + <desc> + Checks whether the supplied password is correct for the VM. + + <result name="VBOX_E_NOT_SUPPORTED"> + Encryption is not configured for this VM. + </result> + <result name="VBOX_E_PASSWORD_INCORRECT"> + The given password is incorrect. + </result> + </desc> + <param name="password" type="wstring" dir="in"> + <desc>The password to check.</desc> + </param> + </method> + + <method name="addEncryptionPassword" wrap-hint-server="limitedcaller"> + <desc> + Adds a password used for encryption. Updates the accesibility + state if password used the VM encryption. + + <result name="VBOX_E_PASSWORD_INCORRECT"> + The password provided wasn't correct for the VM using the provided + ID. + </result> + </desc> + <param name="id" type="wstring" dir="in"> + <desc> + The identifier used for the password. Must match the identifier + used when the encrypted VM was created. + </desc> + </param> + <param name="password" type="wstring" dir="in"> + <desc>The password.</desc> + </param> + </method> + + <method name="addEncryptionPasswords" wrap-hint-server="limitedcaller"> + <desc> + Adds passwords used for encryption. Updates the accesibility + state if the list contains password used the VM encryption. + + <result name="VBOX_E_PASSWORD_INCORRECT"> + The password provided wasn't correct for the VM using the provided + ID. + </result> + <result name="E_INVALIDARG"> + Id and passwords arrays have different size. + </result> + </desc> + <param name="ids" type="wstring" dir="in" safearray="yes"> + <desc> + List of identifiers for the passwords. Must match the identifier + used when the encrypted VM was created. + </desc> + </param> + <param name="passwords" type="wstring" dir="in" safearray="yes"> + <desc>List of passwords.</desc> + </param> + </method> + + <method name="removeEncryptionPassword" wrap-hint-server="limitedcaller,passcaller"> + <desc> + Removes a password used for the VM encryption/decryption. + The password can be removed only if the VM is powered off. + Removing the password causes the VM goes to the inaccessible + state and the password must be provided again. + <note> + If machine becomes inaccessible all passwords are purged. + One has to add required passwords again using either + <link to="IMachine::addEncryptionPassword"/> or + <link to="IMachine::addEncryptionPasswords"/> methods. + </note> + </desc> + <result name="VBOX_E_INVALID_VM_STATE"> + The VM is not in proper state e.g powered on. + </result> + <param name="id" type="wstring" dir="in"> + <desc> + The identifier used for the password. Must match the identifier + used when the encrypted VM was created. + </desc> + </param> + </method> + + <method name="clearAllEncryptionPasswords" wrap-hint-server="limitedcaller,passcaller"> + <desc> + Clears all provided VM passwords. + The passwords can be removed only if the VM is powered off. + Removing the passwords causes the VM goes to the inaccessible + state and the password must be provided again. + </desc> + <result name="VBOX_E_INVALID_VM_STATE"> + The VM is not in proper state e.g powered on. + </result> + </method> + + </interface> + + <interface + name="IEmulatedUSB" extends="$unknown" + uuid="6e253ee8-477a-2497-6759-88b8292a5af0" + wsmap="managed" + reservedMethods="4" reservedAttributes="4" + > + <desc> + Manages emulated USB devices. + </desc> + + <method name="webcamAttach"> + <desc> + Attaches the emulated USB webcam to the VM, which will use a host video capture device. + </desc> + <param name="path" type="wstring" dir="in"> + <desc>The host path of the capture device to use.</desc> + </param> + <param name="settings" type="wstring" dir="in"> + <desc>Optional settings.</desc> + </param> + </method> + + <method name="webcamDetach"> + <desc> + Detaches the emulated USB webcam from the VM + </desc> + <param name="path" type="wstring" dir="in"> + <desc>The host path of the capture device to detach.</desc> + </param> + </method> + + <attribute name="webcams" type="wstring" safearray="yes" readonly="yes"> + <desc>Lists attached virtual webcams.</desc> + </attribute> + </interface> + + <!-- + // IConsole + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IVRDEServerInfo" extends="$unknown" + uuid="c39ef4d6-7532-45e8-96da-eb5986ae76e4" + wsmap="struct" + rest="managed" + reservedAttributes="8" + > + <desc> + Contains information about the remote desktop (VRDE) server capabilities and status. + This is used in the <link to="IConsole::VRDEServerInfo" /> attribute. + </desc> + + <attribute name="active" type="boolean" readonly="yes"> + <desc> + Whether the remote desktop connection is active. + </desc> + </attribute> + + <attribute name="port" type="long" readonly="yes"> + <desc> + VRDE server port number. If this property is equal to <tt>0</tt>, then + the VRDE server failed to start, usually because there are no free IP + ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDE + server has not yet been started. + </desc> + </attribute> + + <attribute name="numberOfClients" type="unsigned long" readonly="yes"> + <desc> + How many times a client connected. + </desc> + </attribute> + + <attribute name="beginTime" type="long long" readonly="yes"> + <desc> + When the last connection was established, in milliseconds since 1970-01-01 UTC. + </desc> + </attribute> + + <attribute name="endTime" type="long long" readonly="yes"> + <desc> + When the last connection was terminated or the current time, if + connection is still active, in milliseconds since 1970-01-01 UTC. + </desc> + </attribute> + + <attribute name="bytesSent" type="long long" readonly="yes"> + <desc> + How many bytes were sent in last or current, if still active, connection. + </desc> + </attribute> + + <attribute name="bytesSentTotal" type="long long" readonly="yes"> + <desc> + How many bytes were sent in all connections. + </desc> + </attribute> + + <attribute name="bytesReceived" type="long long" readonly="yes"> + <desc> + How many bytes were received in last or current, if still active, connection. + </desc> + </attribute> + + <attribute name="bytesReceivedTotal" type="long long" readonly="yes"> + <desc> + How many bytes were received in all connections. + </desc> + </attribute> + + <attribute name="user" type="wstring" readonly="yes"> + <desc> + Login user name supplied by the client. + </desc> + </attribute> + + <attribute name="domain" type="wstring" readonly="yes"> + <desc> + Login domain name supplied by the client. + </desc> + </attribute> + + <attribute name="clientName" type="wstring" readonly="yes"> + <desc> + The client name supplied by the client. + </desc> + </attribute> + + <attribute name="clientIP" type="wstring" readonly="yes"> + <desc> + The IP address of the client. + </desc> + </attribute> + + <attribute name="clientVersion" type="unsigned long" readonly="yes"> + <desc> + The client software version number. + </desc> + </attribute> + + <attribute name="encryptionStyle" type="unsigned long" readonly="yes"> + <desc> + Public key exchange method used when connection was established. + Values: 0 - RDP4 public key exchange scheme. + 1 - X509 certificates were sent to client. + </desc> + </attribute> + + </interface> + + <interface + name="IConsole" extends="$unknown" + uuid="6ac83d89-6ee7-4e33-8ae6-b257b2e81be8" + wsmap="managed" + rest="managed" + reservedMethods="8" reservedAttributes="8" + > + <desc> + The IConsole interface represents an interface to control virtual + machine execution. + + A console object gets created when a machine has been locked for a + particular session (client process) using <link to="IMachine::lockMachine" /> + or <link to="IMachine::launchVMProcess"/>. The console object can + then be found in the session's <link to="ISession::console" /> attribute. + + Methods of the IConsole interface allow the caller to query the current + virtual machine execution state, pause the machine or power it down, save + the machine state or take a snapshot, attach and detach removable media + and so on. + + <see><link to="ISession"/></see> + </desc> + + <attribute name="machine" type="IMachine" readonly="yes" rest="uuid"> + <desc> + Machine object for this console session. + <note> + This is a convenience property, it has the same value as + <link to="ISession::machine"/> of the corresponding session + object. + </note> + </desc> + </attribute> + + <attribute name="state" type="MachineState" readonly="yes"> + <desc> + Current execution state of the machine. + <note> + This property always returns the same value as the corresponding + property of the IMachine object for this console session. + For the process that owns (executes) the VM, this is the + preferable way of querying the VM state, because no IPC + calls are made. + </note> + </desc> + </attribute> + + <attribute name="guest" type="IGuest" readonly="yes"> + <desc>Guest object.</desc> + </attribute> + + <attribute name="keyboard" type="IKeyboard" readonly="yes"> + <desc> + Virtual keyboard object. + <note> + If the machine is not running, any attempt to use + the returned object will result in an error. + </note> + </desc> + </attribute> + + <attribute name="mouse" type="IMouse" readonly="yes"> + <desc> + Virtual mouse object. + <note> + If the machine is not running, any attempt to use + the returned object will result in an error. + </note> + </desc> + </attribute> + + <attribute name="display" type="IDisplay" readonly="yes"> + <desc>Virtual display object. + <note> + If the machine is not running, any attempt to use + the returned object will result in an error. + </note> + </desc> + </attribute> + + <attribute name="debugger" type="IMachineDebugger" readonly="yes"> + <desc>Debugging interface.</desc> + </attribute> + + <attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes"> + <desc> + Collection of USB devices currently attached to the virtual + USB controller. + <note> + The collection is empty if the machine is not running. + </note> + </desc> + </attribute> + + <attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes"> + <desc> + List of USB devices currently attached to the remote VRDE client. + Once a new device is physically attached to the remote host computer, + it appears in this list and remains there until detached. + </desc> + </attribute> + + <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes"> + <desc> + Collection of shared folders for the current session. These folders + are called transient shared folders because they are available to the + guest OS running inside the associated virtual machine only for the + duration of the session (as opposed to + <link to="IMachine::sharedFolders"/> which represent permanent shared + folders). When the session is closed (e.g. the machine is powered down), + these folders are automatically discarded. + + New shared folders are added to the collection using + <link to="#createSharedFolder"/>. Existing shared folders can be + removed using <link to="#removeSharedFolder"/>. + </desc> + </attribute> + + <attribute name="VRDEServerInfo" type="IVRDEServerInfo" readonly="yes"> + <desc> + Interface that provides information on Remote Desktop Extension (VRDE) connection. + </desc> + </attribute> + + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for console events. + </desc> + </attribute> + + <attribute name="attachedPCIDevices" type="IPCIDeviceAttachment" readonly="yes" safearray="yes"> + <desc>Array of PCI devices attached to this machine.</desc> + </attribute> + + <attribute name="useHostClipboard" type="boolean"> + <desc> + Whether the guest clipboard should be connected to the host one or + whether it should only be allowed access to the VRDE clipboard. This + setting may not affect existing guest clipboard connections which + are already connected to the host clipboard. + </desc> + </attribute> + + <attribute name="emulatedUSB" type="IEmulatedUSB" readonly="yes"> + <desc> + Interface that manages emulated USB devices. + </desc> + </attribute> + + <method name="powerUp"> + <rest request="post" path="/vms/{vmid}/console/actions/"/> + <desc> + Starts the virtual machine execution using the current machine + state (that is, its current execution state, current settings and + current storage devices). + + <note> + This method is only useful for front-ends that want to actually + execute virtual machines in their own process (like the VirtualBox + or VBoxSDL front-ends). Unless you are intending to write such a + front-end, do not call this method. If you simply want to + start virtual machine execution using one of the existing front-ends + (for example the VirtualBox GUI or headless server), use + <link to="IMachine::launchVMProcess"/> instead; these + front-ends will power up the machine automatically for you. + </note> + + If the machine is powered off or aborted, the execution will + start from the beginning (as if the real hardware were just + powered on). + + If the machine is in the <link to="MachineState_Saved"/> state or the + <link to="MachineState_AbortedSaved"/> state it will continue its + execution from the point where the state was saved. + + If the machine <link to="IMachine::teleporterEnabled"/> property is + enabled on the machine being powered up, the machine will wait for an + incoming teleportation in the <link to="MachineState_TeleportingIn"/> + state. The returned progress object will have at least three + operations where the last three are defined as: (1) powering up and + starting TCP server, (2) waiting for incoming teleportations, and + (3) perform teleportation. These operations will be reflected as the + last three operations of the progress objected returned by + <link to="IMachine::launchVMProcess"/> as well. + + <see><link to="IMachine::saveState"/></see> + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine already running. + </result> + <result name="VBOX_E_HOST_ERROR"> + Host interface does not exist or name not set. + </result> + <result name="VBOX_E_FILE_ERROR"> + Invalid saved state file. + </result> + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="powerUpPaused"> + <rest request="post" path="/vms/{vmid}/console/actions/"/> + <desc> + Identical to powerUp except that the VM will enter the + <link to="MachineState_Paused"/> state, instead of + <link to="MachineState_Running"/>. + + <see><link to="#powerUp"/></see> + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine already running. + </result> + <result name="VBOX_E_HOST_ERROR"> + Host interface does not exist or name not set. + </result> + <result name="VBOX_E_FILE_ERROR"> + Invalid saved state file. + </result> + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="powerDown"> + <rest request="post" path="/vms/{vmid}/console/actions/"/> + <desc> + Initiates the power down procedure to stop the virtual machine + execution. + + The completion of the power down procedure is tracked using the returned + IProgress object. After the operation is complete, the machine will go + to the PoweredOff state. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine must be Running, Paused or Stuck to be powered down. + </result> + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="reset"> + <rest request="post" path="/vms/{vmid}/console/actions/"/> + <desc>Resets the virtual machine. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Running state. + </result> + <result name="VBOX_E_VM_ERROR"> + Virtual machine error in reset operation. + </result> + </desc> + </method> + + <method name="pause"> + <rest request="post" path="/vms/{vmid}/console/actions/"/> + <desc>Pauses the virtual machine execution. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Running state. + </result> + <result name="VBOX_E_VM_ERROR"> + Virtual machine error in suspend operation. + </result> + </desc> + </method> + + <method name="resume"> + <rest request="post" path="/vms/{vmid}/console/actions/"/> + <desc>Resumes the virtual machine execution. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Paused state. + </result> + <result name="VBOX_E_VM_ERROR"> + Virtual machine error in resume operation. + </result> + </desc> + </method> + + <method name="powerButton"> + <rest request="post" path="/vms/{vmid}/console/actions/"/> + <desc>Sends the ACPI power button event to the guest. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Running state. + </result> + <result name="VBOX_E_PDM_ERROR"> + Controlled power off failed. + </result> + </desc> + </method> + + <method name="sleepButton"> + <rest request="post" path="/vms/{vmid}/console/actions/"/> + <desc>Sends the ACPI sleep button event to the guest. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Running state. + </result> + <result name="VBOX_E_PDM_ERROR"> + Sending sleep button event failed. + </result> + </desc> + </method> + + <method name="getPowerButtonHandled"> + <desc>Checks if the last power button event was handled by guest. + <result name="VBOX_E_PDM_ERROR"> + Checking if the event was handled by the guest OS failed. + </result> + </desc> + <param name="handled" type="boolean" dir="return"/> + </method> + + <method name="getGuestEnteredACPIMode"> + <desc>Checks if the guest entered the ACPI mode G0 (working) or + G1 (sleeping). If this method returns @c false, the guest will + most likely not respond to external ACPI events. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Running state. + </result> + </desc> + <param name="entered" type="boolean" dir="return"/> + </method> + + <method name="getDeviceActivity"> + <desc> + Gets the current activity type of given devices or device groups. + <result name="E_INVALIDARG"> + Invalid device type. + </result> + </desc> + <param name="type" type="DeviceType" safearray="yes" dir="in"/> + <param name="activity" type="DeviceActivity" safearray="yes" dir="return"/> + </method> + + <method name="attachUSBDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Attaches a host USB device with the given UUID to the + USB controller of the virtual machine. + + The device needs to be in one of the following states: + <link to="USBDeviceState_Busy"/>, + <link to="USBDeviceState_Available"/> or + <link to="USBDeviceState_Held"/>, + otherwise an error is immediately returned. + + When the device state is + <link to="USBDeviceState_Busy">Busy</link>, an error may also + be returned if the host computer refuses to release it for some reason. + + <see><link to="IUSBDeviceFilters::deviceFilters"/>, + <link to="USBDeviceState"/></see> + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine state neither Running nor Paused. + </result> + <result name="VBOX_E_PDM_ERROR"> + Virtual machine does not have a USB controller. + </result> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc>UUID of the host USB device to attach.</desc> + </param> + <param name="captureFilename" type="wstring" dir="in"> + <desc>Filename to capture the USB traffic to.</desc> + </param> + </method> + + <method name="detachUSBDevice"> + <rest request="post" path="/vms/{vmid}/configuration/"/> + <desc> + Detaches an USB device with the given UUID from the USB controller + of the virtual machine. + + After this method succeeds, the VirtualBox server re-initiates + all USB filters as if the device were just physically attached + to the host, but filters of this machine are ignored to avoid + a possible automatic re-attachment. + + <see><link to="IUSBDeviceFilters::deviceFilters"/>, + <link to="USBDeviceState"/></see> + + <result name="VBOX_E_PDM_ERROR"> + Virtual machine does not have a USB controller. + </result> + <result name="E_INVALIDARG"> + USB device not attached to this virtual machine. + </result> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc>UUID of the USB device to detach.</desc> + </param> + <param name="device" type="IUSBDevice" dir="return"> + <desc>Detached USB device.</desc> + </param> + </method> + + <method name="findUSBDeviceByAddress"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Searches for a USB device with the given host address. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Given @c name does not correspond to any USB device. + </result> + + <see><link to="IUSBDevice::address"/></see> + </desc> + <param name="name" type="wstring" dir="in"> + <desc> + Address of the USB device (as assigned by the host) to + search for. + </desc> + </param> + <param name="device" type="IUSBDevice" dir="return"> + <desc>Found USB device object.</desc> + </param> + </method> + + <method name="findUSBDeviceById"> + <rest request="get" path="/vms/{vmid}/configuration/"/> + <desc> + Searches for a USB device with the given UUID. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Given @c id does not correspond to any USB device. + </result> + + <see><link to="IUSBDevice::id"/></see> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc>UUID of the USB device to search for.</desc> + </param> + <param name="device" type="IUSBDevice" dir="return"> + <desc>Found USB device object.</desc> + </param> + </method> + + <method name="createSharedFolder"> + <rest request="post" path="/vms/{vmid}/console/methods/"/> + <desc> + Creates a transient new 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 + <link to="ISharedFolder"/> to read more about logical names. + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is in the Saved or AbortedSaved state or currently changing state. + </result> + <result name="VBOX_E_FILE_ERROR"> + Shared folder already exists or not accessible. + </result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Unique logical name of the shared folder.</desc> + </param> + <param name="hostPath" type="wstring" dir="in"> + <desc>Full path to the shared folder in the host file system.</desc> + </param> + <param name="writable" type="boolean" dir="in"> + <desc>Whether the share is writable or readonly</desc> + </param> + <param name="automount" type="boolean" dir="in"> + <desc>Whether the share gets automatically mounted by the guest + or not.</desc> + </param> + <param name="autoMountPoint" type="wstring" dir="in"> + <desc>Where the guest should automatically mount the folder, if possible. + For Windows and OS/2 guests this should be a drive letter, while other + guests it should be a absolute directory. + </desc> + </param> + </method> + + <method name="removeSharedFolder"> + <rest request="post" path="/vms/{vmid}/console/methods/"/> + <desc> + Removes a transient shared folder with the given name previously + created by <link to="#createSharedFolder"/> from the collection of + shared folders and stops sharing it. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is in the Saved or AbortedSaved state or currently changing state. + </result> + <result name="VBOX_E_FILE_ERROR"> + Shared folder does not exists. + </result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Logical name of the shared folder to remove.</desc> + </param> + </method> + + <method name="teleport"> + <desc> + Teleport the VM to a different host machine or process. + + @todo Explain the details. + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not running or paused. + </result> + </desc> + <param name="hostname" type="wstring" dir="in"> + <desc>The name or IP of the host to teleport to.</desc> + </param> + <param name="tcpport" type="unsigned long" dir="in"> + <desc>The TCP port to connect to (1..65535).</desc> + </param> + <param name="password" type="wstring" dir="in"> + <desc>The password.</desc> + </param> + <param name="maxDowntime" type="unsigned long" dir="in"> + <desc> + The maximum allowed downtime given as milliseconds. 0 is not a valid + value. Recommended value: 250 ms. + + The higher the value is, the greater the chance for a successful + teleportation. A small value may easily result in the teleportation + process taking hours and eventually fail. + + <note> + The current implementation treats this a guideline, not as an + absolute rule. + </note> + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="addEncryptionPassword"> + <rest request="post" path="/vms/{vmid}/console/methods/"/> + <desc> + Adds a password used for encryption/decryption. + + <result name="VBOX_E_PASSWORD_INCORRECT"> + The password provided wasn't correct for at least one disk using the provided + ID. + </result> + </desc> + <param name="id" type="wstring" dir="in"> + <desc> + The identifier used for the password. Must match the identifier + used when the encrypted medium was created. + </desc> + </param> + <param name="password" type="wstring" dir="in"> + <desc>The password.</desc> + </param> + <param name="clearOnSuspend" type="boolean" dir="in"> + <desc> + Flag whether to clear the password on VM suspend (due to a suspending host + for example). The password must be supplied again before the VM can resume. + </desc> + </param> + </method> + + <method name="addEncryptionPasswords"> + <rest request="post" path="/vms/{vmid}/console/methods/"/> + <desc> + Adds a password used for encryption/decryption. + + <result name="VBOX_E_PASSWORD_INCORRECT"> + The password provided wasn't correct for at least one disk using the provided + ID. + </result> + </desc> + <param name="ids" type="wstring" dir="in" safearray="yes"> + <desc> + List of identifiers for the passwords. Must match the identifier + used when the encrypted medium was created. + </desc> + </param> + <param name="passwords" type="wstring" dir="in" safearray="yes"> + <desc>List of passwords.</desc> + </param> + <param name="clearOnSuspend" type="boolean" dir="in"> + <desc> + Flag whether to clear the given passwords on VM suspend (due to a suspending host + for example). The passwords must be supplied again before the VM can resume. + </desc> + </param> + </method> + + <method name="removeEncryptionPassword"> + <rest request="post" path="/vms/{vmid}/console/methods/"/> + <desc> + Removes a password used for hard disk encryption/decryption from + the running VM. As soon as the medium requiring this password + is accessed the VM is paused with an error and the password must be + provided again. + </desc> + <param name="id" type="wstring" dir="in"> + <desc> + The identifier used for the password. Must match the identifier + used when the encrypted medium was created. + </desc> + </param> + </method> + + <method name="clearAllEncryptionPasswords"> + <rest request="post" path="/vms/{vmid}/console/methods/"/> + <desc>Clears all provided supplied encryption passwords.</desc> + </method> + </interface> + + <!-- + // IHost + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="HostNetworkInterfaceMediumType" + uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b" + > + <!-- Must match NETIFTYPE in netif.h exactly. --> + <desc> + Type of encapsulation. Ethernet encapsulation includes both wired and + wireless Ethernet connections. + <see><link to="IHostNetworkInterface"/></see> + </desc> + + <const name="Unknown" value="0"> + <desc> + The type of interface cannot be determined. + </desc> + </const> + <const name="Ethernet" value="1"> + <desc> + Ethernet frame encapsulation. + </desc> + </const> + <const name="PPP" value="2"> + <desc> + Point-to-point protocol encapsulation. + </desc> + </const> + <const name="SLIP" value="3"> + <desc> + Serial line IP encapsulation. + </desc> + </const> + </enum> + + <enum + name="HostNetworkInterfaceStatus" + uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41" + > + <!-- Must match NETIFSTATUS in netif.h exactly. --> + <desc> + Current status of the interface. + <see><link to="IHostNetworkInterface"/></see> + </desc> + + <const name="Unknown" value="0"> + <desc> + The state of interface cannot be determined. + </desc> + </const> + <const name="Up" value="1"> + <desc> + The interface is fully operational. + </desc> + </const> + <const name="Down" value="2"> + <desc> + The interface is not functioning. + </desc> + </const> + </enum> + + <enum + name="HostNetworkInterfaceType" + uuid="67431b00-9946-48a2-bc02-b25c5919f4f3" + > + <desc> + Network interface type. + </desc> + <const name="Bridged" value="1"/> + <const name="HostOnly" value="2"/> + </enum> + + <interface + name="IHostNetworkInterface" extends="$unknown" + uuid="455f8c45-44a0-a470-ba20-27890b96dba9" + wsmap="managed" + rest="managed" + reservedMethods="2" reservedAttributes="4" + > + <desc> + Represents one of host's network interfaces. IP V6 address and network + mask are strings of 32 hexadecimal digits grouped by four. Groups are + separated by colons. + For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030. + </desc> + <attribute name="name" type="wstring" readonly="yes"> + <desc>Returns the host network interface name.</desc> + </attribute> + + <attribute name="shortName" type="wstring" readonly="yes"> + <desc>Returns the host network interface short name.</desc> + </attribute> + + <attribute name="id" type="uuid" mod="string" readonly="yes"> + <desc>Returns the interface UUID.</desc> + </attribute> + + <attribute name="networkName" type="wstring" readonly="yes"> + <desc>Returns the name of a virtual network the interface gets attached to.</desc> + </attribute> + + <attribute name="DHCPEnabled" type="boolean" readonly="yes"> + <desc>Specifies whether the DHCP is enabled for the interface.</desc> + </attribute> + + <attribute name="IPAddress" type="wstring" readonly="yes"> + <desc>Returns the IP V4 address of the interface.</desc> + </attribute> + + <attribute name="networkMask" type="wstring" readonly="yes"> + <desc>Returns the network mask of the interface.</desc> + </attribute> + + <attribute name="IPV6Supported" type="boolean" readonly="yes"> + <desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc> + </attribute> + + <attribute name="IPV6Address" type="wstring" readonly="yes"> + <desc>Returns the IP V6 address of the interface.</desc> + </attribute> + + <attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes"> + <desc>Returns the length IP V6 network mask prefix of the interface.</desc> + </attribute> + + <attribute name="hardwareAddress" type="wstring" readonly="yes"> + <desc>Returns the hardware address. For Ethernet it is MAC address.</desc> + </attribute> + + <attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes"> + <desc>Type of protocol encapsulation used.</desc> + </attribute> + + <attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes"> + <desc>Status of the interface.</desc> + </attribute> + + <attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes"> + <desc>specifies the host interface type.</desc> + </attribute> + + <attribute name="wireless" type="boolean" readonly="yes"> + <desc>Specifies whether the interface is wireless.</desc> + </attribute> + + <method name="enableStaticIPConfig"> + <desc>sets and enables the static IP V4 configuration for the given interface.</desc> + <param name="IPAddress" type="wstring" dir="in"> + <desc> + IP address. + </desc> + </param> + <param name="networkMask" type="wstring" dir="in"> + <desc> + network mask. + </desc> + </param> + </method> + + <method name="enableStaticIPConfigV6"> + <desc>sets and enables the static IP V6 configuration for the given interface.</desc> + <param name="IPV6Address" type="wstring" dir="in"> + <desc> + IP address. + </desc> + </param> + <param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in"> + <desc> + network mask. + </desc> + </param> + </method> + + <method name="enableDynamicIPConfig"> + <desc>enables the dynamic IP configuration.</desc> + </method> + + <method name="DHCPRediscover"> + <desc>refreshes the IP configuration for DHCP-enabled interface.</desc> + </method> + + </interface> + + <interface + name="IHostVideoInputDevice" extends="$unknown" + uuid="e8c25d4d-ac97-4c16-b3e2-81bd8a57cc27" + wsmap="managed" + rest="managed" + reservedAttributes="4" + > + <desc> + Represents one of host's video capture devices, for example a webcam. + </desc> + + <attribute name="name" type="wstring" readonly="yes"> + <desc>User friendly name.</desc> + </attribute> + + <attribute name="path" type="wstring" readonly="yes"> + <desc>The host path of the device.</desc> + </attribute> + + <attribute name="alias" type="wstring" readonly="yes"> + <desc>An alias which can be used for <link to="IEmulatedUSB::webcamAttach"/></desc> + </attribute> + + </interface> + + <enum + name="UpdateChannel" + uuid="9f1562a5-e47a-496b-a818-66776f06ce40" + > + <const name="Invalid" value="0"> + <desc>No channel specified. Do not use this.</desc> + </const> + <const name="Stable" value="1"> + <desc>All stable releases (maintenance and minor releases within the same major release).</desc> + </const> + <const name="All" value="2"> + <desc>All stable releases, including major versions.</desc> + </const> + <const name="WithBetas" value="3"> + <desc>All stable and major releases, including beta versions.</desc> + </const> + <const name="WithTesting" value="4"> + <desc>All stable, major and beta releases, including testing versions.</desc> + </const> + </enum> + + <enum + name="UpdateSeverity" + uuid="359a5fee-8a06-4306-8068-2f2dd5cde06f" + > + <const name="Invalid" value="0"> + <desc>No severity specified. Do not use this.</desc> + </const> + <const name="Critical" value="1"> + <desc>Update contains critical patches.</desc> + </const> + <const name="Major" value="2"> + <desc>Update contains a major version.</desc> + </const> + <const name="Minor" value="3"> + <desc>Update contains a minor version.</desc> + </const> + <const name="Testing" value="4"> + <desc>Update contains a testing version. Use with caution!</desc> + </const> + </enum> + + <enum + name="UpdateState" + uuid="6623e363-c892-45f8-80cb-4e8ffd9b4e60" + > + <const name="Invalid" value="0"> + <desc>Invalid / not set update state.</desc> + </const> + <const name="Available" value="1"> + <desc>An uppdate is available.</desc> + </const> + <const name="NotAvailable" value="2"> + <desc>No update available.</desc> + </const> + <const name="Downloading" value="3"> + <desc>Update is being downloaded currently.</desc> + </const> + <const name="Downloaded" value="4"> + <desc>Update has been successfully downloaded.</desc> + </const> + <const name="Installing" value="5"> + <desc>Update is being installed currently.</desc> + </const> + <const name="Installed" value="6"> + <desc>Update has been successfully installed.</desc> + </const> + <const name="UserInteraction" value="7"> + <desc>Update requires user interaction to continue.</desc> + </const> + <const name="Canceled" value="8"> + <desc>Update has been canceled.</desc> + </const> + <const name="Maintenance" value="9"> + <desc>Update service currently is in maintenance mode.</desc> + </const> + <const name="Error" value="10"> + <desc>An error occurred while updating.</desc> + </const> + </enum> + + <interface + name="IUpdateAgent" extends="$unknown" + uuid="c4b1b5f4-8cdf-4923-9ef6-b92476a84109" + wsmap="managed" + reservedMethods="2" reservedAttributes="4" + > + + <desc> + Abstract parent interface for handling updateable software components. + </desc> + + <method name="checkFor"> + <!-- Initially named just "check", but older xcode versions on the Mac have trouble naming interface + functions like this and thus failing to build, sigh. --> + <desc> + Checks for an update. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track operation completion.</desc> + </param> + </method> + + <method name="download"> + <desc> + Downloads the update. + </desc> + <result name="VBOX_E_NOT_SUPPORTED"> + Downloading update not supported. + </result> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track operation completion.</desc> + </param> + </method> + + <method name="install"> + <desc> + Installs the update. + </desc> + <result name="VBOX_E_NOT_SUPPORTED"> + Installing update not supported. + </result> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track operation completion.</desc> + </param> + </method> + + <method name="rollback"> + <desc> + Rolls back installing the update. + </desc> + <result name="VBOX_E_NOT_SUPPORTED"> + Rolling back update not supported. + </result> + </method> + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + Name of the update component. + </desc> + </attribute> + + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for update agent events. + </desc> + </attribute> + + <attribute name="order" type="unsigned long" readonly="yes"> + <desc> + Order hint the update component needs to run at, in conjunction with other update components. + </desc> + <result name="0"> + No order preferred / disabled. + </result> + <note> + Lower numbers mean higher priority. 0 means no order or disabled. + </note> + </attribute> + + <attribute name="dependsOn" type="wstring" readonly="yes" safearray="yes"> + <desc> + Array of other update component names this component depends on before being able to get installed. + </desc> + <note> + Ordered entries, highest priority first. No dependencies when array is empty. + Dependency entries also can contain a minimum version number after the update component name, separated by an "@", + e.g. "Guest Additions@7.1.0_BETA2". + </note> + </attribute> + + <attribute name="version" type="wstring" readonly="yes"> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Result not available yet. + </result> + <desc> + Version the update contains. + </desc> + </attribute> + + <attribute name="downloadUrl" type="wstring" readonly="yes"> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Result not available yet. + </result> + <desc> + Download URL of the update. + </desc> + </attribute> + + <attribute name="webUrl" type="wstring" readonly="yes"> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Result not available yet. + </result> + <desc> + Web URL of the update. + </desc> + </attribute> + + <attribute name="releaseNotes" type="wstring" readonly="yes"> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Result not available yet. + </result> + <desc> + Release notes of the update. + </desc> + </attribute> + + <attribute name="enabled" type="boolean" readonly="no"> + <desc> + Enables or disables the update component. + </desc> + </attribute> + + <attribute name="hidden" type="boolean" readonly="yes"> + <desc> + Whether the update component shall be hidden from the user or not. + </desc> + </attribute> + + <attribute name="state" type="UpdateState" readonly="yes"> + <desc> + Returns the current update state. + </desc> + </attribute> + + <attribute name="checkFrequency" type="unsigned long" readonly="no"> + <desc> + The update check frequency (in seconds). + </desc> + </attribute> + + <attribute name="channel" type="UpdateChannel" readonly="no"> + <desc> + Update channel to use for checking for updates. + </desc> + </attribute> + + <attribute name="repositoryURL" type="wstring" readonly="no"> + <desc> + Update repository URL to use for retrieving the update. + </desc> + <note> + Only repositories with the https:// URL scheme are allowed. + </note> + </attribute> + + <attribute name="lastCheckDate" type="wstring" readonly="yes"> + <desc> + Date of last update check. + </desc> + <note> + In ISO 8601 format (e.g. 2020-05-11T21:13:39.348416000Z). + </note> + </attribute> + + <attribute name="checkCount" type="unsigned long" readonly="yes"> + <desc> + How many times the update check has happened already. + </desc> + </attribute> + + <attribute name="isCheckNeeded" type="boolean" readonly="yes"> + <desc> + Returns @c TRUE if an update check is needed, or @c FALSE if not. + + <note>Compares the system's current date with the last + update check date and currently set check frequency.</note> + </desc> + </attribute> + + <attribute name="supportedChannels" type="UpdateChannel" safearray="yes" readonly="yes"> + <desc> + Returns a safe array of all supported update channels this agents offers. + </desc> + </attribute> + + </interface> + + <interface + name="IHostUpdateAgent" extends="IUpdateAgent" + uuid="d782dba7-cd4f-4ace-951a-58321c23e258" + wsmap="managed" + reservedMethods="2" reservedAttributes="4" + > + <desc> + Implementation of the <link to="IUpdateAgent" /> object + for VirtualBox host updates. + </desc> + <note> + If no proxy is explicitly set, the proxy settings from <link to="ISystemProperties" /> will be used. + </note> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IHostDrivePartition" extends="$unknown" + uuid="4f529a14-ace3-407c-9c49-066e8e8027f0" + wsmap="struct" + rest="managed" + > + <desc> + The IHostDrivePartition interface represents the partition of the host drive. + To enumerate all available drives partitions in the host, use the + <link to="IHost::hostDrives"/> attribute. + </desc> + + <attribute name="number" type="unsigned long" readonly="yes"> + <desc> + The number of the partition. Represents the system number of the + partition, e.g. /dev/sdX in the linux, where X is the number + returned. + </desc> + </attribute> + + <attribute name="size" type="long long" readonly="yes"> + <desc> + The partition size in bytes. + </desc> + </attribute> + + <attribute name="start" type="long long" readonly="yes"> + <desc> + The start byte offset of this partition in bytes relative to the + beginning of the hard disk. + </desc> + </attribute> + + <attribute name="type" type="PartitionType" readonly="yes"> + <desc> + A translation of <link to="IHostDrivePartition::typeMBR"/> and + <link to="IHostDrivePartition::typeUuid"/> when possible, otherwise + set to <link to="PartitionType_Unknown" />. + </desc> + </attribute> + + <attribute name="active" type="boolean" readonly="yes"> + <desc> + The partition is bootable when TRUE. + </desc> + </attribute> + + <!-- MBR: --> + + <attribute name="typeMBR" type="unsigned long" readonly="yes"> + <desc> + The raw MBR partition type, 0 for non-MBR disks. + </desc> + </attribute> + + <attribute name="startCylinder" type="unsigned long" readonly="yes"> + <desc> + The cylinder (0..1023) of the first sector in the partition on an MBR disk, zero for not an MBR disk. + </desc> + </attribute> + + <attribute name="startHead" type="unsigned long" readonly="yes"> + <desc> + The head (0..255) of the first sector in the partition on an MBR disk, zero for not an MBR disk. + </desc> + </attribute> + + <attribute name="startSector" type="unsigned long" readonly="yes"> + <desc> + The sector (0..63) of the first sector in the partition on an MBR disk, zero for not an MBR disk. + </desc> + </attribute> + + <attribute name="endCylinder" type="unsigned long" readonly="yes"> + <desc> + The cylinder (0..1023) of the last sector (inclusive) in the partition on an MBR disk, zero for not an MBR disk. + </desc> + </attribute> + + <attribute name="endHead" type="unsigned long" readonly="yes"> + <desc> + The head (0..255) of the last sector (inclusive) in the partition on an MBR disk, zero for not an MBR disk. + </desc> + </attribute> + + <attribute name="endSector" type="unsigned long" readonly="yes"> + <desc> + The sector (1..63) of the last sector (inclusive) in the partition on an MBR disk, zero for not an MBR disk. + </desc> + </attribute> + + <!-- GPT: --> + <attribute name="typeUuid" type="uuid" mod="string" readonly="yes"> + <!-- @todo r=bird: Not sure about the casing here. typeUUID Klaus? --> + <desc> + The partition type when GUID partitioning scheme is used, NULL UUID value for not a GPT disks. + </desc> + </attribute> + + <attribute name="uuid" type="uuid" mod="string" readonly="yes"> + <desc> + The GUID of the partition when GUID partitioning scheme is used, NULL UUID value for not a GPT disks. + </desc> + </attribute> + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + The name of the partition if GPT partitioning is used, empty if not a GPT disk. + </desc> + </attribute> + + </interface> + + <interface + name="IHostDrive" extends="$unknown" + uuid="70e2e0c3-332c-4d72-b822-2db16e2cb31b" + wsmap="managed" + rest="managed" + > + <desc> + The IHostDrive interface represents the drive of the physical machine. + It is not a complete medium description and, therefore, it is not IMedium + based. The interface is used to get information about a host drive and + its partitioning. + <note> + The object operates in limited mode if the user cannot open the drive + and parse the partition table. In limited mode on the + <link to="IHostDrive::drivePath" /> and <link to="IHostDrive::model" /> + attributes can be accessed, the rest will fail with E_ACCESSDENIED. + </note> + </desc> + + <attribute name="drivePath" type="wstring" readonly="yes" wrap-hint-server="limitedcaller"> + <desc> + The path of the drive. Platform dependent. + </desc> + </attribute> + + <attribute name="partitioningType" type="PartitioningType" readonly="yes"> + <desc> + The scheme of the partitions the disk has. + </desc> + </attribute> + + <attribute name="uuid" type="uuid" mod="string" readonly="yes"> + <desc> + The GUID of the disk. + </desc> + </attribute> + + <attribute name="sectorSize" type="unsigned long" readonly="yes"> + <desc> + The size of the sector in bytes. + </desc> + </attribute> + + <attribute name="size" type="long long" readonly="yes"> + <desc> + The size of the disk in bytes. + </desc> + </attribute> + + <attribute name="model" type="wstring" readonly="yes" wrap-hint-server="limitedcaller"> + <desc> + The model string of the drive if available. + </desc> + </attribute> + + <attribute name="partitions" type="IHostDrivePartition" readonly="yes" safearray="yes"> + <desc>List of partitions available on the host drive.</desc> + </attribute> + + </interface> + + <interface + name="IHost" extends="$unknown" + uuid="e54f6256-97a7-4947-8a78-10c013ddf4b8" + wsmap="managed" + rest="managed" + reservedMethods="6" reservedAttributes="12" + > + <desc> + The IHost interface represents the physical machine that this VirtualBox + installation runs on. + + An object implementing this interface is returned by the + <link to="IVirtualBox::host" /> attribute. This interface contains + read-only information about the host's physical hardware (such as what + processors and disks are available, what the host operating system is, + and so on) and also allows for manipulating some of the host's hardware, + such as global USB device filters and host interface networking. + + </desc> + <attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes"> + <desc>List of DVD drives available on the host.</desc> + </attribute> + + <attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes"> + <desc>List of floppy drives available on the host.</desc> + </attribute> + + <attribute name="audioDevices" type="IHostAudioDevice" readonly="yes" safearray="yes"> + <desc>List of audio devices currently available on the host. + <result name="E_NOTIMPL"> + This attribute is not implemented yet. + </result> + </desc> + </attribute> + + <attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes"> + <desc> + List of USB devices currently attached to the host. + Once a new device is physically attached to the host computer, + it appears in this list and remains there until detached. + + <note> + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + </note> + </desc> + </attribute> + + <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes"> + <desc> + List of USB device filters in action. + When a new device is physically attached to the host computer, + filters from this list are applied to it (in order they are stored + in the list). The first matched filter will determine the + <link to="IHostUSBDeviceFilter::action">action</link> + performed on the device. + + Unless the device is ignored by these filters, filters of all + currently running virtual machines + (<link to="IUSBDeviceFilters::deviceFilters"/>) are applied to it. + + <note> + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + </note> + + <see><link to="IHostUSBDeviceFilter"/>, + <link to="USBDeviceState"/></see> + </desc> + </attribute> + + <attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes"> + <desc>List of host network interfaces currently defined on the host.</desc> + </attribute> + + <attribute name="nameServers" type="wstring" safearray="yes" readonly="yes"> + <desc> The list of nameservers registered in host's name resolving system.</desc> + </attribute> + + <attribute name="domainName" type="wstring" readonly="yes"> + <desc>Domain name used for name resolving.</desc> + </attribute> + + <attribute name="searchStrings" type="wstring" safearray="yes" readonly="yes"> + <desc>Search string registered for name resolving.</desc> + </attribute> + + <attribute name="processorCount" type="unsigned long" readonly="yes"> + <desc>Number of (logical) CPUs installed in the host system.</desc> + </attribute> + + <attribute name="processorOnlineCount" type="unsigned long" readonly="yes"> + <desc>Number of (logical) CPUs online in the host system.</desc> + </attribute> + + <attribute name="processorCoreCount" type="unsigned long" readonly="yes"> + <desc>Number of physical processor cores installed in the host system.</desc> + </attribute> + + <attribute name="processorOnlineCoreCount" type="unsigned long" readonly="yes"> + <desc>Number of physical processor cores online in the host system.</desc> + </attribute> + + <attribute name="hostDrives" type="IHostDrive" readonly="yes" safearray="yes"> + <desc>List of the host drive available to use in the VirtualBox.</desc> + </attribute> + + <method name="getProcessorSpeed"> + <desc>Query the (approximate) maximum speed of a specified host CPU in + Megahertz. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc> + Identifier of the CPU. + </desc> + </param> + <param name="speed" type="unsigned long" dir="return"> + <desc> + Speed value. 0 is returned if value is not known or @a cpuId is + invalid. + </desc> + </param> + </method> + + <method name="getProcessorFeature"> + <desc>Query whether a CPU feature is supported or not.</desc> + <param name="feature" type="ProcessorFeature" dir="in"> + <desc> + CPU Feature identifier. + </desc> + </param> + <param name="supported" type="boolean" dir="return"> + <desc> + Feature is supported or not. + </desc> + </param> + </method> + + <method name="getProcessorDescription"> + <desc>Query the model string of a specified host CPU. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc> + Identifier of the CPU. + <note> + The current implementation might not necessarily return the + description for this exact CPU. + </note> + </desc> + </param> + <param name="description" type="wstring" dir="return"> + <desc> + Model string. An empty string is returned if value is not known or + @a cpuId is invalid. + </desc> + </param> + </method> + + <method name="getProcessorCPUIDLeaf"> + <desc> + Returns the CPU cpuid information for the specified leaf. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc> + Identifier of the CPU. The CPU most be online. + <note> + The current implementation might not necessarily return the + description for this exact CPU. + </note> + </desc> + </param> + <param name="leaf" type="unsigned long" dir="in"> + <desc> + CPUID leaf index (eax). + </desc> + </param> + <param name="subLeaf" type="unsigned long" dir="in"> + <desc> + CPUID leaf sub index (ecx). This currently only applies to cache + information on Intel CPUs. Use 0 if retrieving values for + <link to="IMachine::setCPUIDLeaf"/>. + </desc> + </param> + <param name="valEax" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register eax. + </desc> + </param> + <param name="valEbx" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register ebx. + </desc> + </param> + <param name="valEcx" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register ecx. + </desc> + </param> + <param name="valEdx" type="unsigned long" dir="out"> + <desc> + CPUID leaf value for register edx. + </desc> + </param> + </method> + + <attribute name="memorySize" type="unsigned long" readonly="yes"> + <desc>Amount of system memory in megabytes installed in the host system.</desc> + </attribute> + + <attribute name="memoryAvailable" type="unsigned long" readonly="yes"> + <desc>Available system memory in the host system.</desc> + </attribute> + + <attribute name="operatingSystem" type="wstring" readonly="yes"> + <desc>Name of the host system's operating system.</desc> + </attribute> + + <attribute name="OSVersion" type="wstring" readonly="yes"> + <desc>Host operating system's version string.</desc> + </attribute> + + <attribute name="UTCTime" type="long long" readonly="yes"> + <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc> + </attribute> + + <attribute name="acceleration3DAvailable" type="boolean" readonly="yes"> + <desc>Returns @c true when the host supports 3D hardware acceleration.</desc> + </attribute> + + <method name="createHostOnlyNetworkInterface"> + <desc> + Creates a new adapter for Host Only Networking. + <result name="E_INVALIDARG"> + Host network interface @a name already exists. + </result> + </desc> + <param name="hostInterface" type="IHostNetworkInterface" dir="out"> + <desc> + Created host interface object. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="removeHostOnlyNetworkInterface"> + <desc> + Removes the given Host Only Networking interface. + <result name="VBOX_E_OBJECT_NOT_FOUND"> + No host network interface matching @a id found. + </result> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc> + Adapter GUID. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="createUSBDeviceFilter"> + <desc> + Creates a new USB device filter. All attributes except + the filter name are set to empty (any match), + <i>active</i> is @c false (the filter is not active). + + The created filter can be added to the list of filters using + <link to="#insertUSBDeviceFilter"/>. + + <see><link to="#USBDeviceFilters"/></see> + </desc> + <param name="name" type="wstring" dir="in"> + <desc> + Filter name. See <link to="IUSBDeviceFilter::name"/> for more information. + </desc> + </param> + <param name="filter" type="IHostUSBDeviceFilter" dir="return"> + <desc>Created filter object.</desc> + </param> + </method> + + <method name="insertUSBDeviceFilter"> + <desc> + Inserts the given USB device to the specified position + in the list of filters. + + Positions are numbered starting from @c 0. If the specified + position is equal to or greater than the number of elements in + the list, the filter is added at the end of the collection. + + <note> + Duplicates are not allowed, so an attempt to insert a + filter already in the list is an error. + </note> + <note> + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + </note> + + <see><link to="#USBDeviceFilters"/></see> + + <result name="VBOX_E_INVALID_OBJECT_STATE"> + USB device filter is not created within this VirtualBox instance. + </result> + <result name="E_INVALIDARG"> + USB device filter already in list. + </result> + + </desc> + <param name="position" type="unsigned long" dir="in"> + <desc>Position to insert the filter to.</desc> + </param> + <param name="filter" type="IHostUSBDeviceFilter" dir="in"> + <desc>USB device filter to insert.</desc> + </param> + </method> + + <method name="removeUSBDeviceFilter"> + <desc> + Removes a USB device filter from the specified position in the + list of filters. + + Positions are numbered starting from @c 0. Specifying a + position equal to or greater than the number of elements in + the list will produce an error. + + <note> + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + </note> + + <see><link to="#USBDeviceFilters"/></see> + + <result name="E_INVALIDARG"> + USB device filter list empty or invalid @a position. + </result> + + </desc> + <param name="position" type="unsigned long" dir="in"> + <desc>Position to remove the filter from.</desc> + </param> + </method> + + <method name="findHostDVDDrive"> + <desc> + Searches for a host DVD drive with the given @c name. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Given @c name does not correspond to any host drive. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the host drive to search for</desc> + </param> + <param name="drive" type="IMedium" dir="return"> + <desc>Found host drive object</desc> + </param> + </method> + + <method name="findHostFloppyDrive"> + <desc> + Searches for a host floppy drive with the given @c name. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Given @c name does not correspond to any host floppy drive. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the host floppy drive to search for</desc> + </param> + <param name="drive" type="IMedium" dir="return"> + <desc>Found host floppy drive object</desc> + </param> + </method> + + <method name="findHostNetworkInterfaceByName"> + <desc> + Searches through all host network interfaces for an interface with + the given @c name. + <note> + The method returns an error if the given @c name does not + correspond to any host network interface. + </note> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the host network interface to search for.</desc> + </param> + <param name="networkInterface" type="IHostNetworkInterface" dir="return"> + <desc>Found host network interface object.</desc> + </param> + </method> + <method name="findHostNetworkInterfaceById"> + <desc> + Searches through all host network interfaces for an interface with + the given GUID. + <note> + The method returns an error if the given GUID does not + correspond to any host network interface. + </note> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc>GUID of the host network interface to search for.</desc> + </param> + <param name="networkInterface" type="IHostNetworkInterface" dir="return"> + <desc>Found host network interface object.</desc> + </param> + </method> + <method name="findHostNetworkInterfacesOfType"> + <desc> + Searches through all host network interfaces and returns a list of interfaces of the specified type + </desc> + <param name="type" type="HostNetworkInterfaceType" dir="in"> + <desc>type of the host network interfaces to search for.</desc> + </param> + <param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return"> + <desc>Found host network interface objects.</desc> + </param> + </method> + + <method name="findUSBDeviceById"> + <desc> + Searches for a USB device with the given UUID. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Given @c id does not correspond to any USB device. + </result> + + <see><link to="IUSBDevice::id"/></see> + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc>UUID of the USB device to search for.</desc> + </param> + <param name="device" type="IHostUSBDevice" dir="return"> + <desc>Found USB device object.</desc> + </param> + </method> + + <method name="findUSBDeviceByAddress"> + <desc> + Searches for a USB device with the given host address. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Given @c name does not correspond to any USB device. + </result> + + <see><link to="IUSBDevice::address"/></see> + </desc> + <param name="name" type="wstring" dir="in"> + <desc> + Address of the USB device (as assigned by the host) to + search for. + </desc> + </param> + <param name="device" type="IHostUSBDevice" dir="return"> + <desc>Found USB device object.</desc> + </param> + </method> + + <method name="generateMACAddress"> + <desc> + Generates a valid Ethernet MAC address, 12 hexadecimal characters. + </desc> + <param name="address" type="wstring" dir="return"> + <desc>New Ethernet MAC address.</desc> + </param> + </method> + + <attribute name="videoInputDevices" type="IHostVideoInputDevice" safearray="yes" readonly="yes"> + <desc>List of currently available host video capture devices.</desc> + </attribute> + + <method name="addUSBDeviceSource"> + <desc> + Adds a new USB device source. + </desc> + <param name="backend" type="wstring" dir="in"> + <desc>The backend to use as the new device source.</desc> + </param> + <param name="id" type="wstring" dir="in"> + <desc>Unique ID to identify the source.</desc> + </param> + <param name="address" type="wstring" dir="in"> + <desc> + Address to use, the format is dependent on the backend. + For USB/IP backends for example the notation is host[:port]. + </desc> + </param> + <param name="propertyNames" type="wstring" safearray="yes" dir="in"> + <desc>Array of property names for more detailed configuration. Not used at the moment.</desc> + </param> + <param name="propertyValues" type="wstring" safearray="yes" dir="in"> + <desc>Array of property values for more detailed configuration. Not used at the moment.</desc> + </param> + </method> + + <method name="removeUSBDeviceSource"> + <desc> + Removes a previously added USB device source. + </desc> + <param name="id" type="wstring" dir="in"> + <desc>The identifier used when the source was added.</desc> + </param> + </method> + + <attribute name="updateHost" type="IUpdateAgent" readonly="yes"> + <desc>Checks for new VirtualBox host versions.</desc> + </attribute> + + <attribute name="updateExtPack" type="IUpdateAgent" readonly="yes"> + <desc>Checks for new VirtualBox Extension Pack versions.</desc> + </attribute> + + <attribute name="updateGuestAdditions" type="IUpdateAgent" readonly="yes"> + <desc>Checks for new Guest Additions versions.</desc> + </attribute> + + </interface> + + <!-- + // ICPUProfile + ///////////////////////////////////////////////////////////////////////// + --> + <interface + name="ICPUProfile" + extends="$unknown" + uuid="b7fda727-7a08-46ee-8dd8-f8d7308b519c" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc>CPU profile. Immutable.</desc> + <attribute name="name" type="wstring" readonly="yes"> + <desc>The name.</desc> + </attribute> + <attribute name="fullName" type="wstring" readonly="yes"> + <desc>The full name.</desc> + </attribute> + <attribute name="architecture" type="CPUArchitecture" readonly="yes"> + <desc>The CPU architecture.</desc> + </attribute> + </interface> + + <!-- + // ISystemProperties + ///////////////////////////////////////////////////////////////////////// + --> + + <enum name="ProxyMode" uuid="885264b3-b517-40fc-ce46-36e3bae895a4"> + <desc> Proxy setting: System (default), NoProxy and Manual. <link to="ISystemProperties::proxyMode"/></desc> + <const name="System" value="0"> + <desc>Use the system proxy settings as far as possible.</desc> + </const> + <const name="NoProxy" value="1"> + <desc>Direct connection to the Internet.</desc> + </const> + <const name="Manual" value="2"> + <desc>Use the manual proxy from <link to="ISystemProperties::proxyURL"/>.</desc> + </const> + </enum> + + <interface + name="ISystemProperties" + extends="$unknown" + uuid="aac6c7cb-a371-4c58-ab51-0616896b2f2c" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="16" + > + <desc> + The ISystemProperties interface represents global properties of the given + VirtualBox installation. + + These properties define limits and default values for various attributes + and parameters. Most of the properties are read-only, but some can be + changed by a user. + </desc> + + <attribute name="minGuestRAM" type="unsigned long" readonly="yes"> + <desc>Minimum guest system memory in Megabytes.</desc> + </attribute> + + <attribute name="maxGuestRAM" type="unsigned long" readonly="yes"> + <desc>Maximum guest system memory in Megabytes.</desc> + </attribute> + + <attribute name="minGuestVRAM" type="unsigned long" readonly="yes"> + <desc>Minimum guest video memory in Megabytes.</desc> + </attribute> + + <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes"> + <desc>Maximum guest video memory in Megabytes.</desc> + </attribute> + + <attribute name="minGuestCPUCount" type="unsigned long" readonly="yes"> + <desc>Minimum CPU count.</desc> + </attribute> + + <attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes"> + <desc>Maximum CPU count.</desc> + </attribute> + + <attribute name="maxGuestMonitors" type="unsigned long" readonly="yes"> + <desc>Maximum of monitors which could be connected.</desc> + </attribute> + + <attribute name="infoVDSize" type="long long" readonly="yes"> + <desc>Maximum size of a virtual disk image in bytes. Informational value, + does not reflect the limits of any virtual disk image format.</desc> + </attribute> + + <attribute name="serialPortCount" type="unsigned long" readonly="yes"> + <desc> + Maximum number of serial ports associated with every + <link to="IMachine"/> instance. + </desc> + </attribute> + + <attribute name="parallelPortCount" type="unsigned long" readonly="yes"> + <desc> + Maximum number of parallel ports associated with every + <link to="IMachine"/> instance. + </desc> + </attribute> + + <attribute name="maxBootPosition" type="unsigned long" readonly="yes"> + <desc> + Maximum device position in the boot order. This value corresponds + to the total number of devices a machine can boot from, to make it + possible to include all possible devices to the boot list. + <see><link to="IMachine::setBootOrder"/></see> + </desc> + </attribute> + + <attribute name="rawModeSupported" type="boolean" readonly="yes"> + <desc> + Indicates whether VirtualBox was built with raw-mode support. + + When this reads as False, the <link to="HWVirtExPropertyType_Enabled"/> + setting will be ignored and assumed to be True. + </desc> + </attribute> + + <attribute name="exclusiveHwVirt" type="boolean"> + <desc> + Exclusive use of hardware virtualization by VirtualBox. When enabled, + VirtualBox assumes it can obtain full and exclusive access to the VT-x + or AMD-V feature of the host. To share hardware virtualization with + other hypervisors, this property must be disabled. + + <note>This is ignored on OS X, the kernel mediates hardware + access there.</note> + </desc> + </attribute> + + <attribute name="defaultMachineFolder" type="wstring"> + <desc> + Full path to the default directory used to create new or open + existing machines when a machine settings file name contains no + path. + + Starting with VirtualBox 4.0, by default, this attribute contains + the full path of folder named "VirtualBox VMs" in the user's + home directory, which depends on the host platform. + + When setting this attribute, a full path must be specified. + Setting this property to @c null or an empty string or the + special value "Machines" (for compatibility reasons) will restore + that default value. + + If the folder specified herein does not exist, it will be created + automatically as needed. + + <see> + <link to="IVirtualBox::createMachine"/>, + <link to="IVirtualBox::openMachine"/> + </see> + </desc> + </attribute> + + <attribute name="loggingLevel" type="wstring"> + <desc> + Specifies the logging level in current use by VirtualBox. + </desc> + </attribute> + + <attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes"> + <desc> + List of all medium storage formats supported by this VirtualBox + installation. + + Keep in mind that the medium format identifier + (<link to="IMediumFormat::id"/>) used in other API calls like + <link to="IVirtualBox::createMedium"/> to refer to a particular + medium format is a case-insensitive string. This means that, for + example, all of the following strings: + <pre> + "VDI" + "vdi" + "VdI"</pre> + refer to the same medium format. + + Note that the virtual medium framework is backend-based, therefore + the list of supported formats depends on what backends are currently + installed. + + <see><link to="IMediumFormat"/></see> + </desc> + </attribute> + + <attribute name="defaultHardDiskFormat" type="wstring"> + <desc> + Identifier of the default medium format used by VirtualBox. + + The medium format set by this attribute is used by VirtualBox + when the medium format was not specified explicitly. One example is + <link to="IVirtualBox::createMedium"/> with the empty + format argument. A more complex example is implicit creation of + differencing media when taking a snapshot of a virtual machine: + this operation will try to use a format of the parent medium first + and if this format does not support differencing media the default + format specified by this argument will be used. + + The list of supported medium formats may be obtained by the + <link to="#mediumFormats"/> call. Note that the default medium + format must have a capability to create differencing media; + otherwise operations that create media implicitly may fail + unexpectedly. + + The initial value of this property is <tt>"VDI"</tt> in the current + version of the VirtualBox product, but may change in the future. + + <note> + Setting this property to @c null or empty string will restore the + initial value. + </note> + + <see> + <link to="#mediumFormats"/>, + <link to="IMediumFormat::id"/>, + <link to="IVirtualBox::createMedium"/> + </see> + </desc> + </attribute> + + <attribute name="freeDiskSpaceWarning" type="long long"> + <desc>Issue a warning if the free disk space is below (or in some disk + intensive operation is expected to go below) the given size in + bytes.</desc> + </attribute> + + <attribute name="freeDiskSpacePercentWarning" type="unsigned long"> + <desc>Issue a warning if the free disk space is below (or in some disk + intensive operation is expected to go below) the given percentage.</desc> + </attribute> + + <attribute name="freeDiskSpaceError" type="long long"> + <desc>Issue an error if the free disk space is below (or in some disk + intensive operation is expected to go below) the given size in + bytes.</desc> + </attribute> + + <attribute name="freeDiskSpacePercentError" type="unsigned long"> + <desc>Issue an error if the free disk space is below (or in some disk + intensive operation is expected to go below) the given percentage.</desc> + </attribute> + + <attribute name="VRDEAuthLibrary" type="wstring"> + <desc> + Library that provides authentication for Remote Desktop clients. The library + is used if a virtual machine's authentication type is set to "external" + in the VM RemoteDisplay configuration. + + The system library extension (".DLL" or ".so") must be omitted. + A full path can be specified; if not, then the library must reside on the + system's default library path. + + The default value of this property is <tt>"VBoxAuth"</tt>. There is a library + of that name in one of the default VirtualBox library directories. + + For details about VirtualBox authentication libraries and how to implement + them, please refer to the VirtualBox manual. + + <note> + Setting this property to @c null or empty string will restore the + initial value. + </note> + </desc> + </attribute> + + <attribute name="webServiceAuthLibrary" type="wstring"> + <desc> + Library that provides authentication for webservice clients. The library + is used if a virtual machine's authentication type is set to "external" + in the VM RemoteDisplay configuration and will be called from + within the <link to="IWebsessionManager::logon" /> implementation. + + As opposed to <link to="ISystemProperties::VRDEAuthLibrary" />, + there is no per-VM setting for this, as the webservice is a global + resource (if it is running). Only for this setting (for the webservice), + setting this value to a literal <tt>"null"</tt> string disables authentication, + meaning that <link to="IWebsessionManager::logon" /> will always succeed, + no matter what user name and password are supplied. + + The initial value of this property is <tt>"VBoxAuth"</tt>, + meaning that the webservice will use the same authentication + library that is used by default for VRDE (again, see + <link to="ISystemProperties::VRDEAuthLibrary" />). + The format and calling convention of authentication libraries + is the same for the webservice as it is for VRDE. + + <note> + Setting this property to @c null or empty string will restore the + initial value. + </note> + </desc> + </attribute> + + <attribute name="defaultVRDEExtPack" type="wstring"> + <desc> + The name of the extension pack providing the default VRDE. + + This attribute is for choosing between multiple extension packs + providing VRDE. If only one is installed, it will automatically be the + default one. The attribute value can be empty if no VRDE extension + pack is installed. + + For details about VirtualBox Remote Desktop Extension and how to + implement one, please refer to the VirtualBox SDK. + </desc> + </attribute> + + <attribute name="defaultCryptoExtPack" type="wstring"> + <desc> + The name of the extension pack providing the default cryptographic support + for full VM encryption. + + This attribute is for choosing between multiple extension packs + providing cryptographic support. If only one is installed, it will automatically be the + default one. The attribute value can be empty if no cryptographic extension + pack is installed. + </desc> + </attribute> + + <attribute name="logHistoryCount" type="unsigned long"> + <desc> + This value specifies how many old release log files are kept. + </desc> + </attribute> + + <attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes"> + <desc>This value hold the default audio driver for the current + system.</desc> + </attribute> + + <attribute name="autostartDatabasePath" type="wstring"> + <desc> + The path to the autostart database. Depending on the host this might + be a filesystem path or something else. + </desc> + </attribute> + + <attribute name="defaultAdditionsISO" type="wstring"> + <desc> + The path to the default Guest Additions ISO image. Can be empty if + the location is not known in this installation. + </desc> + </attribute> + + <attribute name="defaultFrontend" type="wstring"> + <desc> + Selects which VM frontend should be used by default when launching + a VM through the <link to="IMachine::launchVMProcess" /> method. + Empty or @c null strings do not define a particular default, it is up + to <link to="IMachine::launchVMProcess" /> to select one. See the + description of <link to="IMachine::launchVMProcess" /> for the valid + frontend types. + + This global setting is overridden by the per-VM attribute + <link to="IMachine::defaultFrontend" /> or a frontend type + passed to <link to="IMachine::launchVMProcess" />. + </desc> + </attribute> + + <attribute name="screenShotFormats" type="BitmapFormat" safearray="yes" readonly="yes"> + <desc> + Supported bitmap formats which can be used with takeScreenShot + and takeScreenShotToArray methods. + </desc> + </attribute> + + <attribute name="proxyMode" type="ProxyMode"> + <desc> The proxy mode setting: System, NoProxy or Manual.</desc> + </attribute> + + <attribute name="proxyURL" type="wstring"> + <desc> + Proxy server URL for the <link to="ProxyMode_Manual" /> proxy mode. + + The format is: [{type}"://"][{userid}[:{password}]@]{server}[":"{port}] + + Valid types are: http (default), https, socks4, socks4a, socks5, socks5h and direct. + Please note that these are proxy types defining how the proxy operates rather than + how to proxy any similarly named protocol (i.e. don't confuse a http-proxy with + proxying the http protocol, as a http-proxy usually can proxy https and other protocols too). + + The port number defaults to 80 for http, 443 for https and 1080 for the socks ones. + + <note>The password is currently stored as plain text! Use the <link to="ProxyMode_System" /> + mode if you consider the proxy password to be sensitive.</note> + + An empty string will cause the behavior to be identical to <link to="ProxyMode_System" />. + For compatibility with libproxy, an URL starting with "direct://" will cause + <link to="ProxyMode_NoProxy" /> behavior. + </desc> + </attribute> + + <attribute name="supportedParavirtProviders" type="ParavirtProvider" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="ParavirtProvider"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedClipboardModes" type="ClipboardMode" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="ClipboardMode"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedDnDModes" type="DnDMode" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="DnDMode"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedFirmwareTypes" type="FirmwareType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="FirmwareType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedPointingHIDTypes" type="PointingHIDType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="PointingHIDType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedKeyboardHIDTypes" type="KeyboardHIDType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="KeyboardHIDType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedVFSTypes" type="VFSType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="VFSType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedImportOptions" type="ImportOptions" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="ImportOptions"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedExportOptions" type="ExportOptions" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="ExportOptions"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedRecordingFeatures" type="RecordingFeature" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="RecordingFeature"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedRecordingAudioCodecs" type="RecordingAudioCodec" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="RecordingAudioCodec"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedRecordingVideoCodecs" type="RecordingVideoCodec" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="RecordingVideoCodec"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedRecordingVSModes" type="RecordingVideoScalingMode" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="RecordingVideoScalingMode"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedRecordingARCModes" type="RecordingRateControlMode" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported audio codec values for enum <link to="RecordingRateControlMode"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedRecordingVRCModes" type="RecordingRateControlMode" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported video codec values for enum <link to="RecordingRateControlMode"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedGraphicsControllerTypes" type="GraphicsControllerType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="GraphicsControllerType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedCloneOptions" type="CloneOptions" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="CloneOptions"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedAutostopTypes" type="AutostopType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="AutostopType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedVMProcPriorities" type="VMProcPriority" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="VMProcPriority"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedNetworkAttachmentTypes" type="NetworkAttachmentType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="NetworkAttachmentType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedNetworkAdapterTypes" type="NetworkAdapterType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="NetworkAdapterType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedPortModes" type="PortMode" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="PortMode"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedUartTypes" type="UartType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="UartType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedUSBControllerTypes" type="USBControllerType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="USBControllerType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedAudioDriverTypes" type="AudioDriverType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="AudioDriverType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedAudioControllerTypes" type="AudioControllerType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="AudioControllerType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedStorageBuses" type="StorageBus" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="StorageBus"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedStorageControllerTypes" type="StorageControllerType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="StorageControllerType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedChipsetTypes" type="ChipsetType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="ChipsetType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedIommuTypes" type="IommuType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="IommuType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="supportedTpmTypes" type="TpmType" safearray="yes" readonly="yes"> + <desc> + Returns an array of officially supported values for enum <link to="TpmType"/>, + in the sense of what is e.g. worth offering in the VirtualBox GUI. + </desc> + </attribute> + + <attribute name="languageId" type="wstring"> + <desc> + The API language ID used to translate messages to client. + </desc> + </attribute> + + <method name="getMaxNetworkAdapters"> + <desc> + Maximum total number of network adapters associated with every + <link to="IMachine"/> instance. + </desc> + + <param name="chipset" type="ChipsetType" dir="in"> + <desc>The chipset type to get the value for.</desc> + </param> + + + <param name="maxNetworkAdapters" type="unsigned long" dir="return"> + <desc>The maximum total number of network adapters allowed.</desc> + </param> + + </method> + + <method name="getMaxNetworkAdaptersOfType"> + <desc> + Maximum number of network adapters of a given attachment type, + associated with every <link to="IMachine"/> instance. + </desc> + + <param name="chipset" type="ChipsetType" dir="in"> + <desc>The chipset type to get the value for.</desc> + </param> + + <param name="type" type="NetworkAttachmentType" dir="in"> + <desc>Type of attachment.</desc> + </param> + + <param name="maxNetworkAdapters" type="unsigned long" dir="return"> + <desc>The maximum number of network adapters allowed for + particular chipset and attachment type.</desc> + </param> + + </method> + + + <method name="getMaxDevicesPerPortForStorageBus"> + <desc>Returns the maximum number of devices which can be attached to a port + for the given storage bus.</desc> + + <param name="bus" type="StorageBus" dir="in"> + <desc>The storage bus type to get the value for.</desc> + </param> + + <param name="maxDevicesPerPort" type="unsigned long" dir="return"> + <desc>The maximum number of devices which can be attached to the port for the given + storage bus.</desc> + </param> + </method> + + <method name="getMinPortCountForStorageBus"> + <desc>Returns the minimum number of ports the given storage bus supports.</desc> + + <param name="bus" type="StorageBus" dir="in"> + <desc>The storage bus type to get the value for.</desc> + </param> + + <param name="minPortCount" type="unsigned long" dir="return"> + <desc>The minimum number of ports for the given storage bus.</desc> + </param> + </method> + + <method name="getMaxPortCountForStorageBus"> + <desc>Returns the maximum number of ports the given storage bus supports.</desc> + + <param name="bus" type="StorageBus" dir="in"> + <desc>The storage bus type to get the value for.</desc> + </param> + + <param name="maxPortCount" type="unsigned long" dir="return"> + <desc>The maximum number of ports for the given storage bus.</desc> + </param> + </method> + + <method name="getMaxInstancesOfStorageBus"> + <desc>Returns the maximum number of storage bus instances which + can be configured for each VM. This corresponds to the number of + storage controllers one can have. Value may depend on chipset type + used.</desc> + + <param name="chipset" type="ChipsetType" dir="in"> + <desc>The chipset type to get the value for.</desc> + </param> + + <param name="bus" type="StorageBus" dir="in"> + <desc>The storage bus type to get the value for.</desc> + </param> + + <param name="maxInstances" type="unsigned long" dir="return"> + <desc>The maximum number of instances for the given storage bus.</desc> + </param> + </method> + + <method name="getDeviceTypesForStorageBus"> + <desc>Returns list of all the supported device types + (<link to="DeviceType"/>) for the given type of storage + bus.</desc> + + <param name="bus" type="StorageBus" dir="in"> + <desc>The storage bus type to get the value for.</desc> + </param> + + <param name="deviceTypes" type="DeviceType" safearray="yes" dir="return"> + <desc>The list of all supported device types for the given storage bus.</desc> + </param> + </method> + + <method name="getStorageBusForStorageControllerType"> + <desc>Returns the <link to="StorageBus"/> enum value + for a given storage controller type.</desc> + + <param name="storageControllerType" type="StorageControllerType" dir="in"> + <desc>The storage controller type to get the value for.</desc> + </param> + + <param name="storageBus" type="StorageBus" dir="return"> + <desc>The storage bus which is applicable.</desc> + </param> + </method> + + <method name="getStorageControllerTypesForStorageBus"> + <desc>Returns the possible <link to="StorageControllerType"/> enum values + for a given storage bus.</desc> + + <param name="storageBus" type="StorageBus" dir="in"> + <desc>The storage bus type to get the values for.</desc> + </param> + + <param name="storageControllerType" type="StorageControllerType" safearray="yes" dir="return"> + <desc>The enum values (sorted by what should be a sensible decreasing + importance of the type) which are valid.</desc> + </param> + </method> + + <method name="getDefaultIoCacheSettingForStorageController" dtracename="getDefaultStorageCtrlCacheSetting"> + <desc>Returns the default I/O cache setting for the + given storage controller</desc> + + <param name="controllerType" type="StorageControllerType" dir="in"> + <desc>The storage controller type to get the setting for.</desc> + </param> + + <param name="enabled" type="boolean" dir="return"> + <desc>Returned flag indicating the default value</desc> + </param> + </method> + + <method name="getStorageControllerHotplugCapable"> + <desc>Returns whether the given storage controller supports + hot-plugging devices.</desc> + + <param name="controllerType" type="StorageControllerType" dir="in"> + <desc>The storage controller to check the setting for.</desc> + </param> + + <param name="hotplugCapable" type="boolean" dir="return"> + <desc>Returned flag indicating whether the controller is hotplug capable</desc> + </param> + </method> + + <method name="getMaxInstancesOfUSBControllerType"> + <desc>Returns the maximum number of USB controller instances which + can be configured for each VM. This corresponds to the number of + USB controllers one can have. Value may depend on chipset type + used.</desc> + + <param name="chipset" type="ChipsetType" dir="in"> + <desc>The chipset type to get the value for.</desc> + </param> + + <param name="type" type="USBControllerType" dir="in"> + <desc>The USB controller type to get the value for.</desc> + </param> + + <param name="maxInstances" type="unsigned long" dir="return"> + <desc>The maximum number of instances for the given USB controller type.</desc> + </param> + </method> + + <method name="getCPUProfiles"> + <desc>Returns CPU profiles matching the given criteria.</desc> + + <param name="architecture" type="CPUArchitecture" dir="in"> + <desc>The architecture to get profiles for. Required.</desc> + </param> + <param name="namePattern" type="wstring" dir="in"> + <desc>Name pattern. Simple wildcard matching using asterisk (*) and + question mark (?).</desc> + </param> + <param name="profiles" type="ICPUProfile" safearray="yes" dir="return"> + <desc>The matching CPU profiles.</desc> + </param> + </method> + </interface> + + <!-- + // IGuest + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IGuestOSType" extends="$unknown" + uuid="966303d0-36a8-4180-8971-18650b0d1055" + wsmap="struct" + rest="managed" + reservedAttributes="16" + > + <desc> + </desc> + + <attribute name="familyId" type="wstring" readonly="yes"> + <desc>Guest OS family identifier string.</desc> + </attribute> + + <attribute name="familyDescription" type="wstring" readonly="yes"> + <desc>Human readable description of the guest OS family.</desc> + </attribute> + + <attribute name="id" type="wstring" readonly="yes"> + <desc>Guest OS identifier string.</desc> + </attribute> + + <attribute name="description" type="wstring" readonly="yes"> + <desc>Human readable description of the guest OS.</desc> + </attribute> + + <attribute name="is64Bit" type="boolean" readonly="yes"> + <desc>Returns @c true if the given OS is 64-bit</desc> + </attribute> + + <attribute name="recommendedIOAPIC" type="boolean" readonly="yes"> + <desc>Returns @c true if I/O-APIC recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedVirtEx" type="boolean" readonly="yes"> + <desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedRAM" type="unsigned long" readonly="yes"> + <desc>Recommended RAM size in Megabytes.</desc> + </attribute> + + <attribute name="recommendedGraphicsController" type="GraphicsControllerType" readonly="yes"> + <desc>Recommended graphics controller type.</desc> + </attribute> + + <attribute name="recommendedVRAM" type="unsigned long" readonly="yes"> + <desc>Recommended video RAM size in Megabytes.</desc> + </attribute> + + <attribute name="recommended2DVideoAcceleration" type="boolean" readonly="yes"> + <desc>Returns @c true if 2D video acceleration is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommended3DAcceleration" type="boolean" readonly="yes"> + <desc>Returns @c true if 3D acceleration is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedHDD" type="long long" readonly="yes"> + <desc>Recommended hard disk size in bytes.</desc> + </attribute> + + <attribute name="adapterType" type="NetworkAdapterType" readonly="yes"> + <desc>Returns recommended network adapter for this OS type.</desc> + </attribute> + + <attribute name="recommendedPAE" type="boolean" readonly="yes"> + <desc>Returns @c true if using PAE is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedDVDStorageController" type="StorageControllerType" readonly="yes"> + <desc>Recommended storage controller type for DVD/CD drives.</desc> + </attribute> + + <attribute name="recommendedDVDStorageBus" type="StorageBus" readonly="yes"> + <desc>Recommended storage bus type for DVD/CD drives.</desc> + </attribute> + + <attribute name="recommendedHDStorageController" type="StorageControllerType" readonly="yes"> + <desc>Recommended storage controller type for HD drives.</desc> + </attribute> + + <attribute name="recommendedHDStorageBus" type="StorageBus" readonly="yes"> + <desc>Recommended storage bus type for HD drives.</desc> + </attribute> + + <attribute name="recommendedFirmware" type="FirmwareType" readonly="yes"> + <desc>Recommended firmware type.</desc> + </attribute> + + <attribute name="recommendedUSBHID" type="boolean" readonly="yes"> + <desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc> + </attribute> + + <attribute name="recommendedHPET" type="boolean" readonly="yes"> + <desc>Returns @c true if using HPET is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedUSBTablet" type="boolean" readonly="yes"> + <desc>Returns @c true if using a USB Tablet is recommended.</desc> + </attribute> + + <attribute name="recommendedRTCUseUTC" type="boolean" readonly="yes"> + <desc>Returns @c true if the RTC of this VM should be set to UTC</desc> + </attribute> + + <attribute name="recommendedChipset" type="ChipsetType" readonly="yes"> + <desc>Recommended chipset type.</desc> + </attribute> + + <attribute name="recommendedIommuType" type="IommuType" readonly="yes"> + <desc>Recommended IOMMU type.</desc> + </attribute> + + <attribute name="recommendedAudioController" type="AudioControllerType" readonly="yes"> + <desc>Recommended audio controller type.</desc> + </attribute> + + <attribute name="recommendedAudioCodec" type="AudioCodecType" readonly="yes"> + <desc>Recommended audio codec type.</desc> + </attribute> + + <attribute name="recommendedFloppy" type="boolean" readonly="yes"> + <desc>Returns @c true a floppy drive is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedUSB" type="boolean" readonly="yes"> + <desc>Returns @c true a USB controller is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedUSB3" type="boolean" readonly="yes"> + <desc>Returns @c true an xHCI (USB 3) controller is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedTFReset" type="boolean" readonly="yes"> + <desc>Returns @c true if using VCPU reset on triple fault is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedX2APIC" type="boolean" readonly="yes"> + <desc>Returns @c true if X2APIC is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedCPUCount" type="unsigned long" readonly="yes"> + <desc>Number of vCPUs recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedTpmType" type="TpmType" readonly="yes"> + <desc>Returns the recommended trusted platform module type for this OS type.</desc> + </attribute> + + <attribute name="recommendedSecureBoot" type="boolean" readonly="yes"> + <desc>Returns @c true if EFI secure boot is recommended for this OS type.</desc> + </attribute> + + <attribute name="recommendedWDDMGraphics" type="boolean" readonly="yes"> + <desc>Returns @c true if this OS usually has a WDDM graphics driver + from guest additions.</desc> + </attribute> + + </interface> + + <enum + name="AdditionsFacilityType" + uuid="c4b10d74-dd48-4ff4-9a40-785a2a389ade" + > + <desc> + Guest Additions facility IDs. + </desc> + + <const name="None" value="0"> + <desc>No/invalid facility.</desc> + </const> + <const name="VBoxGuestDriver" value="20"> + <desc>VirtualBox base driver (VBoxGuest).</desc> + </const> + <const name="AutoLogon" value="90"> + <desc>Auto-logon modules (VBoxGINA, VBoxCredProv, pam_vbox).</desc> + </const> + <const name="VBoxService" value="100"> + <desc>VirtualBox system service (VBoxService).</desc> + </const> + <const name="VBoxTrayClient" value="101"> + <desc>VirtualBox desktop integration (VBoxTray on Windows, VBoxClient on non-Windows).</desc> + </const> + <const name="Seamless" value="1000"> + <desc>Seamless guest desktop integration.</desc> + </const> + <const name="Graphics" value="1100"> + <desc>Guest graphics mode. If not enabled, seamless rendering will not work, resize hints + are not immediately acted on and guest display resizes are probably not initiated by + the Guest Additions. + </desc> + </const> + <const name="MonitorAttach" value="1101"> + <desc>Guest supports monitor hotplug. + </desc> + </const> + <const name="All" value="2147483646"> + <desc>All facilities selected.</desc> + </const> + </enum> + + <enum + name="AdditionsFacilityClass" + uuid="446451b2-c88d-4e5d-84c9-91bc7f533f5f" + > + <desc> + Guest Additions facility classes. + </desc> + + <const name="None" value="0"> + <desc>No/invalid class.</desc> + </const> + <const name="Driver" value="10"> + <desc>Driver.</desc> + </const> + <const name="Service" value="30"> + <desc>System service.</desc> + </const> + <const name="Program" value="50"> + <desc>Program.</desc> + </const> + <const name="Feature" value="100"> + <desc>Feature.</desc> + </const> + <const name="ThirdParty" value="999"> + <desc>Third party.</desc> + </const> + <const name="All" value="2147483646"> + <desc>All facility classes selected.</desc> + </const> + </enum> + + <enum + name="AdditionsFacilityStatus" + uuid="ce06f9e1-394e-4fe9-9368-5a88c567dbde" + > + <desc> + Guest Additions facility states. + </desc> + + <const name="Inactive" value="0"> + <desc>Facility is not active.</desc> + </const> + <const name="Paused" value="1"> + <desc>Facility has been paused.</desc> + </const> + <const name="PreInit" value="20"> + <desc>Facility is preparing to initialize.</desc> + </const> + <const name="Init" value="30"> + <desc>Facility is initializing.</desc> + </const> + <const name="Active" value="50"> + <desc>Facility is up and running.</desc> + </const> + <const name="Terminating" value="100"> + <desc>Facility is shutting down.</desc> + </const> + <const name="Terminated" value="101"> + <desc>Facility successfully shut down.</desc> + </const> + <const name="Failed" value="800"> + <desc>Facility failed to start.</desc> + </const> + <const name="Unknown" value="999"> + <desc>Facility status is unknown.</desc> + </const> + </enum> + + <interface + name="IAdditionsFacility" extends="$unknown" + uuid="f2f7fae4-4a06-81fc-a916-78b2da1fa0e5" + wsmap="struct" + rest="managed" + reservedAttributes="2" + > + <desc> + Structure representing a Guest Additions facility. + </desc> + + <attribute name="classType" type="AdditionsFacilityClass" readonly="yes"> + <desc>The class this facility is part of.</desc> + </attribute> + + <attribute name="lastUpdated" type="long long" readonly="yes"> + <desc> + Timestamp of the last status update, + in milliseconds since 1970-01-01 UTC. + </desc> + </attribute> + + <attribute name="name" type="wstring" readonly="yes"> + <desc>The facility's friendly name.</desc> + </attribute> + + <attribute name="status" type="AdditionsFacilityStatus" readonly="yes"> + <desc>The current status.</desc> + </attribute> + + <attribute name="type" type="AdditionsFacilityType" readonly="yes"> + <desc>The facility's type ID.</desc> + </attribute> + </interface> + + <enum + name="AdditionsRunLevelType" + uuid="a25417ee-a9dd-4f5b-b0dc-377860087754" + > + <desc> + Guest Additions run level type. + </desc> + + <const name="None" value="0"> + <desc>Guest Additions are not loaded.</desc> + </const> + <const name="System" value="1"> + <desc>Guest drivers are loaded.</desc> + </const> + <const name="Userland" value="2"> + <desc>Common components (such as application services) are loaded.</desc> + </const> + <const name="Desktop" value="3"> + <desc>Per-user desktop components are loaded.</desc> + </const> + </enum> + + <enum + name="AdditionsUpdateFlag" + uuid="726a818d-18d6-4389-94e8-3e9e6826171a" + > + <desc> + Guest Additions update flags. + </desc> + + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="WaitForUpdateStartOnly" value="1"> + <desc>Starts the regular updating process and waits until the + actual Guest Additions update inside the guest was started. + This can be necessary due to needed interaction with the guest + OS during the installation phase.</desc> + </const> + </enum> + + <enum + name="GuestShutdownFlag" + uuid="28D19C9C-5862-4930-B29A-F117712B4864" + > + <desc> + Guest shutdown flags. + </desc> + + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="PowerOff" value="1"> + <desc>Performs a reboot after shutdown.</desc> + </const> + <const name="Reboot" value="2"> + <desc>Performs a reboot after shutdown.</desc> + </const> + <const name="Force" value="4"> + <desc>Force the system to shutdown/reboot regardless of objecting + application or other stuff. This flag might not be realized on + all systems.</desc> + </const> + </enum> + + <enum + name="GuestSessionStatus" + uuid="ac2669da-4624-44f2-85b5-0b0bfb8d8673" + > + <desc> + Guest session status. This enumeration represents possible values of + the <link to="IGuestSession::status"/> attribute. + </desc> + <const name="Undefined" value="0"> + <desc>Guest session is in an undefined state.</desc> + </const> + <const name="Starting" value="10"> + <desc>Guest session is being started.</desc> + </const> + <const name="Started" value="100"> + <desc>Guest session has been started.</desc> + </const> + <const name="Terminating" value="480"> + <desc>Guest session is being terminated.</desc> + </const> + <const name="Terminated" value="500"> + <desc>Guest session terminated normally.</desc> + </const> + <const name="TimedOutKilled" value="512"> + <desc>Guest session timed out and was killed.</desc> + </const> + <const name="TimedOutAbnormally" value="513"> + <desc>Guest session timed out and was not killed successfully.</desc> + </const> + <const name="Down" value="600"> + <desc>Service/OS is stopping, guest session was killed.</desc> + </const> + <const name="Error" value="800"> + <desc>Something went wrong.</desc> + </const> + </enum> + + <enum + name="GuestSessionWaitForFlag" + uuid="bb7a372a-f635-4e11-a81a-e707f3a52ef5" + > + <desc> + Guest session waiting flags. + </desc> + + <const name="None" value="0"> + <desc>No waiting flags specified. Do not use this.</desc> + </const> + <const name="Start" value="1"> + <desc>Wait for the guest session being started.</desc> + </const> + <const name="Terminate" value="2"> + <desc>Wait for the guest session being terminated.</desc> + </const> + <const name="Status" value="4"> + <desc>Wait for the next guest session status change.</desc> + </const> + </enum> + + <enum + name="GuestSessionWaitResult" + uuid="c0f6a8a5-fdb6-42bf-a582-56c6f82bcd2d" + > + <desc> + Guest session waiting results. Depending on the session waiting flags (for + more information see <link to="GuestSessionWaitForFlag"/>) the waiting result + can vary based on the session's current status. + + To wait for a guest session to terminate after it has been + created by <link to="IGuest::createSession"/> one would specify + GuestSessionWaitResult_Terminate. + </desc> + + <const name="None" value="0"> + <desc>No result was returned. Not being used.</desc> + </const> + <const name="Start" value="1"> + <desc>The guest session has been started.</desc> + </const> + <const name="Terminate" value="2"> + <desc>The guest session has been terminated.</desc> + </const> + <const name="Status" value="3"> + <desc> + The guest session has changed its status. The status then can + be retrieved via <link to="IGuestSession::status"/>. + </desc> + </const> + <const name="Error" value="4"> + <desc>Error while executing the process.</desc> + </const> + <const name="Timeout" value="5"> + <desc> + The waiting operation timed out. This also will happen + when no event has been occurred matching the + current waiting flags in a <link to="IGuestSession::waitFor"/> call. + </desc> + </const> + <const name="WaitFlagNotSupported" value="6"> + <desc> + A waiting flag specified in the <link to="IGuestSession::waitFor"/> call + is not supported by the guest. + </desc> + </const> + </enum> + + <enum + name="GuestUserState" + uuid="b2a82b02-fd3d-4fc2-ba84-6ba5ac8be198" + > + <desc> + State a guest user has been changed to. + </desc> + + <const name="Unknown" value="0"> + <desc>Unknown state. Not being used.</desc> + </const> + <const name="LoggedIn" value="1"> + <desc>A guest user has been successfully logged into + the guest OS. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="LoggedOut" value="2"> + <desc>A guest user has been successfully logged out + of the guest OS. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Locked" value="3"> + <desc>A guest user has locked its account. This might + include running a password-protected screensaver + in the guest. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Unlocked" value="4"> + <desc>A guest user has unlocked its account. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Disabled" value="5"> + <desc>A guest user has been disabled by the guest OS. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Idle" value="6"> + <desc> + A guest user currently is not using the guest OS. + <note>Currently only available for Windows guests since + Windows 2000 SP2.</note> + <note>On Windows guests this function currently only supports + reporting contiguous idle times up to 49.7 days per user.</note> + The event will be triggered if a guest user is not active for + at least 5 seconds. This threshold can be adjusted by either altering + VBoxService's command line in the guest to + <pre>--vminfo-user-idle-threshold <ms></pre> + , or by setting the per-VM guest property + <pre>/VirtualBox/GuestAdd/VBoxService/--vminfo-user-idle-threshold <ms></pre> + with the RDONLYGUEST flag on the host. In both cases VBoxService needs + to be restarted in order to get the changes applied. + </desc> + </const> + <const name="InUse" value="7"> + <desc>A guest user continued using the guest OS after + being idle.</desc> + </const> + <const name="Created" value="8"> + <desc>A guest user has been successfully created. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Deleted" value="9"> + <desc>A guest user has been successfully deleted. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="SessionChanged" value="10"> + <desc>To guest OS has changed the session of a user. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="CredentialsChanged" value="11"> + <desc>To guest OS has changed the authentication + credentials of a user. This might include changed passwords + and authentication types. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="RoleChanged" value="12"> + <desc>To guest OS has changed the role of a user permanently, + e.g. granting / denying administrative rights. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="GroupAdded" value="13"> + <desc>To guest OS has added a user to a specific + user group. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="GroupRemoved" value="14"> + <desc>To guest OS has removed a user from a specific + user group. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Elevated" value="15"> + <desc>To guest OS temporarily has elevated a user + to perform a certain task. + <note>This property is not implemented yet!</note> + </desc> + </const> + </enum> + + <enum + name="FileSeekOrigin" + uuid="ad32f789-4279-4530-979c-f16892e1c263" + > + <desc> + What a file seek (<link to="IFile::seek"/>) is relative to. + </desc> + + <const name="Begin" value="0"> + <desc>Seek from the beginning of the file.</desc> + </const> + <const name="Current" value="1"> + <desc>Seek from the current file position.</desc> + </const> + <const name="End" value="2"> + <desc>Seek relative to the end of the file. To seek to the position two + bytes from the end of the file, specify -2 as the seek offset.</desc> + </const> + </enum> + + <enum + name="ProcessInputFlag" + uuid="5d38c1dd-2604-4ddf-92e5-0c0cdd3bdbd5" + > + <desc> + Guest process input flags. + </desc> + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="EndOfFile" value="1"> + <desc>End of file (input) reached.</desc> + </const> + </enum> + + <enum + name="ProcessOutputFlag" + uuid="9979e85a-52bb-40b7-870c-57115e27e0f1" + > + <desc> + Guest process output flags for specifying which + type of output to retrieve. + </desc> + <const name="None" value="0"> + <desc>No flags set. Get output from stdout.</desc> + </const> + <const name="StdErr" value="1"> + <desc>Get output from stderr.</desc> + </const> + </enum> + + <enum + name="ProcessWaitForFlag" + uuid="23b550c7-78e1-437e-98f0-65fd9757bcd2" + > + <desc> + Process waiting flags. + </desc> + + <const name="None" value="0"> + <desc>No waiting flags specified. Do not use this.</desc> + </const> + <const name="Start" value="1"> + <desc>Wait for the process being started.</desc> + </const> + <const name="Terminate" value="2"> + <desc>Wait for the process being terminated.</desc> + </const> + <const name="StdIn" value="4"> + <desc>Wait for stdin becoming available.</desc> + </const> + <const name="StdOut" value="8"> + <desc>Wait for data becoming available on stdout.</desc> + </const> + <const name="StdErr" value="16"> + <desc>Wait for data becoming available on stderr.</desc> + </const> + </enum> + + <enum + name="ProcessWaitResult" + uuid="40719cbe-f192-4fe9-a231-6697b3c8e2b4" + > + <desc> + Process waiting results. Depending on the process waiting flags (for + more information see <link to="ProcessWaitForFlag"/>) the waiting result + can vary based on the processes' current status. + + To wait for a guest process to terminate after it has been + created by <link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/> + one would specify ProcessWaitFor_Terminate. + + If a guest process has been started with ProcessCreateFlag_WaitForStdOut + a client can wait with ProcessWaitResult_StdOut for new data to arrive on + stdout; same applies for ProcessCreateFlag_WaitForStdErr and + ProcessWaitResult_StdErr. + </desc> + + <const name="None" value="0"> + <desc>No result was returned. Not being used.</desc> + </const> + <const name="Start" value="1"> + <desc>The process has been started.</desc> + </const> + <const name="Terminate" value="2"> + <desc>The process has been terminated.</desc> + </const> + <const name="Status" value="3"> + <desc> + The process has changed its status. The status then can + be retrieved via <link to="IProcess::status"/>. + </desc> + </const> + <const name="Error" value="4"> + <desc>Error while executing the process.</desc> + </const> + <const name="Timeout" value="5"> + <desc> + The waiting operation timed out. Also use if the guest process has + timed out in the guest side (kill attempted). + </desc> + </const> + <const name="StdIn" value="6"> + <desc>The process signalled that stdin became available for writing.</desc> + </const> + <const name="StdOut" value="7"> + <desc>Data on stdout became available for reading.</desc> + </const> + <const name="StdErr" value="8"> + <desc>Data on stderr became available for reading.</desc> + </const> + <const name="WaitFlagNotSupported" value="9"> + <desc> + A waiting flag specified in the <link to="IProcess::waitFor"/> call + is not supported by the guest. + </desc> + </const> + </enum> + + <enum + name="FileCopyFlag" + uuid="791909d7-4c64-2fa4-4303-adb10658d347" + > + <desc> + File copying flags. + </desc> + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="NoReplace" value="1"> + <!-- Would make more sense to not replace by default, however we the GAs + only supports replacing as of writing, so we currently have no choice. --> + <desc> + Do not replace the destination file if it exists. + </desc> + </const> + <const name="FollowLinks" value="2"> + <desc> + Follow symbolic links. + </desc> + </const> + <const name="Update" value="4"> + <desc> + Only copy when the source file is newer than the destination file + or when the destination file is missing. + </desc> + </const> + </enum> + + <enum + name="FsObjMoveFlag" + uuid="2450a05d-80c6-4c96-9a17-94d73293ff86" + > + <desc> + File moving flags. + </desc> + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="Replace" value="1"> + <desc> + Replace the destination file, symlink, etc if it exists, however this + does not allow replacing any directories. + </desc> + </const> + <const name="FollowLinks" value="2"> + <desc> + Follow symbolic links in the final components or not (only applied to + the given source and target paths, not to anything else). + </desc> + </const> + <const name="AllowDirectoryMoves" value="4"> + <desc> + Allow moving directories accross file system boundraries. Because it + is could be a big undertaking, we require extra assurance that we + should do it when requested. + </desc> + </const> + </enum> + + <enum + name="DirectoryCreateFlag" + uuid="bd721b0e-ced5-4f79-b368-249897c32a36" + > + <desc> + Directory creation flags. + </desc> + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="Parents" value="1"> + <desc>No error if existing, make parent directories as needed.</desc> + </const> + </enum> + + <enum + name="DirectoryCopyFlag" + uuid="20108C67-B1EB-4EF6-869B-25539A47A18E" + > + <desc> + Directory copying flags. + </desc> + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="CopyIntoExisting" value="1"> + <desc>Allow copying into an existing destination directory.</desc> + </const> + <const name="Recursive" value="2"> + <desc>Copy directories recursively.</desc> + </const> + <const name="FollowLinks" value="4"> + <desc>Follow symbolic links.</desc> + </const> + <!-- Later, basically have to see what cp and xcopy offers. --> + </enum> + + <enum + name="DirectoryRemoveRecFlag" + uuid="455aabf0-7692-48f6-9061-f21579b65769" + > + <desc> + Directory recursive removement flags. + </desc> + + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="ContentAndDir" value="1"> + <desc>Delete the content of the directory and the directory itself.</desc> + </const> + <const name="ContentOnly" value="2"> + <desc>Only delete the content of the directory, omit the directory it self.</desc> + </const> + </enum> + + <enum + name="FsObjRenameFlag" + uuid="59bbf3a1-4e23-d7cf-05d5-ccae32080ed2" + > + <desc> + Flags for use when renaming file system objects (files, directories, + symlink, etc), see <link to="IGuestSession::fsObjRename"/>. + </desc> + + <const name="NoReplace" value="0"> + <desc>Do not replace any destination object.</desc> + </const> + <const name="Replace" value="1"> + <desc>This will attempt to replace any destination object other except + directories. (The default is to fail if the destination exists.)</desc> + </const> + </enum> + + <enum + name="ProcessCreateFlag" + uuid="C544CD2B-F02D-4886-9901-71C523DB8DC5" + > + <desc> + Guest process execution flags. + <note>The values are passed to the Guest Additions, so its not possible + to change (move) or reuse values.here. See GUEST_PROC_CREATE_FLAG_XXX + in GuestControlSvc.h.</note> + </desc> + + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="WaitForProcessStartOnly" value="1"> + <desc>Only use the specified timeout value to wait for starting the guest process - the guest + process itself then uses an infinite timeout.</desc> + </const> + <const name="IgnoreOrphanedProcesses" value="2"> + <desc>Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down.</desc> + </const> + <const name="Hidden" value="4"> + <desc>Do not show the started process according to the guest OS guidelines.</desc> + </const> + <const name="Profile" value="8"> + <desc>Utilize the user's profile data when exeuting a process. Only available for Windows guests at the moment.</desc> + </const> + <const name="WaitForStdOut" value="16"> + <desc>The guest process waits until all data from stdout is read out.</desc> + </const> + <const name="WaitForStdErr" value="32"> + <desc>The guest process waits until all data from stderr is read out.</desc> + </const> + <const name="ExpandArguments" value="64"> + <desc>Expands environment variables in process arguments. + <note> + This is not yet implemented and is currently silently ignored. + We will document the protocolVersion number for this feature once it + appears, so don't use it till then. + </note> + </desc> + </const> + <const name="UnquotedArguments" value="128"> + <desc>Work around for Windows and OS/2 applications not following normal + argument quoting and escaping rules. The arguments are passed to the + application without any extra quoting, just a single space between each. + <note>Present since VirtualBox 4.3.28 and 5.0 beta 3.</note> + </desc> + </const> + </enum> + + <enum + name="ProcessPriority" + uuid="ee8cac50-e232-49fe-806b-d1214d9c2e49" + > + <desc> + Process priorities. + </desc> + + <const name="Invalid" value="0"> + <desc>Invalid priority, do not use.</desc> + </const> + <const name="Default" value="1"> + <desc>Default process priority determined by the OS.</desc> + </const> + </enum> + + <enum + name="SymlinkType" + uuid="37794668-f8f1-4714-98a5-6f8fa2ed0118" + > + <desc> + Symbolic link types. This is significant when creating links on the + Windows platform, ignored elsewhere. + </desc> + + <const name="Unknown" value="0"> + <desc>It is not known what is being targeted.</desc> + </const> + <const name="Directory" value="1"> + <desc>The link targets a directory.</desc> + </const> + <const name="File" value="2"> + <desc>The link targets a file (or whatever else except directories).</desc> + </const> + </enum> + + <enum + name="SymlinkReadFlag" + uuid="b7fe2b9d-790e-4b25-8adf-1ca33026931f" + > + <desc> + Symbolic link reading flags. + </desc> + + <const name="None" value="0"> + <desc>No flags set.</desc> + </const> + <const name="NoSymlinks" value="1"> + <desc>Don't allow symbolic links as part of the path.</desc> + </const> + </enum> + + <enum + name="ProcessStatus" + uuid="4d52368f-5b48-4bfe-b486-acf89139b52f" + > + <desc> + Process execution statuses. + </desc> + + <const name="Undefined" value="0"> + <desc>Process is in an undefined state.</desc> + </const> + <const name="Starting" value="10"> + <desc>Process is being started.</desc> + </const> + <const name="Started" value="100"> + <desc>Process has been started.</desc> + </const> + <const name="Paused" value="110"> + <desc>Process has been paused.</desc> + </const> + <const name="Terminating" value="480"> + <desc>Process is being terminated.</desc> + </const> + <const name="TerminatedNormally" value="500"> + <desc>Process terminated normally.</desc> + </const> + <const name="TerminatedSignal" value="510"> + <desc>Process terminated via signal.</desc> + </const> + <const name="TerminatedAbnormally" value="511"> + <desc>Process terminated abnormally.</desc> + </const> + <const name="TimedOutKilled" value="512"> + <desc>Process timed out and was killed.</desc> + </const> + <const name="TimedOutAbnormally" value="513"> + <desc>Process timed out and was not killed successfully.</desc> + </const> + <const name="Down" value="600"> + <desc>Service/OS is stopping, process was killed.</desc> + </const> + <const name="Error" value="800"> + <desc>Something went wrong.</desc> + </const> + </enum> + + <enum + name="ProcessInputStatus" + uuid="a4a0ef9c-29cc-4805-9803-c8215ae9da6c" + > + <desc> + Process input statuses. + </desc> + + <const name="Undefined" value="0"> + <desc>Undefined state.</desc> + </const> + <const name="Broken" value="1"> + <desc>Input pipe is broken.</desc> + </const> + <const name="Available" value="10"> + <desc>Input pipe became available for writing.</desc> + </const> + <const name="Written" value="50"> + <desc>Data has been successfully written.</desc> + </const> + <const name="Overflow" value="100"> + <desc>Too much input data supplied, data overflow.</desc> + </const> + </enum> + + <enum + name="PathStyle" + uuid="97303a5b-42e8-0a55-d16f-d2a92c295261" + > + <desc> + The path style of a system. + (Values matches the RTPATH_STR_F_STYLE_XXX defines in iprt/path.h!) + </desc> + <const name="DOS" value="1"> + <desc>DOS-style paths with forward and backward slashes, drive + letters and UNC. Known from DOS, OS/2 and Windows.</desc> + </const> + <const name="UNIX" value="2"> + <desc>UNIX-style paths with forward slashes only.</desc> + </const> + <const name="Unknown" value="8"> + <desc> + The path style is not known, most likely because the Guest Additions + aren't active yet. + </desc> + </const> + </enum> + + <enum + name="FileAccessMode" + uuid="231a578f-47fb-ea30-3b3e-8489558227f0" + > + <desc> + File open access mode for use with <link to="IGuestSession::fileOpen"/> + and <link to="IGuestSession::fileOpenEx"/>. + </desc> + <const name="ReadOnly" value="1"> + <desc>Open the file only with read access.</desc> + </const> + <const name="WriteOnly" value="2"> + <desc>Open the file only with write access.</desc> + </const> + <const name="ReadWrite" value="3"> + <desc>Open the file with both read and write access.</desc> + </const> + <const name="AppendOnly" value="4"> + <desc>Open the file for appending only, no read or seek access. + <note>Not yet implemented.</note> + </desc> + </const> + <const name="AppendRead" value="5"> + <desc>Open the file for appending and read. Writes always goes to the + end of the file while reads are done at the current or specified file + position. + <note>Not yet implemented.</note> + </desc> + </const> + </enum> + + <enum + name="FileOpenAction" + uuid="12bc97e2-4fc6-a8b4-4f84-0cbf4ab970d2" + > + <desc> + What action <link to="IGuestSession::fileOpen"/> and <link to="IGuestSession::fileOpenEx"/> + should take whether the file being opened exists or not. + </desc> + <const name="OpenExisting" value="1"> + <desc>Opens an existing file, fails if no file exists. (Was "oe".)</desc> + </const> + <const name="OpenOrCreate" value="2"> + <desc>Opens an existing file, creates a new one if no file exists. (Was "oc".)</desc> + </const> + <const name="CreateNew" value="3"> + <desc>Creates a new file is no file exists, fails if there is a file there already. (Was "ce".)</desc> + </const> + <const name="CreateOrReplace" value="4"> + <desc> + Creates a new file, replace any existing file. (Was "ca".) + <note> + Currently undefined whether we will inherit mode and ACLs from the + existing file or replace them. + </note> + </desc> + </const> + <const name="OpenExistingTruncated" value="5"> + <desc>Opens and truncate an existing file, fails if no file exists. (Was "ot".)</desc> + </const> + <const name="AppendOrCreate" value="99"> + <desc>Opens an existing file and places the file pointer at the end of + the file, creates the file if it does not exist. This action implies + write access. (Was "oa".) + <note> + <!-- @todo r=bird: See iprt/file.h, RTFILE_O_APPEND - not an action/disposition! + Moving the file pointer to the end, is almost fine, but implying 'write' access + isn't. That is something that is exclusively reserved for the opening mode. --> + Deprecated. Only here for historical reasons. Do not use! + </note> + </desc> + </const> + </enum> + + <enum + name="FileSharingMode" + uuid="f87dfe58-425b-c5ba-7d6d-22adeea25de1" + > + <desc> + File sharing mode for <link to="IGuestSession::fileOpenEx"/>. + </desc> + <const name="Read" value="1"> + <desc>Only share read access to the file.</desc> + </const> + <const name="Write" value="2"> + <desc>Only share write access to the file.</desc> + </const> + <const name="ReadWrite" value="3"> + <desc>Share both read and write access to the file, but deny deletion.</desc> + </const> + <const name="Delete" value="4"> + <desc>Only share delete access, denying read and write.</desc> + </const> + <const name="ReadDelete" value="5"> + <desc>Share read and delete access to the file, denying writing.</desc> + </const> + <const name="WriteDelete" value="6"> + <desc>Share write and delete access to the file, denying reading.</desc> + </const> + <const name="All" value="7"> + <desc>Share all access, i.e. read, write and delete, to the file.</desc> + </const> + </enum> + + <enum + name="FileOpenExFlag" + uuid="4671abd4-f70c-42aa-8542-6c169cb87a5c" + > + <desc> + Open flags for <link to="IGuestSession::fileOpenEx"/>. + </desc> + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + </enum> + + <enum + name="FileStatus" + uuid="8c86468b-b97b-4080-8914-e29f5b0abd2c" + > + <desc> + File statuses. + </desc> + + <const name="Undefined" value="0"> + <desc>File is in an undefined state.</desc> + </const> + <const name="Opening" value="10"> + <desc>Guest file is opening.</desc> + </const> + <const name="Open" value="100"> + <desc>Guest file has been successfully opened.</desc> + </const> + <const name="Closing" value="150"> + <desc>Guest file closing.</desc> + </const> + <const name="Closed" value="200"> + <desc>Guest file has been closed.</desc> + </const> + <const name="Down" value="600"> + <desc>Service/OS is stopping, guest file was closed.</desc> + </const> + <const name="Error" value="800"> + <desc>Something went wrong.</desc> + </const> + </enum> + + <enum + name="FsObjType" + uuid="34a0d1aa-491e-e209-e150-84964d6cee5f" + > + <desc> + File system object (file) types. + </desc> + <const name="Unknown" value="1"> + <desc>Used either if the object has type that is not in this enum, or + if the type has not yet been determined or set.</desc> + </const> + <const name="Fifo" value="2"> + <desc>FIFO or named pipe, depending on the platform/terminology.</desc> + </const> + <const name="DevChar" value="3"> + <desc>Character device.</desc> + </const> + <const name="Directory" value="4"> + <desc>Directory.</desc> + </const> + <const name="DevBlock" value="5"> + <desc>Block device.</desc> + </const> + <const name="File" value="6"> + <desc>Regular file.</desc> + </const> + <const name="Symlink" value="7"> + <desc>Symbolic link.</desc> + </const> + <const name="Socket" value="8"> + <desc>Socket.</desc> + </const> + <const name="WhiteOut" value="9"> + <desc>A white-out file. Found in union mounts where it is used for + hiding files after deletion, I think. </desc> + </const> + </enum> + + <enum + name="DnDAction" + uuid="17609e74-778e-4d0e-8827-35f5230f287b" + > + <desc> + Possible actions of a drag'n drop operation. + </desc> + + <const name="Ignore" value="0"> + <desc>Do nothing.</desc> + </const> + + <const name="Copy" value="1"> + <desc>Copy the item to the target.</desc> + </const> + + <const name="Move" value="2"> + <desc>Move the item to the target.</desc> + </const> + + <const name="Link" value="3"> + <desc>Link the item from within the target.</desc> + </const> + </enum> + + <enum + name="DirectoryOpenFlag" + uuid="5138837a-8fd2-4194-a1b0-08f7bc3949d0" + > + <desc> + Directory open flags. + </desc> + <const name="None" value="0"> + <desc>No flag set.</desc> + </const> + <const name="NoSymlinks" value="1"> + <desc>Don't allow symbolic links as part of the path.</desc> + </const> +<!-- r=bird: need a "NoFollowSymlinks" value here. IPRT probably needs that too. --> + </enum> + + <interface + name="IDnDBase" extends="$unknown" + uuid="00727A73-000A-4C4A-006D-E7D300351186" + wsmap="managed" + reservedMethods="1" reservedAttributes="2" + > + <desc>Base abstract interface for drag'n drop.</desc> + + <attribute name="formats" type="wstring" safearray="yes" readonly="yes"> + <desc>Returns all supported drag'n drop formats.</desc> + </attribute> + + <method name="isFormatSupported" > + <desc> + Checks if a specific drag'n drop MIME / Content-type format is supported. + </desc> + <param name="format" type="wstring" dir="in"> + <desc>Format to check for.</desc> + </param> + <param name="supported" type="boolean" dir="return"> + <desc>Returns @c true if the specified format is supported, @c false if not.</desc> + </param> + </method> + + <method name="addFormats" > + <desc> + Adds MIME / Content-type formats to the supported formats. + </desc> + <param name="formats" type="wstring" safearray="yes" dir="in"> + <desc>Collection of formats to add.</desc> + </param> + </method> + + <method name="removeFormats" > + <desc> + Removes MIME / Content-type formats from the supported formats. + </desc> + <param name="formats" type="wstring" safearray="yes" dir="in"> + <desc>Collection of formats to remove.</desc> + </param> + </method> + + </interface> + + <interface + name="IDnDSource" extends="IDnDBase" + uuid="d23a9ca3-42da-c94b-8aec-21968e08355d" + wsmap="managed" + reservedMethods="1" reservedAttributes="2" + > + <desc>Abstract interface for handling drag'n drop sources.</desc> + + <method name="dragIsPending"> + <desc> + Ask the source if there is any drag and drop operation pending. + If no drag and drop operation is pending currently, DnDAction_Ignore is returned. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc>The screen ID where the drag and drop event occurred.</desc> + </param> + <param name="formats" type="wstring" dir="out" safearray="yes"> + <desc>On return the supported mime types.</desc> + </param> + <param name="allowedActions" type="DnDAction" dir="out" safearray="yes"> + <desc>On return the actions which are allowed.</desc> + </param> + <param name="defaultAction" type="DnDAction" dir="return"> + <desc>On return the default action to use.</desc> + </param> + </method> + + <method name="drop"> + <desc> + Informs the source that a drop event occurred for a pending + drag and drop operation. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + </desc> + + <param name="format" type="wstring" dir="in"> + <desc>The mime type the data must be in.</desc> + </param> + <param name="action" type="DnDAction" dir="in"> + <desc>The action to use.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="receiveData"> + <desc> + Receive the data of a previously drag and drop event from the source. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + + </desc> + + <param name="data" type="octet" safearray="yes" dir="return"> + <desc>The actual data.</desc> + </param> + </method> + + </interface> + + <interface + name="IGuestDnDSource" extends="IDnDSource" + uuid="dedfb5d9-4c1b-edf7-fdf3-c1be6827dc28" + wsmap="managed" + > + <desc> + Implementation of the <link to="IDnDSource" /> object + for source drag'n drop operations on the guest. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IDnDTarget" extends="IDnDBase" + uuid="ff5befc3-4ba3-7903-2aa4-43988ba11554" + wsmap="managed" + reservedMethods="1" reservedAttributes="2" + > + <desc>Abstract interface for handling drag'n drop targets.</desc> + + <method name="enter"> + <desc> + Informs the target about a drag and drop enter event. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc>The screen ID where the drag and drop event occurred.</desc> + </param> + <param name="y" type="unsigned long" dir="in"> + <desc>Y-position of the event.</desc> + </param> + <param name="x" type="unsigned long" dir="in"> + <desc>X-position of the event.</desc> + </param> + <param name="defaultAction" type="DnDAction" dir="in"> + <desc>The default action to use.</desc> + </param> + <param name="allowedActions" type="DnDAction" dir="in" safearray="yes"> + <desc>The actions which are allowed.</desc> + </param> + <param name="formats" type="wstring" dir="in" safearray="yes"> + <desc>The supported MIME types.</desc> + </param> + <param name="resultAction" type="DnDAction" dir="return"> + <desc>The resulting action of this event.</desc> + </param> + </method> + + <method name="move"> + <desc> + Informs the target about a drag and drop move event. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc>The screen ID where the drag and drop event occurred.</desc> + </param> + <param name="x" type="unsigned long" dir="in"> + <desc>X-position of the event.</desc> + </param> + <param name="y" type="unsigned long" dir="in"> + <desc>Y-position of the event.</desc> + </param> + <param name="defaultAction" type="DnDAction" dir="in"> + <desc>The default action to use.</desc> + </param> + <param name="allowedActions" type="DnDAction" dir="in" safearray="yes"> + <desc>The actions which are allowed.</desc> + </param> + <param name="formats" type="wstring" dir="in" safearray="yes"> + <desc>The supported MIME types.</desc> + </param> + <param name="resultAction" type="DnDAction" dir="return"> + <desc>The resulting action of this event.</desc> + </param> + </method> + + <method name="leave"> + <desc> + Informs the target about a drag and drop leave event. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc>The screen ID where the drag and drop event occurred.</desc> + </param> + </method> + + <method name="drop"> + <desc> + Informs the target about a drop event. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc>The screen ID where the Drag and Drop event occurred.</desc> + </param> + <param name="x" type="unsigned long" dir="in"> + <desc>X-position of the event.</desc> + </param> + <param name="y" type="unsigned long" dir="in"> + <desc>Y-position of the event.</desc> + </param> + <param name="defaultAction" type="DnDAction" dir="in"> + <desc>The default action to use.</desc> + </param> + <param name="allowedActions" type="DnDAction" dir="in" safearray="yes"> + <desc>The actions which are allowed.</desc> + </param> + <param name="formats" type="wstring" dir="in" safearray="yes"> + <desc>The supported MIME types.</desc> + </param> + <param name="format" type="wstring" dir="out"> + <desc>The resulting format of this event.</desc> + </param> + <param name="resultAction" type="DnDAction" dir="return"> + <desc>The resulting action of this event.</desc> + </param> + </method> + + <method name="sendData"> + <desc> + Initiates sending data to the target. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc>The screen ID where the drag and drop event occurred.</desc> + </param> + <param name="format" type="wstring" dir="in"> + <desc>The MIME type the data is in.</desc> + </param> + <param name="data" type="octet" dir="in" safearray="yes"> + <desc>The actual data.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="cancel"> + <desc> + Requests cancelling the current operation. The target can veto + the request in case the operation is not cancelable at the moment. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + + </desc> + + <param name="veto" type="boolean" dir="return"> + <desc>Whether the target has vetoed cancelling the operation.</desc> + </param> + </method> + + </interface> + + <interface + name="IGuestDnDTarget" extends="IDnDTarget" + uuid="50ce4b51-0ff7-46b7-a138-3c6e5ac946b4" + wsmap="managed" + > + <desc> + Implementation of the <link to="IDnDTarget" /> object + for target drag'n drop operations on the guest. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IGuestSession" extends="$unknown" + uuid="234f0627-866d-48c2-91a5-4c9d50f04928" + wsmap="managed" + reservedMethods="8" reservedAttributes="12" + > + <desc> + A guest session represents one impersonated user account in the guest, so + every operation will use the same credentials specified when creating + the session object via <link to="IGuest::createSession"/>. + + There can be a maximum of 32 sessions at once per VM, whereas session 0 + always is reserved for the root session (the root session is part of that + limit). + + This root session is controlling all other guest sessions and also is + responsible for actions which require system level privileges. + + Each guest session keeps track of the guest directories and files that + it opened as well as guest processes it has created. To work on guest + files or directories a guest session offers methods to open or create + such objects (see <link to="IGuestSession::fileOpen"/> or + <link to="IGuestSession::directoryOpen"/> for instance). Similarly, + there a methods for creating guest processes. + + There can be up to 2048 objects (guest processes, files and directories) + a time per guest session. Exceeding the limit will result in an error (see + the corresponding functions for more). + + When done with either of these objects, including the guest session itself, + use the appropriate close() method to let the object do its cleanup work. + + Closing a session via <link to="IGuestSession::close" /> will try to close + all the mentioned objects above unless these objects are still used by + a client. + + A set of environment variables changes is associated with each session + (<link to="IGuestSession::environmentChanges"/>). These are applied to + the base environment of the impersonated guest user when creating a new + guest process. For additional flexibility the <link to="IGuestSession::processCreate"/> + and <link to="IGuestSession::processCreateEx"/> methods allows you to + specify individual environment changes for each process you create. + With newer guest addition versions, the base environment is also made + available via <link to="IGuestSession::environmentBase"/>. (One reason + for why we record changes to a base environment instead of working + directly on an environment block is that we need to be compatible + with older Guest Additions. Another reason is that this way it is always + possible to undo all the changes you've scheduled.) + </desc> + + <attribute name="user" type="wstring" readonly="yes"> + <desc>Returns the user name used by this session to impersonate + users in the guest. + </desc> + </attribute> + <attribute name="domain" type="wstring" readonly="yes"> + <desc>Returns the domain name used by this session to impersonate + users in the guest. + </desc> + </attribute> + <attribute name="name" type="wstring" readonly="yes"> + <desc>Returns the session's friendly name.</desc> + </attribute> + <attribute name="id" type="unsigned long" readonly="yes"> + <desc>Returns the internal session ID.</desc> + </attribute> + <attribute name="timeout" type="unsigned long"> + <desc> +<!-- r=bird: Using 'Returns' for writable attributes is misleading. --> + Returns the session timeout (in ms). + <result name="E_NOTIMPL"> + This attribute is not implemented yet. + </result> + </desc> + </attribute> + <attribute name="protocolVersion" type="unsigned long" readonly="yes"> + <desc>Returns the protocol version which is used by this session to + communicate with the guest.</desc> + </attribute> + <attribute name="status" type="GuestSessionStatus" readonly="yes"> + <desc>Returns the current session status.</desc> + </attribute> + <attribute name="environmentChanges" type="wstring" safearray="yes"> + <desc> + The set of scheduled environment changes to the base environment of the + session. They are in putenv format, i.e. "VAR=VALUE" for setting and + "VAR" for unsetting. One entry per variable (change). The changes are + applied when creating new guest processes. + + This is writable, so to undo all the scheduled changes, assign it an + empty array. + </desc> + </attribute> + <attribute name="environmentBase" type="wstring" safearray="yes" readonly="yes"> + <desc> + The base environment of the session. They are on the "VAR=VALUE" form, + one array entry per variable. + <!-- @todo/TODO/FIXME: This doesn't end up in the PDF. + <result name="VBOX_E_NOT_SUPPORTED">If the Guest Additions does not + support the session base environment feature. Support for this was + introduced with protocol version XXX.</result> + <result name="VBOX_E_INVALID_OBJECT_STATE">If the Guest Additions has + yet to report the session base environment.</result> --> + + Access fails with VBOX_E_NOT_SUPPORTED if the Guest Additions does not + support the session base environment feature. Support for this was + introduced with protocol version XXXX. + + Access fails with VBOX_E_INVALID_OBJECT_STATE if the Guest Additions + has yet to report the session base environment. + </desc> + </attribute> + <attribute name="processes" type="IGuestProcess" readonly="yes" safearray="yes"> + <desc> + Returns all current guest processes. + </desc> + </attribute> + <attribute name="pathStyle" type="PathStyle" readonly="yes"> + <desc> + The style of paths used by the guest. Handy for giving the right kind + of path specifications to <link to="IGuestSession::fileOpen"/> and similar methods. + </desc> + </attribute> + <attribute name="currentDirectory" type="wstring"> + <desc> + Gets or sets the current directory of the session. Guest path style. + <result name="E_NOTIMPL"> + This attribute is not implemented yet. + </result> + </desc> + </attribute> + <attribute name="userHome" type="wstring" readonly="yes"> + <desc> + Returns the user's home / profile directory. Guest path style. + </desc> + </attribute> + <attribute name="userDocuments" type="wstring" readonly="yes"> + <desc> + Returns the user's documents directory. Guest path style. + </desc> + </attribute> + <attribute name="directories" type="IGuestDirectory" readonly="yes" safearray="yes"> + <desc> + Returns all currently opened guest directories. + </desc> + </attribute> + <attribute name="files" type="IGuestFile" readonly="yes" safearray="yes"> + <desc> + Returns all currently opened guest files. + </desc> + </attribute> + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for guest session events. + </desc> + </attribute> + + <method name="close"> + <desc> + Closes this session. All opened guest directories, files and + processes which are not referenced by clients anymore will be + closed. Guest processes which fall into this category and still + are running in the guest will be terminated automatically. + </desc> + </method> + + <method name="copyFromGuest"> + <desc> + Copies directories and/or files from guest to the host. + + This function requires several parallel arrays to be supplied, one + set for each source. + </desc> + <param name="sources" type="wstring" dir="in" safearray="yes"> + <desc>Paths to directories and/or files on the guest side that should be + copied to the host. If the path ends with a path delimiter, only + the directory's content is being copied. Guest path style.</desc> + </param> + <param name="filters" type="wstring" dir="in" safearray="yes"> + <desc>Array of source filters. This uses the + DOS/NT style wildcard characters '?' and '*'.</desc> + </param> + <param name="flags" type="wstring" dir="in" safearray="yes"> + <desc>Array of comma-separated list of source flags. + + The following flags are available: + + <dl> + <dt><tt>CopyIntoExisting</tt></dt> + <dd>Allow copying into an existing destination directory.</dd> + <dt><tt>NoReplace</tt></dt> + <dd>Do not replace any existing destination files on + the destination.</dd> + <dt><tt>FollowLinks</tt></dt> + <dd>Follows (and handles) (symbolic) links.</dd> + <dt><tt>Update</tt></dt> + <dd>Only copy when the source file is newer than the destination + file or when the destination file is missing.</dd> + </dl> + </desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>Where to put the sources on the host. Host path style.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="copyToGuest"> + <desc> + Copies directories and/or files from host to the guest. + + This function requires several parallel arrays to be supplied, one + set for each source. + </desc> + <param name="sources" type="wstring" dir="in" safearray="yes"> + <desc>Paths to directories and/or files on the host side that should be + copied to the guest. If the path ends with a path delimiter, only + the directory's content is being copied. Host path style.</desc> + </param> + <param name="filters" type="wstring" dir="in" safearray="yes"> + <desc>Array of source filters. This uses the + DOS/NT style wildcard characters '?' and '*'.</desc> + </param> + <param name="flags" type="wstring" dir="in" safearray="yes"> + <desc>Array of comma-separated list of source flags. + + The following flags are available: + + <dl> + <dt><tt>CopyIntoExisting</tt></dt> + <dd>Allow copying into an existing destination directory.</dd> + <dt><tt>NoReplace</tt></dt> + <dd>Do not replace any existing destination files on + the destination.</dd> + <dt><tt>FollowLinks</tt></dt> + <dd>Follows (and handles) (symbolic) links.</dd> + <dt><tt>Update</tt></dt> + <dd>Only copy when the source file is newer than the destination + file or when the destination file is missing.</dd> + </dl> + + </desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>Where to put the sources on the guest. Guest path style.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <!-- Directory related methods. --> + + <method name="directoryCopy"> + <desc> + Recursively copies a directory from one guest location to another. + + <result name="E_NOTIMPL"> + Not yet implemented. + </result> + </desc> + <param name="source" type="wstring" dir="in"> + <desc>The path to the directory to copy (in the guest). Guest path style.</desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>The path to the target directory (in the guest). Unless the + <link to="DirectoryCopyFlag_CopyIntoExisting"/> flag is given, the + directory shall not already exist. Guest path style.</desc> + </param> + <param name="flags" type="DirectoryCopyFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="DirectoryCopyFlag"/> values.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="directoryCopyFromGuest"> + <desc> + Recursively copies a directory from the guest to the host. + </desc> + <param name="source" type="wstring" dir="in"> + <desc>Path to the directory on the guest side that should be copied to + the host. Guest path style.</desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>Where to put the directory on the host. Unless the + <link to="DirectoryCopyFlag_CopyIntoExisting"/> flag is given, the + directory shall not already exist. Host path style.</desc> + </param> + <param name="flags" type="DirectoryCopyFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="DirectoryCopyFlag"/> values.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="directoryCopyToGuest"> + <desc> + Recursively copies a directory from the host to the guest. + </desc> + <param name="source" type="wstring" dir="in"> + <desc>Path to the directory on the host side that should be copied to + the guest. Host path style.</desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>Where to put the file in the guest. Unless the + <link to="DirectoryCopyFlag_CopyIntoExisting"/> flag is given, the + directory shall not already exist. Guest style path.</desc> + </param> + <param name="flags" type="DirectoryCopyFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="DirectoryCopyFlag"/> values.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="directoryCreate"> + <desc> + Creates a directory in the guest. + + <result name="VBOX_E_IPRT_ERROR"> + Error while creating the directory. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to the directory directory to be created. Guest path style.</desc> + </param> + <param name="mode" type="unsigned long" dir="in"> + <desc> + The UNIX-style access mode mask to create the directory with. + Whether/how all three access groups and associated access rights are + realized is guest OS dependent. The API does the best it can on each + OS. + </desc> + </param> + <param name="flags" type="DirectoryCreateFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="DirectoryCreateFlag"/> flags.</desc> + </param> + </method> + + <method name="directoryCreateTemp"> + <desc> + Creates a temporary directory in the guest. + + <result name="VBOX_E_NOT_SUPPORTED"> + The operation is not possible as requested on this particular + guest type. + </result> + <result name="E_INVALIDARG"> + Invalid argument. This includes an incorrectly formatted template, + or a non-absolute path. + </result> + <result name="VBOX_E_IPRT_ERROR"> + The temporary directory could not be created. Possible reasons + include a non-existing path or an insecure path when the secure + option was requested. + </result> + </desc> + <param name="templateName" type="wstring" dir="in"> + <desc>Template for the name of the directory to create. This must + contain at least one 'X' character. The first group of consecutive + 'X' characters in the template will be replaced by a random + alphanumeric string to produce a unique name.</desc> + </param> + <param name="mode" type="unsigned long" dir="in"> + <desc> + The UNIX-style access mode mask to create the directory with. + Whether/how all three access groups and associated access rights are + realized is guest OS dependent. The API does the best it can on each + OS. + + This parameter is ignored if the @a secure parameter is set to @c true. + <note>It is strongly recommended to use 0700.</note> + </desc> + </param> + <param name="path" type="wstring" dir="in"> + <desc>The path to the directory in which the temporary directory should + be created. Guest path style.</desc> + </param> + <param name="secure" type="boolean" dir="in"> + <desc> + Whether to fail if the directory can not be securely created. + Currently this means that another unprivileged user cannot + manipulate the path specified or remove the temporary directory + after it has been created. Also causes the mode specified to be + ignored. May not be supported on all guest types. + </desc> + </param> + <param name="directory" type="wstring" dir="return"> + <desc>On success this will contain the full path to the created + directory. Guest path style.</desc> + </param> + </method> + + <method name="directoryExists"> + <desc> + Checks whether a directory exists in the guest or not. + + <result name="VBOX_E_IPRT_ERROR"> + Error while checking existence of the directory specified. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to the directory to check if exists. Guest path style.</desc> + </param> + <param name="followSymlinks" type="boolean" dir="in"> + <desc> + If @c true, symbolic links in the final component will be followed + and the existance of the symlink target made the question for this method. + If @c false, a symbolic link in the final component will make the + method return @c false (because a symlink isn't a directory). + </desc> + </param> + <param name="exists" type="boolean" dir="return"> + <desc>Returns @c true if the directory exists, @c false if not, or is not a directory.</desc> + </param> + </method> + + <method name="directoryOpen"> + <desc> + Opens a directory in the guest and creates a <link to="IGuestDirectory"/> + object that can be used for further operations. + + <note>This method follows symbolic links by default at the moment, this + may change in the future.</note> + + <note>One idiosyncrasy of the current implementation is that you will NOT + get VBOX_E_OBJECT_NOT_FOUND returned here if the directory doesn't exist. + Instead the read function will fail with VBOX_E_IPRT_ERROR. This will + be fixed soon.</note> + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Directory to open was not found. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Error while opening the directory. + </result> + <result name="VBOX_E_MAXIMUM_REACHED"> + The maximum of concurrent guest directories has been reached. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to the directory to open. Guest path style.</desc> + </param> + <param name="filter" type="wstring" dir="in"> + <desc>Optional directory listing filter to apply. This uses the DOS/NT + style wildcard characters '?' and '*'.</desc> + </param> + <param name="flags" type="DirectoryOpenFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="DirectoryOpenFlag"/> flags.</desc> + </param> + <param name="directory" type="IGuestDirectory" dir="return"> + <desc><link to="IGuestDirectory"/> object containing the opened directory.</desc> + </param> + </method> + + <method name="directoryRemove"> + <desc> + Removes a guest directory if empty. + + <note>Symbolic links in the final component will not be followed, + instead an not-a-directory error is reported.</note> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to the directory that should be removed. Guest path style.</desc> + </param> + </method> + + <method name="directoryRemoveRecursive"> + <desc> + Removes a guest directory recursively. + +<!-- Add this back when the warning can be removed: + Unless <link to="DirectoryRemoveRecFlag_ContentAndDir"/> or + <link to="DirectoryRemoveRecFlag_ContentOnly"/> is given, only the + directory structure is removed. Which means it will fail if there are + directories which are not empty in the directory tree @a path points to. +--> + + <note> WARNING!! THE FLAGS ARE NOT CURRENTLY IMPLEMENTED. THE IMPLEMENTATION + WORKS AS IF FLAGS WAS SET TO <link to="DirectoryRemoveRecFlag_ContentAndDir"/>. + </note> + + <note>If the final path component is a symbolic link, this method will + fail as it can only be applied to directories.</note> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path of the directory that is to be removed recursively. Guest + path style.</desc> + </param> + <param name="flags" type="DirectoryRemoveRecFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="DirectoryRemoveRecFlag"/> flags. + <note>WARNING! SPECIFYING <link to="DirectoryRemoveRecFlag_ContentAndDir"/> IS + MANDATORY AT THE MOMENT!!</note> + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion. This is not implemented + yet and therefore this method call will block until deletion is completed.</desc> + </param> + </method> + + <!-- Environment related methods. --> + + <method name="environmentScheduleSet"> + <desc> + Schedules setting an environment variable when creating the next guest + process. This affects the <link to="IGuestSession::environmentChanges"/> + attribute. + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the environment variable to set. This cannot be empty + nor can it contain any equal signs.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc>Value to set the session environment variable to.</desc> + </param> + </method> + + <method name="environmentScheduleUnset"> + <desc> + Schedules unsetting (removing) an environment variable when creating + the next guest process. This affects the + <link to="IGuestSession::environmentChanges"/> attribute. + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the environment variable to unset. This cannot be empty + nor can it contain any equal signs.</desc> + </param> + </method> + + <method name="environmentGetBaseVariable"> + <desc> + Gets an environment variable from the session's base environment + (<link to="IGuestSession::environmentBase"/>). + + <result name="VBOX_E_NOT_SUPPORTED">If the Guest Additions does not + support the session base environment feature. Support for this was + introduced with protocol version XXXX.</result> + <result name="VBOX_E_INVALID_OBJECT_STATE">If the Guest Additions has + yet to report the session base environment.</result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the environment variable to get.This cannot be empty + nor can it contain any equal signs.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc> + The value of the variable. Empty if not found. To deal with + variables that may have empty values, use + <link to="IGuestSession::environmentDoesBaseVariableExist"/>. + </desc> + </param> + </method> + + <method name="environmentDoesBaseVariableExist"> + <desc> + Checks if the given environment variable exists in the session's base + environment (<link to="IGuestSession::environmentBase"/>). + + <result name="VBOX_E_NOT_SUPPORTED">If the Guest Additions does not + support the session base environment feature. Support for this was + introduced with protocol version XXXX.</result> + <result name="VBOX_E_INVALID_OBJECT_STATE">If the Guest Additions has + yet to report the session base environment.</result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the environment variable to look for. This cannot be + empty nor can it contain any equal signs.</desc> + </param> + <param name="exists" type="boolean" dir="return"> + <desc>TRUE if the variable exists, FALSE if not.</desc> + </param> + </method> + + <!-- File related methods. --> + + <method name="fileCopy"> + <desc> + Copies a file from one guest location to another. + + <note>Will overwrite the destination file unless + <link to="FileCopyFlag_NoReplace"/> is specified.</note> + + <result name="E_NOTIMPL"> + Not yet implemented. + </result> + </desc> + <param name="source" type="wstring" dir="in"> + <desc>The path to the file to copy (in the guest). Guest path style.</desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>The path to the target file (in the guest). This cannot be a + directory. Guest path style.</desc> + </param> + <param name="flags" type="FileCopyFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="FileCopyFlag"/> values.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="fileCopyFromGuest"> + <desc> + Copies a file from the guest to the host. + + <note>Will overwrite the destination file unless + <link to="FileCopyFlag_NoReplace"/> is specified.</note> + + <result name="VBOX_E_IPRT_ERROR"> + Error starting the copy operation. + </result> + </desc> + <param name="source" type="wstring" dir="in"> + <desc>Path to the file on the guest side that should be copied to the + host. Guest path style.</desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>Where to put the file on the host (file, not directory). Host + path style.</desc> + </param> + <param name="flags" type="FileCopyFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="FileCopyFlag"/> values.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="fileCopyToGuest"> + <desc> + Copies a file from the host to the guest. + + <note>Will overwrite the destination file unless + <link to="FileCopyFlag_NoReplace"/> is specified.</note> + + <result name="VBOX_E_IPRT_ERROR"> + Error starting the copy operation. + </result> + </desc> + <param name="source" type="wstring" dir="in"> + <desc>Path to the file on the host side that should be copied to the + guest. Host path style.</desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>Where to put the file in the guest (file, not directory). Guest + style path.</desc> + </param> + <param name="flags" type="FileCopyFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="FileCopyFlag"/> values.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="fileCreateTemp"> + <desc> + Creates a temporary file in the guest. + + <result name="VBOX_E_NOT_SUPPORTED"> + The operation is not possible as requested on this particular + guest OS. + </result> + <result name="E_INVALIDARG"> + Invalid argument. This includes an incorrectly formatted template, + or a non-absolute path. + </result> + <result name="VBOX_E_IPRT_ERROR"> + The temporary file could not be created. Possible reasons include + a non-existing path or an insecure path when the secure + option was requested. + </result> + </desc> + <param name="templateName" type="wstring" dir="in"> + <desc>Template for the name of the file to create. This must contain + at least one 'X' character. The first group of consecutive 'X' + characters in the template will be replaced by a random + alphanumeric string to produce a unique name. + </desc> + </param> + <param name="mode" type="unsigned long" dir="in"> + <desc> + The UNIX-style access mode mask to create the file with. + Whether/how all three access groups and associated access rights are + realized is guest OS dependent. The API does the best it can on each + OS. + + This parameter is ignore if the @a secure parameter is set to @c true. + <note>It is strongly recommended to use 0600.</note> + </desc> + </param> + <param name="path" type="wstring" dir="in"> + <desc>The path to the directory in which the temporary file should be + created.</desc> + </param> + <param name="secure" type="boolean" dir="in"> + <desc>Whether to fail if the file can not be securely created. + Currently this means that another unprivileged user cannot + manipulate the path specified or remove the temporary file after + it has been created. Also causes the mode specified to be ignored. + May not be supported on all guest types.</desc> + </param> + <param name="file" type="IGuestFile" dir="return"> + <desc>On success this will contain an open file object for the new + temporary file. + </desc> + </param> + </method> + + <method name="fileExists"> + <desc> + Checks whether a regular file exists in the guest or not. + + <result name="VBOX_E_IPRT_ERROR"> + Error while checking existence of the file specified. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to the alleged regular file. Guest path style.</desc> + </param> + <param name="followSymlinks" type="boolean" dir="in"> + <desc> + If @c true, symbolic links in the final component will be followed + and the existance of the symlink target made the question for this method. + If @c false, a symbolic link in the final component will make the + method return @c false (because a symlink isn't a regular file). + </desc> + </param> + <param name="exists" type="boolean" dir="return"> + <desc>Returns @c true if the file exists, @c false if not. @c false is + also return if this @a path does not point to a file object.</desc> + </param> + </method> + + <method name="fileOpen"> + <desc> + Opens a file and creates a <link to="IGuestFile"/> object that + can be used for further operations. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + File to open was not found. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Error while opening the file. + </result> + <result name="VBOX_E_MAXIMUM_REACHED"> + The maximum of concurrent guest files has been reached. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to file to open. Guest path style.</desc> + </param> + <param name="accessMode" type="FileAccessMode" dir="in"> + <desc>The file access mode (read, write and/or append). + See <link to="FileAccessMode"/> for details.</desc> + </param> + <param name="openAction" type="FileOpenAction" dir="in"> + <desc>What action to take depending on whether the file exists or not. + See <link to="FileOpenAction"/> for details.</desc> + </param> + <param name="creationMode" type="unsigned long" dir="in"> + <desc> + The UNIX-style access mode mask to create the file with if @a openAction + requested the file to be created (otherwise ignored). Whether/how all + three access groups and associated access rights are realized is guest + OS dependent. The API does the best it can on each OS. + </desc> + </param> + <param name="file" type="IGuestFile" dir="return"> + <desc><link to="IGuestFile"/> object representing the opened file.</desc> + </param> + </method> + + <method name="fileOpenEx"> + <desc> + Opens a file and creates a <link to="IGuestFile"/> object that + can be used for further operations, extended version. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + File to open was not found. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Error while opening the file. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to file to open. Guest path style.</desc> + </param> + <param name="accessMode" type="FileAccessMode" dir="in"> + <desc>The file access mode (read, write and/or append). + See <link to="FileAccessMode"/> for details.</desc> + </param> + <param name="openAction" type="FileOpenAction" dir="in"> + <desc>What action to take depending on whether the file exists or not. + See <link to="FileOpenAction"/> for details.</desc> + </param> + <param name="sharingMode" type="FileSharingMode" dir="in"> + <desc>The file sharing mode in the guest. This parameter is currently + ignore for all guest OSes. It will in the future be implemented for + Windows, OS/2 and maybe Solaris guests only, the others will ignore it. + Use <link to="FileSharingMode_All"/>. + </desc> + </param> + <param name="creationMode" type="unsigned long" dir="in"> + <desc> + The UNIX-style access mode mask to create the file with if @a openAction + requested the file to be created (otherwise ignored). Whether/how all + three access groups and associated access rights are realized is guest + OS dependent. The API does the best it can on each OS. + </desc> + </param> + <param name="flags" type="FileOpenExFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="FileOpenExFlag"/> values. </desc> + </param> + <param name="file" type="IGuestFile" dir="return"> + <desc><link to="IGuestFile"/> object representing the opened file.</desc> + </param> + </method> + + <method name="fileQuerySize"> + <desc> + Queries the size of a regular file in the guest. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + File to was not found. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Error querying file size. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to the file which size is requested. Guest path style.</desc> + </param> + <param name="followSymlinks" type="boolean" dir="in"> + <desc> + It @c true, symbolic links in the final path component will be + followed to their target, and the size of the target is returned. + If @c false, symbolic links in the final path component will make + the method call fail (symblink is not a regular file). + </desc> + </param> + <param name="size" type="long long" dir="return"> + <desc>Queried file size.</desc> + </param> + </method> + + <!-- File System Object Level --> + + <method name="fsObjExists"> + <desc> + Checks whether a file system object (file, directory, etc) exists in + the guest or not. + + <result name="VBOX_E_IPRT_ERROR"> + Error while checking existence of the file specified. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to the file system object to check the existance of. Guest + path style.</desc> + </param> + <param name="followSymlinks" type="boolean" dir="in"> + <desc> + If @c true, symbolic links in the final component will be followed + and the method will instead check if the target exists. + If @c false, symbolic links in the final component will satisfy the + method and it will return @c true in @a exists. + </desc> + </param> + <param name="exists" type="boolean" dir="return"> + <desc>Returns @c true if the file exists, @c false if not.</desc> + </param> + </method> + + <method name="fsObjQueryInfo"> + <desc> + Queries information about a file system object (file, directory, etc) + in the guest. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + The file system object was not found. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Error while querying information. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to the file system object to gather information about. + Guest path style.</desc> + </param> + <param name="followSymlinks" type="boolean" dir="in"> + <desc> + Information about symbolic links is returned if @c false. Otherwise, + symbolic links are followed and the returned information concerns + itself with the symlink target if @c true. + </desc> + </param> + <param name="info" type="IGuestFsObjInfo" dir="return"> + <desc><link to="IGuestFsObjInfo"/> object containing the information.</desc> + </param> + </method> + + <method name="fsObjRemove"> + <desc> + Removes a file system object (file, symlink, etc) in the guest. Will + not work on directories, use <link to="IGuestSession::directoryRemove"/> + to remove directories. + + <note>This method will remove symbolic links in the final path + component, not follow them.</note> + + <result name="E_NOTIMPL"> + The method has not been implemented yet. + </result> + <result name="VBOX_E_OBJECT_NOT_FOUND"> + The file system object was not found. + </result> + <result name="VBOX_E_IPRT_ERROR"> + For most other errors. We know this is unhelpful, will fix shortly... + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Path to the file system object to remove. Guest style path.</desc> + </param> + </method> + + <method name="fsObjRemoveArray"> + <desc> + Removes multiple file system objects (files, directories, symlinks, etc) + in the guest. Use with caution. + + <note>This method is not implemented yet and will return E_NOTIMPL.</note> + + <note>This method will remove symbolic links in the final path + component, not follow them.</note> + + <result name="E_NOTIMPL"> + The method has not been implemented yet. + </result> + </desc> + <param name="path" type="wstring" dir="in" safearray="yes"> + <desc>Array of paths to the file system objects to remove. Guest style path.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="fsObjRename"> + <desc> + Renames a file system object (file, directory, symlink, etc) in the + guest. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + The file system object was not found. + </result> + <result name="VBOX_E_IPRT_ERROR"> + For most other errors. We know this is unhelpful, will fix shortly... + </result> + </desc> + <param name="oldPath" type="wstring" dir="in"> + <desc>The current path to the object. Guest path style.</desc> + </param> + <param name="newPath" type="wstring" dir="in"> + <desc>The new path to the object. Guest path style.</desc> + </param> + <param name="flags" type="FsObjRenameFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="FsObjRenameFlag"/> values.</desc> + </param> + </method> + + <method name="fsObjMove"> + <desc> + Moves a file system object (file, directory, symlink, etc) from one + guest location to another. + + This differs from <link to="IGuestSession::fsObjRename"/> in that it + can move accross file system boundraries. In that case it will + perform a copy and then delete the original. For directories, this + can take a while and is subject to races. + + <result name="E_NOTIMPL"> + Not yet implemented. + </result> + </desc> + <param name="source" type="wstring" dir="in"> + <desc>Path to the file to move. Guest path style.</desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>Where to move the file to (file, not directory). Guest path + style.</desc> + </param> + <param name="flags" type="FsObjMoveFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="FsObjMoveFlag"/> values.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="fsObjMoveArray"> + <desc> + Moves file system objects (files, directories, symlinks, etc) from one + guest location to another. + + <result name="E_NOTIMPL"> + Not yet implemented. + </result> + </desc> + <param name="source" type="wstring" dir="in" safearray="yes"> + <desc>Array of paths to the file system objects to move. Guest style path.</desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>Where to move the file system objects to (directory). Guest path + style.</desc> + </param> + <param name="flags" type="FsObjMoveFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="FsObjMoveFlag"/> values.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="fsObjCopyArray"> + <desc> + Copies file system objects (files, directories, symlinks, etc) from one + guest location to another. + + <result name="E_NOTIMPL"> + Not yet implemented. + </result> + </desc> + <param name="source" type="wstring" dir="in" safearray="yes"> + <desc>Array of paths to the file system objects to copy. Guest style path.</desc> + </param> + <param name="destination" type="wstring" dir="in"> + <desc>Where to copy the file system objects to (directory). Guest path + style.</desc> + </param> + <param name="flags" type="FileCopyFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="FileCopyFlag"/> values.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation to completion.</desc> + </param> + </method> + + <method name="fsObjSetACL"> + <desc> + Sets the access control list (ACL) of a file system object (file, + directory, etc) in the guest. + + <result name="E_NOTIMPL"> + The method is not implemented yet. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Full path of the file system object which ACL to set.</desc> + </param> + <param name="followSymlinks" type="boolean" dir="in"> + <desc> + If @c true symbolic links in the final component will be followed, + otherwise, if @c false, the method will work directly on a symbolic + link in the final component. + </desc> + </param> + <param name="acl" type="wstring" dir="in"> + <desc>The ACL specification string. To-be-defined.</desc> + </param> + <param name="mode" type="unsigned long" dir="in"> + <desc>UNIX-style mode mask to use if @a acl is empty. As mention in + <link to="IGuestSession::directoryCreate"/> this is realized on + a best effort basis and the exact behavior depends on the Guest OS. + </desc> + </param> + </method> + + <method name="fsQueryFreeSpace"> + <desc> + Returns the free space (in bytes) of a given path. + + <result name="E_NOTIMPL"> + The method is not implemented yet. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Full path to return the free space for.</desc> + </param> + <param name="freeSpace" type="long long" dir="return"> + <desc>Free space (in bytes).</desc> + </param> + </method> + + <method name="fsQueryInfo"> + <desc> + Returns file system information for a given path. + + <result name="E_NOTIMPL"> + The method is not implemented yet. + </result> + </desc> + + <param name="path" type="wstring" dir="in"> + <desc>Full path to return file system information for.</desc> + </param> + <param name="info" type="IGuestFsInfo" dir="return"> + <desc>IGuestFsInfo object containing the information.</desc> + </param> + + </method> + + <!-- Process methods --> + + <method name="processCreate"> + <desc> + Creates a new process running in the guest. The new process will be + started asynchronously, meaning on return of this function it is not + be guaranteed that the guest process is in a started state. To wait for + successful startup, use the <link to="IProcess::waitFor"/> call. + + <note> + Starting at VirtualBox 4.2 guest process execution by is default limited + to serve up to 255 guest processes at a time. If all 255 guest processes + are active and running, creating a new guest process will result in an + error. + + If ProcessCreateFlag_WaitForStdOut and/or ProcessCreateFlag_WaitForStdErr + are set, the guest process will not enter the terminated state until + all data from the specified streams have been read read. + </note> + + <result name="VBOX_E_IPRT_ERROR"> + Error creating guest process. + </result> + + <result name="VBOX_E_MAXIMUM_REACHED"> + The maximum of concurrent guest processes has been reached. + </result> + </desc> + <param name="executable" type="wstring" dir="in"> + <desc> + Full path to the file to execute in the guest. The file has to + exists in the guest VM with executable right to the session user in + order to succeed. If empty/null, the first entry in the + @a arguments array will be used instead (i.e. argv[0]). + </desc> + </param> + <param name="arguments" type="wstring" dir="in" safearray="yes"> + <desc>Array of arguments passed to the new process. + <note> + Starting with VirtualBox 5.0 this array starts with argument 0 + instead of argument 1 as in previous versions. Whether the zeroth + argument can be passed to the guest depends on the VBoxService + version running there. If you depend on this, check that the + <link to="IGuestSession::protocolVersion"/> is 3 or higher. + </note> + </desc> + </param> + <param name="environmentChanges" type="wstring" dir="in" safearray="yes"> + <desc> + Set of environment changes to complement + <link to="IGuestSession::environmentChanges"/>. Takes precedence + over the session ones. The changes are in putenv format, i.e. + "VAR=VALUE" for setting and "VAR" for unsetting. + + The changes are applied to the base environment of the impersonated + guest user (<link to="IGuestSession::environmentBase"/>) when + creating the process. (This is done on the guest side of things in + order to be compatible with older Guest Additions. That is one of + the motivations for not passing in the whole environment here.) + </desc> + </param> + <param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes"> + <desc> + Process creation flags; + see <link to="ProcessCreateFlag"/> for more information. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) for limiting the guest process' running time. + Pass 0 for an infinite timeout. On timeout the guest process will be + killed and its status will be put to an appropriate value. See + <link to="ProcessStatus"/> for more information. + </desc> + </param> + <param name="guestProcess" type="IGuestProcess" dir="return"> + <desc>Guest process object of the newly created process.</desc> + </param> + </method> + + <method name="processCreateEx"> + <desc> + Creates a new process running in the guest with the extended options + for setting the process priority and affinity. + + See <link to="IGuestSession::processCreate"/> for more information. + </desc> + <param name="executable" type="wstring" dir="in"> + <desc> + Full path to the file to execute in the guest. The file has to + exists in the guest VM with executable right to the session user in + order to succeed. If empty/null, the first entry in the + @a arguments array will be used instead (i.e. argv[0]). + </desc> + </param> + <param name="arguments" type="wstring" dir="in" safearray="yes"> + <desc>Array of arguments passed to the new process. + <note> + Starting with VirtualBox 5.0 this array starts with argument 0 + instead of argument 1 as in previous versions. Whether the zeroth + argument can be passed to the guest depends on the VBoxService + version running there. If you depend on this, check that the + <link to="IGuestSession::protocolVersion"/> is 3 or higher. + </note> + </desc> + </param> + <param name="environmentChanges" type="wstring" dir="in" safearray="yes"> + <desc> + Set of environment changes to complement + <link to="IGuestSession::environmentChanges"/>. Takes precedence + over the session ones. The changes are in putenv format, i.e. + "VAR=VALUE" for setting and "VAR" for unsetting. + + The changes are applied to the base environment of the impersonated + guest user (<link to="IGuestSession::environmentBase"/>) when + creating the process. (This is done on the guest side of things in + order to be compatible with older Guest Additions. That is one of + the motivations for not passing in the whole environment here.) + </desc> + </param> + <param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes"> + <desc> + Process creation flags, see <link to="ProcessCreateFlag"/> for + detailed description of available flags. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) for limiting the guest process' running time. + Pass 0 for an infinite timeout. On timeout the guest process will be + killed and its status will be put to an appropriate value. See + <link to="ProcessStatus"/> for more information. + </desc> + </param> + <param name="priority" type="ProcessPriority" dir="in"> + <desc> + Process priority to use for execution, see <link to="ProcessPriority"/> + for available priority levels. + <note>This is silently ignored if not supported by Guest Additions.</note> + </desc> + </param> + <param name="affinity" type="long" dir="in" safearray="yes"> + <desc> + Processor affinity to set for the new process. This is a list of + guest CPU numbers the process is allowed to run on. + <note> + This is silently ignored if the guest does not support setting the + affinity of processes, or if the Guest Additions does not implemet + this feature. + </note> + </desc> + </param> + <param name="guestProcess" type="IGuestProcess" dir="return"> + <desc>Guest process object of the newly created process.</desc> + </param> + </method> + + <method name="processGet"> + <desc> + Gets a certain guest process by its process ID (PID). + </desc> + <param name="pid" type="unsigned long" dir="in"> + <desc>Process ID (PID) to get guest process for.</desc> + </param> + <param name="guestProcess" type="IGuestProcess" dir="return"> + <desc>Guest process of specified process ID (PID).</desc> + </param> + </method> + + <!-- Symbolic link methods --> + + <method name="symlinkCreate"> + <desc> + Creates a symbolic link in the guest. + + <result name="E_NOTIMPL"> + The method is not implemented yet. + </result> + </desc> + <param name="symlink" type="wstring" dir="in"> + <desc>Path to the symbolic link that should be created. Guest path + style.</desc> + </param> + <param name="target" type="wstring" dir="in"> + <desc> + The path to the symbolic link target. If not an absolute, this will + be relative to the @a symlink location at access time. Guest path + style. + </desc> + </param> + <param name="type" type="SymlinkType" dir="in"> + <desc> + The symbolic link type (mainly for Windows). See <link to="SymlinkType"/> + for more information. + </desc> + </param> + </method> + + <method name="symlinkExists"> + <desc> + Checks whether a symbolic link exists in the guest. + + <result name="E_NOTIMPL"> + The method is not implemented yet. + </result> + </desc> + <param name="symlink" type="wstring" dir="in"> + <desc>Path to the alleged symbolic link. Guest path style.</desc> + </param> + <param name="exists" type="boolean" dir="return"> + <desc> + Returns @c true if the symbolic link exists. Returns @c false if it + does not exist, if the file system object identified by the path is + not a symbolic link, or if the object type is inaccessible to the + user, or if the @a symlink argument is empty. + </desc> + </param> + </method> + + <method name="symlinkRead"> + <desc> + Reads the target value of a symbolic link in the guest. + + <result name="E_NOTIMPL"> + The method is not implemented yet. + </result> + </desc> + <param name="symlink" type="wstring" dir="in"> + <desc>Path to the symbolic link to read.</desc> + </param> + <param name="flags" type="SymlinkReadFlag" dir="in" safearray="yes"> + <desc>Zero or more <link to="SymlinkReadFlag"/> values.</desc> + </param> + <param name="target" type="wstring" dir="return"> + <desc>Target value of the symbolic link. Guest path style.</desc> + </param> + </method> + + <!-- Session wait methods --> + + <method name="waitFor"> + <desc> + Waits for one or more events to happen. + </desc> + <param name="waitFor" type="unsigned long" dir="in"> + <desc> + Specifies what to wait for; + see <link to="GuestSessionWaitForFlag"/> for more information. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="reason" type="GuestSessionWaitResult" dir="return"> + <desc> + The overall wait result; + see <link to="GuestSessionWaitResult"/> for more information. + </desc> + </param> + </method> + + <method name="waitForArray"> + <desc> + Waits for one or more events to happen. + Scriptable version of <link to="#waitFor" />. + </desc> + <param name="waitFor" type="GuestSessionWaitForFlag" dir="in" safearray="yes"> + <desc> + Specifies what to wait for; + see <link to="GuestSessionWaitForFlag"/> for more information. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="reason" type="GuestSessionWaitResult" dir="return"> + <desc> + The overall wait result; + see <link to="GuestSessionWaitResult"/> for more information. + </desc> + </param> + </method> + + </interface> + + <interface + name="IProcess" extends="$unknown" + uuid="bc68370c-8a02-45f3-a07d-a67aa72756aa" + wsmap="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + Abstract parent interface for processes handled by VirtualBox. + </desc> + + <attribute name="arguments" type="wstring" readonly="yes" safearray="yes"> + <desc> + The arguments this process is using for execution. + </desc> + </attribute> + <attribute name="environment" type="wstring" readonly="yes" safearray="yes"> + <desc> + The initial process environment. Not yet implemented. + </desc> + </attribute> + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for process events. + </desc> + </attribute> + <attribute name="executablePath" type="wstring" readonly="yes"> + <desc>Full path of the actual executable image.</desc> + </attribute> + <attribute name="exitCode" type="long" readonly="yes"> + <desc> + The exit code. Only available when the process has been + terminated normally. + </desc> + </attribute> + <attribute name="name" type="wstring" readonly="yes"> + <desc> + The friendly name of this process. + </desc> + </attribute> + <attribute name="PID" type="unsigned long" readonly="yes"> + <desc> + The process ID (PID). + </desc> + </attribute> + <attribute name="status" type="ProcessStatus" readonly="yes"> + <desc> + The current process status; see <link to="ProcessStatus"/> + for more information. + </desc> + </attribute> + + <method name="waitFor"> + <desc> + Waits for one or more events to happen. + </desc> + <param name="waitFor" type="unsigned long" dir="in"> + <desc> + Specifies what to wait for; + see <link to="ProcessWaitForFlag"/> for more information. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="reason" type="ProcessWaitResult" dir="return"> + <desc> + The overall wait result; + see <link to="ProcessWaitResult"/> for more information. + </desc> + </param> + </method> + + <method name="waitForArray"> + <desc> + Waits for one or more events to happen. + Scriptable version of <link to="#waitFor" />. + </desc> + <param name="waitFor" type="ProcessWaitForFlag" dir="in" safearray="yes"> + <desc> + Specifies what to wait for; + see <link to="ProcessWaitForFlag"/> for more information. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="reason" type="ProcessWaitResult" dir="return"> + <desc> + The overall wait result; + see <link to="ProcessWaitResult"/> for more information. + </desc> + </param> + </method> + + <method name="read"> + <desc> + Reads data from a running process. + </desc> + <param name="handle" type="unsigned long" dir="in"> + <desc>Handle to read from. Usually 0 is stdin.</desc> + </param> + <param name="toRead" type="unsigned long" dir="in"> + <desc>Number of bytes to read.</desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="data" type="octet" dir="return" safearray="yes"> + <desc>Array of data read.</desc> + </param> + </method> + + <method name="write"> + <desc> + Writes data to a running process. + </desc> + <param name="handle" type="unsigned long" dir="in"> + <desc>Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr.</desc> + </param> + <param name="flags" type="unsigned long" dir="in"> + <desc> + A combination of <link to="ProcessInputFlag"/> flags. + </desc> + </param> + <param name="data" type="octet" dir="in" safearray="yes"> + <desc> + Array of bytes to write. The size of the array also specifies + how much to write. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="written" type="unsigned long" dir="return"> + <desc>How many bytes were written.</desc> + </param> + </method> + + <method name="writeArray"> + <desc> + Writes data to a running process. + Scriptable version of <link to="#write" />. + </desc> + <param name="handle" type="unsigned long" dir="in"> + <desc>Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr.</desc> + </param> + <param name="flags" type="ProcessInputFlag" dir="in" safearray="yes"> + <desc> + A combination of <link to="ProcessInputFlag"/> flags. + </desc> + </param> + <param name="data" type="octet" dir="in" safearray="yes"> + <desc> + Array of bytes to write. The size of the array also specifies + how much to write. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="written" type="unsigned long" dir="return"> + <desc>How may bytes were written.</desc> + </param> + </method> + + <method name="terminate"> + <desc> + Terminates (kills) a running process. + <note>It can take up to 30 seconds to get a guest process killed. In + case a guest process could not be killed an appropriate error is + returned.</note> + </desc> + </method> + </interface> + + <interface + name="IGuestProcess" extends="IProcess" + uuid="35cf4b3f-4453-4f3e-c9b8-5686939c80b6" + wsmap="managed" + > + <desc> + Implementation of the <link to="IProcess" /> object + for processes the host has started in the guest. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IDirectory" extends="$unknown" + uuid="758d7eac-e4b1-486a-8f2e-747ae346c3e9" + wsmap="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + Abstract parent interface for directories handled by VirtualBox. + </desc> + + <attribute name="directoryName" type="wstring" readonly="yes"> + <desc>The path specified when opening the directory.</desc> + </attribute> + + <attribute name="filter" type="wstring" readonly="yes"> + <desc>Directory listing filter to (specified when opening the directory).</desc> + </attribute> + + <method name="close"> + <desc> + Closes this directory. After closing operations like reading the next + directory entry will not be possible anymore. + </desc> + </method> + + <method name="read"> + <desc> + Reads the next directory entry of this directory. + <result name="VBOX_E_OBJECT_NOT_FOUND"> + No more directory entries to read. + </result> + </desc> + <param name="objInfo" type="IFsObjInfo" dir="return"> + <desc>Object information of the current directory entry read. Also see + <link to="IFsObjInfo"/>.</desc> + </param> + </method> + + <!-- Would be useful to add queryInfo() and setACL() here later, but at + present IPRT isn't doing a race free job with the former and doesn't + have the latter. So, let it be for now. --> + + </interface> + + <interface + name="IGuestDirectory" extends="IDirectory" + uuid="cc830458-4974-a19c-4dc6-cc98c2269626" + wsmap="managed" + > + <desc> + Implementation of the <link to="IDirectory" /> object + for directories in the guest. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IFile" extends="$unknown" + uuid="59a235ac-2f1a-4d6c-81fc-e3fa843f49ae" + wsmap="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + Abstract parent interface for files handled by VirtualBox. + </desc> + + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for file events. + </desc> + </attribute> + <attribute name="id" type="unsigned long" readonly="yes"> + <desc> + The ID VirtualBox internally assigned to the open file. + </desc> + </attribute> + <attribute name="initialSize" type="long long" readonly="yes"> + <desc> + The initial size in bytes when opened. + </desc> + </attribute> + <attribute name="offset" type="long long" readonly="yes"> + <desc> + The current file position. + + The file current position always applies to the <link to="IFile::read"/> + method, which updates it upon return. Same goes for the <link to="IFile::write"/> + method except when <link to="IFile::accessMode"/> is <link to="FileAccessMode_AppendOnly"/> + or <link to="FileAccessMode_AppendRead"/>, where it will always write + to the end of the file and will leave this attribute unchanged. + + The <link to="IFile::seek"/> is used to change this attribute without + transfering any file data like read and write does. + + <note> This will not always be correct with older Guest Additions + (version 5.2.30 and earlier, as well as versions 6.0.0 thru 6.0.8) + after a calling <link to="IFile::readAt"/> or <link to="IFile::writeAt"/>, + or after calling <link to="IFile::write"/> on a file in append mode. + The correct file offset can be obtained using <link to="IFile::seek"/>.</note> + + </desc> + </attribute> + <attribute name="status" type="FileStatus" readonly="yes"> + <desc> + Current file status. + </desc> + </attribute> + + <!-- The following attributes just remembers the fileOpen parameters for you. + Nice for introspection and probably doesn't cost us much. --> + <attribute name="filename" type="wstring" readonly="yes"> + <desc>Full path of the actual file name of this file. + <!-- r=bird: The 'actual' file name is too tough, we cannot guarentee + that on unix guests. Seeing how IGuestDirectory did things, + I'm questioning the 'Full path' part too. Not urgent to check. --> + </desc> + </attribute> + <attribute name="creationMode" type="unsigned long" readonly="yes"> + <desc>The UNIX-style creation mode specified when opening the file.</desc> + </attribute> + <attribute name="openAction" type="FileOpenAction" readonly="yes"> + <desc>The opening action specified when opening the file.</desc> + </attribute> + <attribute name="accessMode" type="FileAccessMode" readonly="yes"> + <desc>The file access mode.</desc> + </attribute> + + <method name="close"> + <desc> + Closes this file. After closing operations like reading data, + writing data or querying information will not be possible anymore. + </desc> + </method> + + <method name="queryInfo"> + <desc> + Queries information about this file. + </desc> + <param name="objInfo" type="IFsObjInfo" dir="return"> + <desc>Object information of this file. Also see + <link to="IFsObjInfo"/>.</desc> + </param> + </method> + + <method name="querySize"> + <!-- Can also be gotten via seek(Current, 0), but this is easier to us. + This is a query method both to match IGuestSession::fileQuerySize to + highlight that it is a value that is not cacheable as others may be + changing the file concurrently (imagine reading /var/log/messages). --> + <desc> + Queries the current file size. + </desc> + <param name="size" type="long long" dir="return"> + <desc>Queried file size.</desc> + </param> + </method> + + <method name="read"> + <desc> + Reads data from this file. + + The file current position (<link to="IFile::offset"/>) is updated on success. + </desc> + <param name="toRead" type="unsigned long" dir="in"> + <desc>Number of bytes to read.</desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="data" type="octet" dir="return" safearray="yes"> + <desc>Array of data read.</desc> + </param> + </method> + + <method name="readAt"> + <desc> + Reads data from an offset of this file. + + The file current position (<link to="IFile::offset"/>) is updated on success. + </desc> + <param name="offset" type="long long" dir="in"> + <desc>Offset in bytes to start reading.</desc> + </param> + <param name="toRead" type="unsigned long" dir="in"> + <desc>Number of bytes to read.</desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="data" type="octet" dir="return" safearray="yes"> + <desc>Array of data read.</desc> + </param> + </method> + + <method name="seek"> + <desc> + Changes the current file position of this file. + + The file current position always applies to the <link to="IFile::read"/> + method. Same for the <link to="IFile::write"/> method it except when + the <link to="IFile::accessMode"/> is <link to="FileAccessMode_AppendOnly"/> + or <link to="FileAccessMode_AppendRead"/>. + </desc> + <param name="offset" type="long long" dir="in"> + <desc>Offset to seek relative to the position specified by @a whence.</desc> + </param> + <param name="whence" type="FileSeekOrigin" dir="in"> + <desc> + One of the <link to="FileSeekOrigin"/> seek starting points. + </desc> + </param> + <param name="newOffset" type="long long" dir="return"> + <desc>The new file offset after the seek operation.</desc> + </param> + </method> + + <method name="setACL"> + <desc> + Sets the ACL of this file. + + <result name="E_NOTIMPL"> + The method is not implemented yet. + </result> + </desc> + <param name="acl" type="wstring" dir="in"> + <desc>The ACL specification string. To-be-defined.</desc> + </param> + <param name="mode" type="unsigned long" dir="in"> + <desc>UNIX-style mode mask to use if @a acl is empty. As mention in + <link to="IGuestSession::directoryCreate"/> this is realized on + a best effort basis and the exact behavior depends on the Guest OS. + </desc> + </param> + </method> + + <method name="setSize"> + <desc> + Changes the file size. + </desc> + <param name="size" type="long long" dir="in"> + <desc>The new file size.</desc> + </param> + </method> + + <method name="write"> + <desc> + Writes bytes to this file. + + The file current position (<link to="IFile::offset"/>) is updated on success. + </desc> + <param name="data" type="octet" dir="in" safearray="yes"> + <desc> + Array of bytes to write. The size of the array also specifies + how much to write. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="written" type="unsigned long" dir="return"> + <desc>How many bytes were written.</desc> + </param> + </method> + + <method name="writeAt"> + <desc> + Writes bytes at a certain offset to this file. + + The file current position (<link to="IFile::offset"/>) is updated on success. + </desc> + <param name="offset" type="long long" dir="in"> + <desc>Offset in bytes to start writing. If the file was opened with the + <link to="IFile::accessMode"/> set to <link to="FileAccessMode_AppendOnly"/> + or <link to="FileAccessMode_AppendRead"/>, the offset is ignored and the + write always goes to the end of the file.</desc> + </param> + <param name="data" type="octet" dir="in" safearray="yes"> + <desc> + Array of bytes to write. The size of the array also specifies + how much to write. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="written" type="unsigned long" dir="return"> + <desc>How many bytes were written.</desc> + </param> + </method> + + </interface> + + <interface + name="IGuestFile" extends="IFile" + uuid="92f21dc0-44de-1653-b717-2ebf0ca9b664" + wsmap="managed" + > + <desc> + Implementation of the <link to="IFile" /> object + for files in the guest. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IFsInfo" extends="$unknown" + uuid="3db2ab1a-6cf7-42f1-8bf5-e1c0553e0b30" + wsmap="managed" + reservedAttributes="8" + > + <desc> + Abstract parent interface for VirtualBox file system information. + This can be information about a host or guest file system, for example. + </desc> + + <attribute name="freeSize" type="long long" readonly="yes"> + <desc> + Remaining free space (in bytes) of the filesystem. + </desc> + </attribute> + <attribute name="totalSize" type="long long" readonly="yes"> + <desc> + Total space (in bytes) of the filesystem. + </desc> + </attribute> + <attribute name="blockSize" type="unsigned long" readonly="yes"> + <desc> + Block size (in bytes) of the filesystem. + </desc> + </attribute> + <attribute name="sectorSize" type="unsigned long" readonly="yes"> + <desc> + Sector size (in bytes) of the filesystem. + </desc> + </attribute> + <attribute name="serialNumber" type="unsigned long" readonly="yes"> + <desc> + Serial number of the filesystem. + </desc> + </attribute> + <attribute name="isRemote" type="boolean" readonly="yes"> + <desc> + @c TRUE if the filesystem is remote, @c FALSE if the filesystem is local. + </desc> + </attribute> + <attribute name="isCaseSensitive" type="boolean" readonly="yes"> + <desc> + @c TRUE if the filesystem is case sensitive, @c FALSE if the filesystem is case insensitive. + </desc> + </attribute> + <attribute name="isReadOnly" type="boolean" readonly="yes"> + <desc> + @c TRUE if the filesystem is mounted read only, @c FALSE if the filesystem is mounted read write. + </desc> + </attribute> + <attribute name="isCompressed" type="boolean" readonly="yes"> + <desc> + @c TRUE if the filesystem is compressed, @c FALSE if it isn't or we don't know. + </desc> + </attribute> + <attribute name="supportsFileCompression" type="boolean" readonly="yes"> + <desc> + @c TRUE if the filesystem compresses of individual files, @c FALSE if it doesn't or we don't know. + </desc> + </attribute> + <attribute name="maxComponent" type="unsigned long" readonly="yes"> + <desc> + The maximum size of a filesystem object name. + </desc> + </attribute> + <attribute name="type" type="wstring" readonly="yes"> + <desc> + Name of the filesystem. + </desc> + </attribute> + <attribute name="label" type="wstring" readonly="yes"> + <desc> + Label of the filesystem. + </desc> + </attribute> + <attribute name="mountPoint" type="wstring" readonly="yes"> + <desc> + Mount point of the filesystem. + </desc> + </attribute> + </interface> + + <interface + name="IFsObjInfo" extends="$unknown" + uuid="081fc833-c6fa-430e-6020-6a505d086387" + wsmap="managed" + reservedAttributes="8" + > + <desc> + Abstract parent interface for VirtualBox file system object information. + This can be information about a file or a directory, for example. + </desc> + <attribute name="name" type="wstring" readonly="yes"> + <desc> + The object's name. + </desc> + </attribute> + <attribute name="type" type="FsObjType" readonly="yes"> + <desc> + The object type. See <link to="FsObjType" /> for more. + </desc> + </attribute> + <attribute name="fileAttributes" type="wstring" readonly="yes"> + <desc> + File attributes. Not implemented yet. + </desc> + </attribute> + <attribute name="objectSize" type="long long" readonly="yes"> + <desc> + The logical size (st_size). For normal files this is the size of the file. + For symbolic links, this is the length of the path name contained in the + symbolic link. For other objects this fields needs to be specified. + </desc> + </attribute> + <attribute name="allocatedSize" type="long long" readonly="yes"> + <desc> + Disk allocation size (st_blocks * DEV_BSIZE). + </desc> + </attribute> + <!-- Time attributes: --> + <attribute name="accessTime" type="long long" readonly="yes"> + <desc> + Time of last access (st_atime). + </desc> + </attribute> + <attribute name="birthTime" type="long long" readonly="yes"> + <desc> + Time of file birth (st_birthtime). + </desc> + </attribute> + <attribute name="changeTime" type="long long" readonly="yes"> + <desc> + Time of last status change (st_ctime). + </desc> + </attribute> + <attribute name="modificationTime" type="long long" readonly="yes"> + <desc> + Time of last data modification (st_mtime). + </desc> + </attribute> + <!-- Ownership attributes: --> + <attribute name="UID" type="long" readonly="yes"> + <desc> + The user owning the filesystem object (st_uid). This is -1 if not available. + </desc> + </attribute> + <attribute name="userName" type="wstring" readonly="yes"> + <desc> + The user name. + </desc> + </attribute> + <attribute name="GID" type="long" readonly="yes"> + <desc> + The group the filesystem object is assigned (st_gid). This is -1 if not available. + </desc> + </attribute> + <attribute name="groupName" type="wstring" readonly="yes"> + <desc> + The group name. + </desc> + </attribute> + <!-- More esoteric attributes: --> + <attribute name="nodeId" type="long long" readonly="yes"> + <desc> + The unique identifier (within the filesystem) of this filesystem object (st_ino). + This is zero if not availalbe. + </desc> + </attribute> + <attribute name="nodeIdDevice" type="unsigned long" readonly="yes"> + <desc> + The device number of the device which this filesystem object resides on (st_dev). + </desc> + </attribute> + <attribute name="hardLinks" type="unsigned long" readonly="yes"> + <desc> + Number of hard links to this filesystem object (st_nlink). + </desc> + </attribute> + <attribute name="deviceNumber" type="unsigned long" readonly="yes"> + <desc> + The device number of a character or block device type object (st_rdev). + </desc> + </attribute> + <attribute name="generationId" type="unsigned long" readonly="yes"> + <desc> + The current generation number (st_gen). + </desc> + </attribute> + <attribute name="userFlags" type="unsigned long" readonly="yes"> + <desc> + User flags (st_flags). + </desc> + </attribute> + </interface> + + <interface + name="IGuestFsInfo" extends="IFsInfo" + uuid="726eaca9-091e-41b4-bca6-355efe864107" + wsmap="managed" + > + <desc> + Represents the guest implementation of the + <link to="IFsInfo" /> object. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IGuestFsObjInfo" extends="IFsObjInfo" + uuid="6620db85-44e0-ca69-e9e0-d4907ceccbe5" + wsmap="managed" + > + <desc> + Represents the guest implementation of the + <link to="IFsObjInfo" /> object. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IGuest" extends="$unknown" + uuid="00892186-A4AF-4627-B21F-FC561CE4473C" + wsmap="managed" + reservedMethods="8" reservedAttributes="16" + > + <desc> + The IGuest interface represents information about the operating system + running inside the virtual machine. Used in + <link to="IConsole::guest"/>. + + IGuest provides information about the guest operating system, whether + Guest Additions are installed and other OS-specific virtual machine + properties. + </desc> + + <attribute name="OSTypeId" type="wstring" readonly="yes"> + <desc> + Identifier of the Guest OS type as reported by the Guest + Additions. + You may use <link to="IVirtualBox::getGuestOSType"/> to obtain + an IGuestOSType object representing details about the given + Guest OS type. + <note> + If Guest Additions are not installed, this value will be + the same as <link to="IMachine::OSTypeId"/>. + </note> + </desc> + </attribute> + + <attribute name="additionsRunLevel" type="AdditionsRunLevelType" readonly="yes"> + <desc> + Current run level of the installed Guest Additions. + </desc> + </attribute> + + <attribute name="additionsVersion" type="wstring" readonly="yes"> + <desc> + Version of the installed Guest Additions in the same format as + <link to="IVirtualBox::version"/>. + </desc> + </attribute> + + <attribute name="additionsRevision" type="unsigned long" readonly="yes"> + <desc> + The internal build revision number of the installed Guest Additions. + + See also <link to="IVirtualBox::revision"/>. + </desc> + </attribute> + + <attribute name="dnDSource" type="IGuestDnDSource" readonly="yes"> + <desc> + Retrieves the drag'n drop source implementation for the guest side, that + is, handling and retrieving drag'n drop data from the guest. + </desc> + </attribute> + + <attribute name="dnDTarget" type="IGuestDnDTarget" readonly="yes"> + <desc> + Retrieves the drag'n drop source implementation for the host side. This + will allow the host to handle and initiate a drag'n drop operation to copy + data from the host to the guest. + </desc> + </attribute> + + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for guest events. + </desc> + </attribute> + + <attribute name="facilities" type="IAdditionsFacility" readonly="yes" safearray="yes"> + <desc> + Returns a collection of current known facilities. Only returns facilities where + a status is known, e.g. facilities with an unknown status will not be returned. + </desc> + </attribute> + + <attribute name="sessions" type="IGuestSession" readonly="yes" safearray="yes"> + <desc>Returns a collection of all opened guest sessions.</desc> + </attribute> + + <attribute name="memoryBalloonSize" type="unsigned long"> + <desc>Guest system memory balloon size in megabytes (transient property).</desc> + </attribute> + + <attribute name="statisticsUpdateInterval" type="unsigned long"> + <desc>Interval to update guest statistics in seconds.</desc> + </attribute> + + <method name="internalGetStatistics"> + <desc> + Internal method; do not use as it might change at any time. + </desc> + <param name="cpuUser" type="unsigned long" dir="out"> + <desc>Percentage of processor time spent in user mode as seen by the guest.</desc> + </param> + <param name="cpuKernel" type="unsigned long" dir="out"> + <desc>Percentage of processor time spent in kernel mode as seen by the guest.</desc> + </param> + <param name="cpuIdle" type="unsigned long" dir="out"> + <desc>Percentage of processor time spent idling as seen by the guest.</desc> + </param> + <param name="memTotal" type="unsigned long" dir="out"> + <desc>Total amount of physical guest RAM.</desc> + </param> + <param name="memFree" type="unsigned long" dir="out"> + <desc>Free amount of physical guest RAM.</desc> + </param> + <param name="memBalloon" type="unsigned long" dir="out"> + <desc>Amount of ballooned physical guest RAM.</desc> + </param> + <param name="memShared" type="unsigned long" dir="out"> + <desc>Amount of shared physical guest RAM.</desc> + </param> + <param name="memCache" type="unsigned long" dir="out"> + <desc>Total amount of guest (disk) cache memory.</desc> + </param> + <param name="pagedTotal" type="unsigned long" dir="out"> + <desc>Total amount of space in the page file.</desc> + </param> + <param name="memAllocTotal" type="unsigned long" dir="out"> + <desc>Total amount of memory allocated by the hypervisor.</desc> + </param> + <param name="memFreeTotal" type="unsigned long" dir="out"> + <desc>Total amount of free memory available in the hypervisor.</desc> + </param> + <param name="memBalloonTotal" type="unsigned long" dir="out"> + <desc>Total amount of memory ballooned by the hypervisor.</desc> + </param> + <param name="memSharedTotal" type="unsigned long" dir="out"> + <desc>Total amount of shared memory in the hypervisor.</desc> + </param> + </method> + + <method name="getFacilityStatus"> + <desc> + Get the current status of a Guest Additions facility. + </desc> + <param name="facility" type="AdditionsFacilityType" dir="in"> + <desc>Facility to check status for.</desc> + </param> + <param name="timestamp" type="long long" dir="out"> + <desc>Timestamp (in ms) of last status update seen by the host.</desc> + </param> + <param name="status" type="AdditionsFacilityStatus" dir="return"> + <desc>The current (latest) facility status.</desc> + </param> + </method> + + <method name="getAdditionsStatus"> + <desc> + Retrieve the current status of a certain Guest Additions run level. + + <result name="VBOX_E_NOT_SUPPORTED"> + Wrong status level specified. + </result> + + </desc> + <param name="level" type="AdditionsRunLevelType" dir="in"> + <desc>Status level to check</desc> + </param> + <param name="active" type="boolean" dir="return"> + <desc>Flag whether the status level has been reached or not</desc> + </param> + </method> + + <method name="setCredentials"> + <desc> + Store login credentials that can be queried by guest operating + systems with Additions installed. The credentials are transient + to the session and the guest may also choose to erase them. Note + that the caller cannot determine whether the guest operating system + has queried or made use of the credentials. + + <result name="VBOX_E_VM_ERROR"> + VMM device is not available. + </result> + + </desc> + <param name="userName" type="wstring" dir="in"> + <desc>User name string, can be empty</desc> + </param> + <param name="password" type="wstring" dir="in"> + <desc>Password string, can be empty</desc> + </param> + <param name="domain" type="wstring" dir="in"> + <desc>Domain name (guest logon scheme specific), can be empty</desc> + </param> + <param name="allowInteractiveLogon" type="boolean" dir="in"> + <desc> + Flag whether the guest should alternatively allow the user to + interactively specify different credentials. This flag might + not be supported by all versions of the Additions. + </desc> + </param> + </method> + + <method name="createSession"> + <desc> + Creates a new guest session for controlling the guest. The new session + will be started asynchronously, meaning on return of this function it is + not guaranteed that the guest session is in a started and/or usable state. + To wait for successful startup, use the <link to="IGuestSession::waitFor"/> + call. + + A guest session represents one impersonated user account in the guest, so + every operation will use the same credentials specified when creating + the session object via <link to="IGuest::createSession"/>. Anonymous + sessions, that is, sessions without specifying a valid + user account in the guest are not allowed reasons of security. + + There can be a maximum of 32 sessions at once per VM. An error will + be returned if this has been reached. + + For more information please consult <link to="IGuestSession"/> + + <result name="VBOX_E_IPRT_ERROR"> + Error creating guest session. + </result> + + <result name="VBOX_E_MAXIMUM_REACHED"> + The maximum of concurrent guest sessions has been reached. + </result> + </desc> + <param name="user" type="wstring" dir="in"> + <desc> + User name this session will be using to control the guest; has to exist + and have the appropriate rights to execute programs in the VM. Must not + be empty. + </desc> + </param> + <param name="password" type="wstring" dir="in"> + <desc> + Password of the user account to be used. Empty passwords are allowed. + </desc> + </param> + <param name="domain" type="wstring" dir="in"> + <desc> + Domain name of the user account to be used if the guest is part of + a domain. Optional. This feature is not implemented yet. + </desc> + </param> + <param name="sessionName" type="wstring" dir="in"> + <desc> + The session's friendly name. Optional, can be empty. + </desc> + </param> + <param name="guestSession" type="IGuestSession" dir="return"> + <desc> + The newly created session object. + </desc> + </param> + </method> + + <method name="findSession"> + <desc> + Finds guest sessions by their friendly name and returns an interface + array with all found guest sessions. + </desc> + <param name="sessionName" type="wstring" dir="in"> + <desc> + The session's friendly name to find. Wildcards like ? and * are allowed. + </desc> + </param> + <param name="sessions" type="IGuestSession" safearray="yes" dir="return"> + <desc> + Array with all guest sessions found matching the name specified. + </desc> + </param> + </method> + + <method name="shutdown"> + <desc> + Shuts down (and optionally halts and/or reboots) the guest. + Needs supported Guest Additions installed. + + <result name="VBOX_E_NOT_SUPPORTED"> + Guest OS is not supported for shutting down, or the + already installed Guest Additions are not supported. + </result> + + <result name="VBOX_E_IPRT_ERROR"> + Error while shutting down. + </result> + + </desc> + <param name="flags" type="GuestShutdownFlag" dir="in" safearray="yes"> + <desc> + <link to="GuestShutdownFlag"/> flags. + </desc> + </param> + </method> + + <method name="updateGuestAdditions"> + <desc> + Automatically updates already installed Guest Additions in a VM. + + At the moment only Windows and Linux guests are supported. + + Because the VirtualBox Guest Additions drivers are not WHQL-certified + yet there might be warning dialogs during the actual Guest Additions + update. These need to be confirmed manually in order to continue the + installation process. This applies to Windows 2000 and Windows XP guests + and therefore these guests can't be updated in a fully automated fashion + without user interaction. However, to start a Guest Additions update for + the mentioned Windows versions anyway, the flag + AdditionsUpdateFlag_WaitForUpdateStartOnly can be specified. See + <link to="AdditionsUpdateFlag"/> for more information. + + The guest needs to be restarted in order to make use of the updated + Guest Additions. + + <result name="VBOX_E_NOT_SUPPORTED"> + Guest OS is not supported for automated Guest Additions updates or the + already installed Guest Additions are not ready yet. + </result> + + <result name="VBOX_E_IPRT_ERROR"> + Error while updating. + </result> + + </desc> + <param name="source" type="wstring" dir="in"> + <desc> + Path to the Guest Additions .ISO file to use for the update. + </desc> + </param> + <param name="arguments" type="wstring" dir="in" safearray="yes"> + <desc> + Optional command line arguments to use for the Guest Additions + installer. Useful for retrofitting features which weren't installed + before in the guest. + </desc> + </param> + <param name="flags" type="AdditionsUpdateFlag" dir="in" safearray="yes"> + <desc> + <link to="AdditionsUpdateFlag"/> flags. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + </interface> + + + <!-- + // IProgress + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IProgress" extends="$unknown" + uuid="d7b98d2b-30e8-447e-99cb-e31becae6ae4" + wsmap="managed" + rest="managed" + wrap-hint-server-addinterfaces="IInternalProgressControl" + reservedMethods="8" reservedAttributes="12" + > + <desc> + The IProgress interface is used to track and control + asynchronous tasks within VirtualBox. + + An instance of this is returned every time VirtualBox starts + an asynchronous task (in other words, a separate thread) which + continues to run after a method call returns. For example, + <link to="IMachine::saveState" />, which saves the state of + a running virtual machine, can take a long time to complete. + To be able to display a progress bar, a user interface such as + the VirtualBox graphical user interface can use the IProgress + object returned by that method. + + Note that IProgress is a "read-only" interface in the sense + that only the VirtualBox internals behind the Main API can + create and manipulate progress objects, whereas client code + can only use the IProgress object to monitor a task's + progress and, if <link to="#cancelable" /> is @c true, + cancel the task by calling <link to="#cancel" />. + + A task represented by IProgress consists of either one or + several sub-operations that run sequentially, one by one (see + <link to="#operation" /> and <link to="#operationCount" />). + Every operation is identified by a number (starting from 0) + and has a separate description. + + You can find the individual percentage of completion of the current + operation in <link to="#operationPercent" /> and the + percentage of completion of the task as a whole + in <link to="#percent" />. + + Similarly, you can wait for the completion of a particular + operation via <link to="#waitForOperationCompletion" /> or + for the completion of the whole task via + <link to="#waitForCompletion" />. + </desc> + + <attribute name="id" type="uuid" mod="string" readonly="yes"> + <desc>ID of the task.</desc> + </attribute> + + <attribute name="description" type="wstring" readonly="yes"> + <desc>Description of the task.</desc> + </attribute> + + <attribute name="initiator" type="$unknown" readonly="yes"> + <desc>Initiator of the task.</desc> + </attribute> + + <attribute name="cancelable" type="boolean" readonly="yes"> + <desc>Whether the task can be interrupted.</desc> + </attribute> + + <attribute name="percent" type="unsigned long" readonly="yes"> + <desc> + Current progress value of the task as a whole, in percent. + This value depends on how many operations are already complete. + Returns 100 if <link to="#completed" /> is @c true. + </desc> + </attribute> + + <attribute name="timeRemaining" type="long" readonly="yes"> + <desc> + Estimated remaining time until the task completes, in + seconds. Returns 0 once the task has completed; returns -1 + if the remaining time cannot be computed, in particular if + the current progress is 0. + + Even if a value is returned, the estimate will be unreliable + for low progress values. It will become more reliable as the + task progresses; it is not recommended to display an ETA + before at least 20% of a task have completed. + </desc> + </attribute> + + <attribute name="completed" type="boolean" readonly="yes"> + <desc>Whether the task has been completed.</desc> + </attribute> + + <attribute name="canceled" type="boolean" readonly="yes"> + <desc>Whether the task has been canceled.</desc> + </attribute> + + <attribute name="resultCode" type="long" readonly="yes"> + <desc> + Result code of the progress task. + Valid only if <link to="#completed"/> is @c true. + </desc> + </attribute> + + <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + Extended information about the unsuccessful result of the + progress operation. May be @c null if no extended information + is available. + Valid only if <link to="#completed"/> is @c true and + <link to="#resultCode"/> indicates a failure. + </desc> + </attribute> + + <attribute name="operationCount" type="unsigned long" readonly="yes"> + <desc> + Number of sub-operations this task is divided into. + Every task consists of at least one suboperation. + </desc> + </attribute> + + <attribute name="operation" type="unsigned long" readonly="yes"> + <desc>Number of the sub-operation being currently executed.</desc> + </attribute> + + <attribute name="operationDescription" type="wstring" readonly="yes"> + <desc> + Description of the sub-operation being currently executed. + </desc> + </attribute> + + <attribute name="operationPercent" type="unsigned long" readonly="yes"> + <desc>Progress value of the current sub-operation only, in percent.</desc> + </attribute> + + <attribute name="operationWeight" type="unsigned long" readonly="yes"> + <desc>Weight value of the current sub-operation only.</desc> + </attribute> + + <attribute name="timeout" type="unsigned long"> + <desc> + When non-zero, this specifies the number of milliseconds after which + the operation will automatically be canceled. This can only be set on + cancelable objects. + </desc> + </attribute> + + <attribute name="eventSource" type="IEventSource" readonly="yes" rest="suppress"/> + + <method name="waitForCompletion"> + <rest request="post" path="/progresses/{progressid}/actions/"/> + <desc> + Waits until the task is done (including all sub-operations) + with a given timeout in milliseconds; specify -1 for an indefinite wait. + + Note that the VirtualBox/XPCOM/COM/native event queues of the calling + thread are not processed while waiting. Neglecting event queues may + have dire consequences (degrade performance, resource hogs, + deadlocks, etc.), this is specially so for the main thread on + platforms using XPCOM. Callers are advised wait for short periods + and service their event queues between calls, or to create a worker + thread to do the waiting. + + <result name="VBOX_E_IPRT_ERROR"> + Failed to wait for task completion. + </result> + </desc> + + <param name="timeout" type="long" dir="in"> + <desc> + Maximum time in milliseconds to wait or -1 to wait indefinitely. + </desc> + </param> + </method> + + <method name="waitForOperationCompletion"> + <rest request="post" path="/progresses/{progressid}/actions/"/> + <desc> + Waits until the given operation is done with a given timeout in + milliseconds; specify -1 for an indefinite wait. + + See <link to="#waitForCompletion"> for event queue considerations.</link> + + <result name="VBOX_E_IPRT_ERROR"> + Failed to wait for operation completion. + </result> + + </desc> + <param name="operation" type="unsigned long" dir="in"> + <desc> + Number of the operation to wait for. + Must be less than <link to="#operationCount"/>. + </desc> + </param> + <param name="timeout" type="long" dir="in"> + <desc> + Maximum time in milliseconds to wait or -1 to wait indefinitely. + </desc> + </param> + </method> + + <method name="cancel"> + <rest request="post" path="/progresses/{progressid}/actions/"/> + <desc> + Cancels the task. + <note> + If <link to="#cancelable"/> is @c false, then this method will fail. + </note> + + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Operation cannot be canceled. + </result> + + </desc> + </method> + + </interface> + + <interface + name="IInternalProgressControl" extends="$unknown" + uuid="41a033b8-cc87-4f6e-a0e9-47bb7f2d4be5" + internal="yes" + wsmap="suppress" + reservedMethods="8" reservedAttributes="8" + > + + <method name="setCurrentOperationProgress"> + <desc>Internal method, not to be called externally.</desc> + <param name="percent" type="unsigned long" dir="in" /> + </method> + + <method name="waitForOtherProgressCompletion"> + <desc> + Internal method, not to be called externally. + + Waits until the other task is completed (including all sub-operations) + and forward all changes from the other progress to this progress. This + means sub-operation number, description, percent and so on. + + The caller is responsible for having at least the same count of + sub-operations in this progress object as there are in the other + progress object. + + If the other progress object supports cancel and this object gets any + cancel request (when here enabled as well), it will be forwarded to + the other progress object. + + Error information is automatically preserved (by transferring it to + the current thread's error information). If the caller wants to set it + as the completion state of this progress it needs to be done separately. + + <result name="VBOX_E_TIMEOUT"> + Waiting time has expired. + </result> + </desc> + <param name="progressOther" type="IProgress" dir="in"> + <desc>Other progress object to be "cloned".</desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc>Timeout (in ms). Pass 0 for an infinite timeout.</desc> + </param> + </method> + + <method name="setNextOperation"> + <desc>Internal method, not to be called externally.</desc> + <param name="nextOperationDescription" type="wstring" dir="in" /> + <param name="nextOperationsWeight" type="unsigned long" dir="in" /> + </method> + + <method name="notifyPointOfNoReturn"> + <desc>Internal method, not to be called externally.</desc> + </method> + + <method name="notifyComplete"> + <desc>Internal method, not to be called externally.</desc> + <param name="resultCode" type="long" dir="in" /> + <param name="errorInfo" type="IVirtualBoxErrorInfo" dir="in" /> + </method> + + </interface> + + <!-- + // ISnapshot + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="ISnapshot" extends="$unknown" + uuid="6cc49055-dad4-4496-85cf-3f76bcb3b5fa" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + The ISnapshot interface represents a snapshot of the virtual + machine. + + Together with the differencing media that are created + when a snapshot is taken, a machine can be brought back to + the exact state it was in when the snapshot was taken. + + The ISnapshot interface has no methods, only attributes; snapshots + are controlled through methods of the <link to="IMachine" /> interface + which also manage the media associated with the snapshot. + The following operations exist: + + <ul> + <li><link to="IMachine::takeSnapshot"/> creates a new snapshot + by creating new, empty differencing images for the machine's + media and saving the VM settings and (if the VM is running) + the current VM state in the snapshot. + + The differencing images will then receive all data written to + the machine's media, while their parent (base) images + remain unmodified after the snapshot has been taken (see + <link to="IMedium" /> for details about differencing images). + This simplifies restoring a machine to the state of a snapshot: + only the differencing images need to be deleted. + + The current machine state is not changed by taking a snapshot + except that <link to="IMachine::currentSnapshot" /> is set to + the newly created snapshot, which is also added to the machine's + snapshots tree. + </li> + + <li><link to="IMachine::restoreSnapshot"/> resets a machine to + the state of a previous snapshot by deleting the differencing + image of each of the machine's media and setting the machine's + settings and state to the state that was saved in the snapshot (if any). + + This destroys the machine's current state. After calling this, + <link to="IMachine::currentSnapshot" /> points to the snapshot + that was restored. + </li> + + <li><link to="IMachine::deleteSnapshot"/> deletes a snapshot + without affecting the current machine state. + + This does not change the current machine state, but instead frees the + resources allocated when the snapshot was taken: the settings and machine + state file are deleted (if any), and the snapshot's differencing image for + each of the machine's media gets merged with its parent image. + + Neither the current machine state nor other snapshots are affected + by this operation, except that parent media will be modified + to contain the disk data associated with the snapshot being deleted. + + When deleting the current snapshot, the <link to="IMachine::currentSnapshot" /> + attribute is set to the current snapshot's parent or @c null if it + has no parent. Otherwise the attribute is unchanged. + </li> + </ul> + + Each snapshot contains a copy of virtual machine's settings (hardware + configuration etc.). This copy is contained in an immutable (read-only) + instance of <link to="IMachine" /> which is available from the snapshot's + <link to="#machine" /> attribute. When restoring the snapshot, these + settings are copied back to the original machine. + + In addition, if the machine was running when the + snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>), + the current VM state is saved in the snapshot (similarly to what happens + when a VM's state is saved). The snapshot is then said to be <i>online</i> + because when restoring it, the VM will be running. + + If the machine was in the <link to="MachineState_Saved">Saved</link> or + <link to="MachineState_AbortedSaved">AbortedSaved</link> state, the snapshot + receives a copy of the execution state file (<link to="IMachine::stateFilePath"/>). + + Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/> + or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>; + it then contains a so-called "zero execution state", representing a + machine that is powered off. + </desc> + + <attribute name="id" type="uuid" mod="string" readonly="yes"> + <desc>UUID of the snapshot.</desc> + </attribute> + + <attribute name="name" type="wstring"> + <desc>Short name of the snapshot. + <note>Setting this attribute causes <link to="IMachine::saveSettings" /> to + be called implicitly.</note> + </desc> + </attribute> + + <attribute name="description" type="wstring"> + <desc>Optional description of the snapshot. + <note>Setting this attribute causes <link to="IMachine::saveSettings" /> to + be called implicitly.</note> + </desc> + </attribute> + + <attribute name="timeStamp" type="long long" readonly="yes"> + <desc> + Timestamp of the snapshot, in milliseconds since 1970-01-01 UTC. + </desc> + </attribute> + + <attribute name="online" type="boolean" readonly="yes"> + <desc> + @c true if this snapshot is an online snapshot and @c false otherwise. + + When this attribute is @c true, the + <link to="IMachine::stateFilePath"/> attribute of the + <link to="#machine"/> object associated with this snapshot + will point to the saved state file. Otherwise, it will be + an empty string. + </desc> + </attribute> + + <attribute name="machine" type="IMachine" readonly="yes" rest="uuid"> + <desc> + Virtual machine this snapshot is taken on. This object + stores all settings the machine had when taking this snapshot. + <note> + The returned machine object is immutable, i.e. no + any settings can be changed. + </note> + </desc> + </attribute> + + <attribute name="parent" type="ISnapshot" readonly="yes" rest="uuid"> + <desc> + Parent snapshot (a snapshot this one is based on), or + @c null if the snapshot has no parent (i.e. is the first snapshot). + </desc> + </attribute> + + <attribute name="children" type="ISnapshot" readonly="yes" safearray="yes" rest="uuid"> + <desc> + Child snapshots (all snapshots having this one as a parent). + By inspecting this attribute starting with a machine's root snapshot + (which can be obtained by calling <link to="IMachine::findSnapshot" /> + with a @c null UUID), a machine's snapshots tree can be iterated over. + </desc> + </attribute> + + <attribute name="childrenCount" type="unsigned long" readonly="yes"> + <desc> + Returns the number of direct children of this snapshot. + </desc> + </attribute> + + </interface> + + + <!-- + // IMedium + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="MediumState" + uuid="ef41e980-e012-43cd-9dea-479d4ef14d13" + > + <desc> + Virtual medium state. + <see><link to="IMedium"/></see> + </desc> + + <const name="NotCreated" value="0"> + <desc> + Associated medium storage does not exist (either was not created yet or + was deleted). + </desc> + </const> + <const name="Created" value="1"> + <desc> + Associated storage exists and accessible; this gets set if the + accessibility check performed by <link to="IMedium::refreshState" /> + was successful. + </desc> + </const> + <const name="LockedRead" value="2"> + <desc> + Medium is locked for reading (see <link to="IMedium::lockRead"/>), + no data modification is possible. + </desc> + </const> + <const name="LockedWrite" value="3"> + <desc> + Medium is locked for writing (see <link to="IMedium::lockWrite"/>), + no concurrent data reading or modification is possible. + </desc> + </const> + <const name="Inaccessible" value="4"> + <desc> + Medium accessibility check (see <link to="IMedium::refreshState" />) has + not yet been performed, or else, associated medium storage is not + accessible. In the first case, <link to="IMedium::lastAccessError"/> + is empty, in the second case, it describes the error that occurred. + </desc> + </const> + <const name="Creating" value="5"> + <desc> + Associated medium storage is being created. + </desc> + </const> + <const name="Deleting" value="6"> + <desc> + Associated medium storage is being deleted. + </desc> + </const> + </enum> + + <enum + name="MediumType" + uuid="fe663fb5-c244-4e1b-9d81-c628b417dd04" + > + <desc> + Virtual medium type. For each <link to="IMedium" />, this defines how the medium is + attached to a virtual machine (see <link to="IMediumAttachment" />) and what happens + when a snapshot (see <link to="ISnapshot" />) is taken of a virtual machine which has + the medium attached. At the moment DVD and floppy media are always of type "writethrough". + </desc> + + <const name="Normal" value="0"> + <desc> + Normal medium (attached directly or indirectly, preserved + when taking snapshots). + </desc> + </const> + <const name="Immutable" value="1"> + <desc> + Immutable medium (attached indirectly, changes are wiped out + the next time the virtual machine is started). + </desc> + </const> + <const name="Writethrough" value="2"> + <desc> + Write through medium (attached directly, ignored when + taking snapshots). + </desc> + </const> + <const name="Shareable" value="3"> + <desc> + Allow using this medium concurrently by several machines. + <note>Present since VirtualBox 3.2.0, and accepted since 3.2.8.</note> + </desc> + </const> + <const name="Readonly" value="4"> + <desc> + A readonly medium, which can of course be used by several machines. + <note>Present and accepted since VirtualBox 4.0.</note> + </desc> + </const> + <const name="MultiAttach" value="5"> + <desc> + A medium which is indirectly attached, so that one base medium can + be used for several VMs which have their own differencing medium to + store their modifications. In some sense a variant of Immutable + with unset AutoReset flag in each differencing medium. + <note>Present and accepted since VirtualBox 4.0.</note> + </desc> + </const> + </enum> + + <enum + name="MediumVariant" + uuid="0282e97f-4ef3-4411-a8e0-47c384803cb6" + > + <desc> + Virtual medium image variant. More than one flag may be set. + <see><link to="IMedium"/></see> + </desc> + + <const name="Standard" value="0"> + <desc> + No particular variant requested, results in using the backend default. + </desc> + </const> + <const name="VmdkSplit2G" value="0x01"> + <desc> + VMDK image split in chunks of less than 2GByte. + </desc> + </const> + <const name="VmdkRawDisk" value="0x02"> + <desc> + VMDK image representing a raw disk. + </desc> + </const> + <const name="VmdkStreamOptimized" value="0x04"> + <desc> + VMDK streamOptimized image. Special import/export format which is + read-only/append-only. + </desc> + </const> + <const name="VmdkESX" value="0x08"> + <desc> + VMDK format variant used on ESX products. + </desc> + </const> + <const name="VdiZeroExpand" value="0x100"> + <desc> + Fill new blocks with zeroes while expanding image file. + </desc> + </const> + <const name="Fixed" value="0x10000"> + <desc> + Fixed image. Only allowed for base images. + </desc> + </const> + <const name="Diff" value="0x20000"> + <desc> + Differencing image. Only allowed for child images. + </desc> + </const> + <const name="Formatted" value="0x20000000"> + <desc> + Special flag which requests formatting the disk image. Right now + supported for floppy images only. + </desc> + </const> + <const name="NoCreateDir" value="0x40000000"> + <desc> + Special flag which suppresses automatic creation of the subdirectory. + Only used when passing the medium variant as an input parameter. + </desc> + </const> + </enum> + + <interface + name="IMediumAttachment" extends="$unknown" + uuid="8d095cb0-0126-43e0-b05d-326e74abb356" + wsmap="struct" + rest="managed" + reservedAttributes="8" + > + <desc> + The IMediumAttachment interface links storage media to virtual machines. + For each medium (<link to="IMedium"/>) which has been attached to a + storage controller (<link to="IStorageController"/>) of a machine + (<link to="IMachine"/>) via the <link to="IMachine::attachDevice" /> + method, one instance of IMediumAttachment is added to the machine's + <link to="IMachine::mediumAttachments"/> array attribute. + + Each medium attachment specifies the storage controller as well as a + port and device number and the IMedium instance representing a virtual + hard disk or floppy or DVD image. + + For removable media (DVDs or floppies), there are two additional + options. For one, the IMedium instance can be @c null to represent + an empty drive with no media inserted (see <link to="IMachine::mountMedium" />); + secondly, the medium can be one of the pseudo-media for host drives + listed in <link to="IHost::DVDDrives"/> or <link to="IHost::floppyDrives"/>. + + <h3>Attaching Hard Disks</h3> + + Hard disks are attached to virtual machines using the + <link to="IMachine::attachDevice"/> method and detached using the + <link to="IMachine::detachDevice"/> method. Depending on a medium's + type (see <link to="IMedium::type" />), hard disks are attached either + <i>directly</i> or <i>indirectly</i>. + + When a hard disk is being attached directly, it is associated with the + virtual machine and used for hard disk operations when the machine is + running. When a hard disk is being attached indirectly, a new differencing + hard disk linked to it is implicitly created and this differencing hard + disk is associated with the machine and used for hard disk operations. + This also means that if <link to="IMachine::attachDevice"/> performs + a direct attachment then the same hard disk will be returned in response + to the subsequent <link to="IMachine::getMedium"/> call; however if + an indirect attachment is performed then + <link to="IMachine::getMedium"/> will return the implicitly created + differencing hard disk, not the original one passed to <link + to="IMachine::attachDevice"/>. In detail: + + <ul> + <li><b>Normal base</b> hard disks that do not have children (i.e. + differencing hard disks linked to them) and that are not already + attached to virtual machines in snapshots are attached <b>directly</b>. + Otherwise, they are attached <b>indirectly</b> because having + dependent children or being part of the snapshot makes it impossible + to modify hard disk contents without breaking the integrity of the + dependent party. The <link to="IMedium::readOnly"/> attribute allows to + quickly determine the kind of the attachment for the given hard + disk. Note that if a normal base hard disk is to be indirectly + attached to a virtual machine with snapshots then a special + procedure called <i>smart attachment</i> is performed (see below).</li> + <li><b>Normal differencing</b> hard disks are like normal base hard disks: + they are attached <b>directly</b> if they do not have children and are + not attached to virtual machines in snapshots, and <b>indirectly</b> + otherwise. Note that the smart attachment procedure is never performed + for differencing hard disks.</li> + <li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because + they are designed to be non-writable. If an immutable hard disk is + attached to a virtual machine with snapshots then a special + procedure called smart attachment is performed (see below).</li> + <li><b>Writethrough</b> hard disks are always attached <b>directly</b>, + also as designed. This also means that writethrough hard disks cannot + have other hard disks linked to them at all.</li> + <li><b>Shareable</b> hard disks are always attached <b>directly</b>, + also as designed. This also means that shareable hard disks cannot + have other hard disks linked to them at all. They behave almost + like writethrough hard disks, except that shareable hard disks can + be attached to several virtual machines which are running, allowing + concurrent accesses. You need special cluster software running in + the virtual machines to make use of such disks.</li> + </ul> + + Note that the same hard disk, regardless of its type, may be attached to + more than one virtual machine at a time. In this case, the machine that is + started first gains exclusive access to the hard disk and attempts to + start other machines having this hard disk attached will fail until the + first machine is powered down. + + Detaching hard disks is performed in a <i>deferred</i> fashion. This means + that the given hard disk remains associated with the given machine after a + successful <link to="IMachine::detachDevice"/> call until + <link to="IMachine::saveSettings"/> is called to save all changes to + machine settings to disk. This deferring is necessary to guarantee that + the hard disk configuration may be restored at any time by a call to + <link to="IMachine::discardSettings"/> before the settings + are saved (committed). + + Note that if <link to="IMachine::discardSettings"/> is called after + indirectly attaching some hard disks to the machine but before a call to + <link to="IMachine::saveSettings"/> is made, it will implicitly delete + all differencing hard disks implicitly created by + <link to="IMachine::attachDevice"/> for these indirect attachments. + Such implicitly created hard disks will also be immediately deleted when + detached explicitly using the <link to="IMachine::detachDevice"/> + call if it is made before <link to="IMachine::saveSettings"/>. This + implicit deletion is safe because newly created differencing hard + disks do not contain any user data. + + However, keep in mind that detaching differencing hard disks that were + implicitly created by <link to="IMachine::attachDevice"/> + before the last <link to="IMachine::saveSettings"/> call will + <b>not</b> implicitly delete them as they may already contain some data + (for example, as a result of virtual machine execution). If these hard + disks are no more necessary, the caller can always delete them explicitly + using <link to="IMedium::deleteStorage"/> after they are actually de-associated + from this machine by the <link to="IMachine::saveSettings"/> call. + + <h3>Smart Attachment</h3> + + When normal base or immutable hard disks are indirectly attached to a + virtual machine then some additional steps are performed to make sure the + virtual machine will have the most recent "view" of the hard disk being + attached. These steps include walking through the machine's snapshots + starting from the current one and going through ancestors up to the first + snapshot. Hard disks attached to the virtual machine in all + of the encountered snapshots are checked whether they are descendants of + the given normal base or immutable hard disk. The first found child (which + is the differencing hard disk) will be used instead of the normal base or + immutable hard disk as a parent for creating a new differencing hard disk + that will be actually attached to the machine. And only if no descendants + are found or if the virtual machine does not have any snapshots then the + normal base or immutable hard disk will be used itself as a parent for + this differencing hard disk. + + It is easier to explain what smart attachment does using the + following example: + <pre> +BEFORE attaching B.vdi: AFTER attaching B.vdi: + +Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) + Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi) + Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi) + Snapshot 4 (none) Snapshot 4 (none) + CurState (none) CurState (D3->D2.vdi) + + NOT + ... + CurState (D3->B.vdi) + </pre> + The first column is the virtual machine configuration before the base hard + disk <tt>B.vdi</tt> is attached, the second column shows the machine after + this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar + mean that the hard disk that is actually attached to the machine is a + differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on) + another hard disk, <tt>B.vdi</tt>. + + As we can see from the example, the hard disk <tt>B.vdi</tt> was detached + from the machine before taking Snapshot 4. Later, after Snapshot 4 was + taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has + dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore + it cannot be attached directly and needs an indirect attachment (i.e. + implicit creation of a new differencing hard disk). Due to the smart + attachment procedure, the new differencing hard disk + (<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on + <tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of + <tt>B.vdi</tt> existing for this snapshot branch of the given virtual + machine. + + Note that if there is more than one descendant hard disk of the given base + hard disk found in a snapshot, and there is an exact device, channel and + bus match, then this exact match will be used. Otherwise, the youngest + descendant will be picked up. + + There is one more important aspect of the smart attachment procedure which + is not related to snapshots at all. Before walking through the snapshots + as described above, the backup copy of the current list of hard disk + attachment is searched for descendants. This backup copy is created when + the hard disk configuration is changed for the first time after the last + <link to="IMachine::saveSettings"/> call and used by + <link to="IMachine::discardSettings"/> to undo the recent hard disk + changes. When such a descendant is found in this backup copy, it will be + simply re-attached back, without creating a new differencing hard disk for + it. This optimization is necessary to make it possible to re-attach the + base or immutable hard disk to a different bus, channel or device slot + without losing the contents of the differencing hard disk actually + attached to the machine in place of it. + + </desc> + + <attribute name="machine" type="IMachine" readonly="yes" rest="uuid"> + <desc>Machine object for this medium attachment.</desc> + </attribute> + + <attribute name="medium" type="IMedium" readonly="yes" rest="uuid"> + <desc>Medium object associated with this attachment; it + can be @c null for removable devices.</desc> + </attribute> + + <attribute name="controller" type="wstring" readonly="yes"> + <desc>Name of the storage controller of this attachment; this + refers to one of the controllers in <link to="IMachine::storageControllers" /> + by name.</desc> + </attribute> + + <attribute name="port" type="long" readonly="yes"> + <desc>Port number of this attachment. + See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types. + </desc> + </attribute> + + <attribute name="device" type="long" readonly="yes"> + <desc>Device slot number of this attachment. + See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types. + </desc> + </attribute> + + <attribute name="type" type="DeviceType" readonly="yes"> + <desc>Device type of this attachment.</desc> + </attribute> + + <attribute name="passthrough" type="boolean" readonly="yes"> + <desc>Pass I/O requests through to a device on the host.</desc> + </attribute> + + <attribute name="temporaryEject" type="boolean" readonly="yes"> + <desc>Whether guest-triggered eject results in unmounting the medium.</desc> + </attribute> + + <attribute name="isEjected" type="boolean" readonly="yes"> + <desc>Signals that the removable medium has been ejected. This is not + necessarily equivalent to having a @c null medium association.</desc> + </attribute> + + <attribute name="nonRotational" type="boolean" readonly="yes"> + <desc>Whether the associated medium is non-rotational.</desc> + </attribute> + + <attribute name="discard" type="boolean" readonly="yes"> + <desc>Whether the associated medium supports discarding unused blocks.</desc> + </attribute> + + <attribute name="hotPluggable" type="boolean" readonly="yes"> + <desc>Whether this attachment is hot pluggable or not.</desc> + </attribute> + + <attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes"> + <desc>The bandwidth group this medium attachment is assigned to.</desc> + </attribute> + + </interface> + + <interface + name="IMedium" extends="$unknown" + uuid="ad47ad09-787b-44ab-b343-a082a3f2dfb1" + wsmap="managed" + rest="managed" + reservedMethods="7" reservedAttributes="12" + > + <desc> + The IMedium interface represents virtual storage for a machine's + hard disks, CD/DVD or floppy drives. It will typically represent + a disk image on the host, for example a VDI or VMDK file representing + a virtual hard disk, or an ISO or RAW file representing virtual + removable media, but can also point to a network location (e.g. + for iSCSI targets). + + Instances of IMedium are connected to virtual machines by way of medium + attachments, which link the storage medium to a particular device slot + of a storage controller of the virtual machine. + In the VirtualBox API, virtual storage is therefore always represented + by the following chain of object links: + + <ul> + <li><link to="IMachine::storageControllers"/> contains an array of + storage controllers (IDE, SATA, SCSI, SAS or a floppy controller; + these are instances of <link to="IStorageController"/>).</li> + <li><link to="IMachine::mediumAttachments"/> contains an array of + medium attachments (instances of <link to="IMediumAttachment"/> + created by <link to="IMachine::attachDevice" />), + each containing a storage controller from the above array, a + port/device specification, and an instance of IMedium representing + the medium storage (image file). + + For removable media, the storage medium is optional; a medium + attachment with no medium represents a CD/DVD or floppy drive + with no medium inserted. By contrast, hard disk attachments + will always have an IMedium object attached.</li> + <li>Each IMedium in turn points to a storage unit (such as a file + on the host computer or a network resource) that holds actual + data. This location is represented by the <link to="#location"/> + attribute.</li> + </ul> + + Existing media are opened using <link to="IVirtualBox::openMedium"/>; + new hard disk media can be created with the VirtualBox API using the + <link to="IVirtualBox::createMedium"/> method. Differencing hard + disks (see below) are usually implicitly created by VirtualBox as + needed, but may also be created explicitly using <link to="#createDiffStorage"/>. + VirtualBox cannot create CD/DVD or floppy images (ISO and RAW files); these + should be created with external tools and then opened from within VirtualBox. + + Only for CD/DVDs and floppies, an IMedium instance can also represent a host + drive. In that case the <link to="#id" /> attribute contains the UUID of + one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />. + + <h3>Media registries</h3> + + When a medium has been opened or created using one of the aforementioned + APIs, it becomes "known" to VirtualBox. Known media can be attached + to virtual machines and re-found through <link to="IVirtualBox::openMedium"/>. + They also appear in the global + <link to="IVirtualBox::hardDisks" />, + <link to="IVirtualBox::DVDImages" /> and + <link to="IVirtualBox::floppyImages" /> arrays. + + Prior to VirtualBox 4.0, opening a medium added it to a global media registry + in the VirtualBox.xml file, which was shared between all machines and made + transporting machines and their media from one host to another difficult. + + Starting with VirtualBox 4.0, media are only added to a registry when they are + <i>attached</i> to a machine using <link to="IMachine::attachDevice" />. For + backwards compatibility, which registry a medium is added to depends on which + VirtualBox version created a machine: + + <ul> + <li>If the medium has first been attached to a machine which was created by + VirtualBox 4.0 or later, it is added to that machine's media registry in + the machine XML settings file. This way all information about a machine's + media attachments is contained in a single file and can be transported + easily.</li> + <li>For older media attachments (i.e. if the medium was first attached to a + machine which was created with a VirtualBox version before 4.0), media + continue to be registered in the global VirtualBox settings file, for + backwards compatibility.</li> + </ul> + + See <link to="IVirtualBox::openMedium" /> for more information. + + Media are removed from media registries by the <link to="IMedium::close"/>, + <link to="#deleteStorage"/> and <link to="#mergeTo"/> methods. + + <h3>Accessibility checks</h3> + + VirtualBox defers media accessibility checks until the <link to="#refreshState" /> + method is called explicitly on a medium. This is done to make the VirtualBox object + ready for serving requests as fast as possible and let the end-user + application decide if it needs to check media accessibility right away or not. + + As a result, when VirtualBox starts up (e.g. the VirtualBox + object gets created for the first time), all known media are in the + "Inaccessible" state, but the value of the <link to="#lastAccessError"/> + attribute is an empty string because no actual accessibility check has + been made yet. + + After calling <link to="#refreshState" />, a medium is considered + <i>accessible</i> if its storage unit can be read. In that case, the + <link to="#state"/> attribute has a value of "Created". If the storage + unit cannot be read (for example, because it is located on a disconnected + network resource, or was accidentally deleted outside VirtualBox), + the medium is considered <i>inaccessible</i>, which is indicated by the + "Inaccessible" state. The exact reason why the medium is inaccessible can be + obtained by reading the <link to="#lastAccessError"/> attribute. + + <h3>Medium types</h3> + + There are five types of medium behavior which are stored in the + <link to="#type"/> attribute (see <link to="MediumType" />) and + which define the medium's behavior with attachments and snapshots. + + All media can be also divided in two groups: <i>base</i> media and + <i>differencing</i> media. A base medium contains all sectors of the + medium data in its own storage and therefore can be used independently. + In contrast, a differencing medium is a "delta" to some other medium and + contains only those sectors which differ from that other medium, which is + then called a <i>parent</i>. The differencing medium is said to be + <i>linked to</i> that parent. The parent may be itself a differencing + medium, thus forming a chain of linked media. The last element in that + chain must always be a base medium. Note that several differencing + media may be linked to the same parent medium. + + Differencing media can be distinguished from base media by querying the + <link to="#parent"/> attribute: base media do not have parents they would + depend on, so the value of this attribute is always @c null for them. + Using this attribute, it is possible to walk up the medium tree (from the + child medium to its parent). It is also possible to walk down the tree + using the <link to="#children"/> attribute. + + Note that the type of all differencing media is "normal"; all other + values are meaningless for them. Base media may be of any type. + + <h3>Automatic composition of the file name part</h3> + + Another extension to the <link to="IMedium::location"/> attribute is that + there is a possibility to cause VirtualBox to compose a unique value for + the file name part of the location using the UUID of the hard disk. This + applies only to hard disks in <link to="MediumState_NotCreated"/> state, + e.g. before the storage unit is created, and works as follows. You set the + value of the <link to="IMedium::location"/> attribute to a location + specification which only contains the path specification but not the file + name part and ends with either a forward slash or a backslash character. + In response, VirtualBox will generate a new UUID for the hard disk and + compose the file name using the following pattern: + <pre> + <path>/{<uuid>}.<ext> + </pre> + where <tt><path></tt> is the supplied path specification, + <tt><uuid></tt> is the newly generated UUID and <tt><ext></tt> + is the default extension for the storage format of this hard disk. After + that, you may call any of the methods that create a new hard disk storage + unit and they will use the generated UUID and file name. + </desc> + + <attribute name="id" type="uuid" mod="string" readonly="yes"> + <desc> + UUID of the medium. For a newly created medium, this value is a randomly + generated UUID. + + <note> + For media in one of MediumState_NotCreated, MediumState_Creating or + MediumState_Deleting states, the value of this property is undefined + and will most likely be an empty UUID. + </note> + </desc> + </attribute> + + <attribute name="description" type="wstring" wrap-hint-server="passcaller"> + <desc> + Optional description of the medium. For a newly created medium the value + of this attribute is an empty string. + + Medium types that don't support this attribute will return E_NOTIMPL in + attempt to get or set this attribute's value. + + <note> + For some storage types, reading this attribute may return an outdated + (last known) value when <link to="#state"/> is <link + to="MediumState_Inaccessible"/> or <link + to="MediumState_LockedWrite"/> because the value of this attribute is + stored within the storage unit itself. Also note that changing the + attribute value is not possible in such case, as well as when the + medium is the <link to="MediumState_LockedRead"/> state. + </note> + </desc> + </attribute> + + <attribute name="state" type="MediumState" readonly="yes"> + <desc> + Returns the current medium state, which is the last state set by + the accessibility check performed by <link to="#refreshState"/>. + If that method has not yet been called on the medium, the state + is "Inaccessible"; as opposed to truly inaccessible media, the + value of <link to="#lastAccessError"/> will be an empty string in + that case. + + <note>As of version 3.1, this no longer performs an accessibility check + automatically; call <link to="#refreshState"/> for that. + </note> + </desc> + </attribute> + + <attribute name="variant" type="MediumVariant" safearray="yes" readonly="yes"> + <desc> + Returns the storage format variant information for this medium + as an array of the flags described at <link to="MediumVariant" />. + Before <link to="#refreshState"/> is called this method returns + an undefined value. + </desc> + </attribute> + + <attribute name="location" type="wstring"> + <desc> + Location of the storage unit holding medium data. + + The format of the location string is medium type specific. For medium + types using regular files in a host's file system, the location + string is the full file name. + </desc> + </attribute> + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + Name of the storage unit holding medium data. + + The returned string is a short version of the <link to="#location"/> + attribute that is suitable for representing the medium in situations + where the full location specification is too long (such as lists + and comboboxes in GUI frontends). This string is also used by frontends + to sort the media list alphabetically when needed. + + For example, for locations that are regular files in the host's file + system, the value of this attribute is just the file name (+ extension), + without the path specification. + + Note that as opposed to the <link to="#location"/> attribute, the name + attribute will not necessary be unique for a list of media of the + given type and format. + </desc> + </attribute> + + <attribute name="deviceType" type="DeviceType" readonly="yes"> + <desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this + medium.</desc> + </attribute> + + <attribute name="hostDrive" type="boolean" readonly="yes"> + <desc>True if this corresponds to a drive on the host.</desc> + </attribute> + + <attribute name="size" type="long long" readonly="yes"> + <desc> + Physical size of the storage unit used to hold medium data (in bytes). + + <note> + For media whose <link to="#state"/> is <link + to="MediumState_Inaccessible"/>, the value of this property is the + last known size. For <link to="MediumState_NotCreated"/> media, + the returned value is zero. + </note> + </desc> + </attribute> + + <attribute name="format" type="wstring" readonly="yes"> + <desc> + Storage format of this medium. + + The value of this attribute is a string that specifies a backend used + to store medium data. The storage format is defined when you create a + new medium or automatically detected when you open an existing medium, + and cannot be changed later. + + The list of all storage formats supported by this VirtualBox + installation can be obtained using + <link to="ISystemProperties::mediumFormats"/>. + </desc> + </attribute> + + <attribute name="mediumFormat" type="IMediumFormat" readonly="yes"> + <desc> + Storage medium format object corresponding to this medium. + + The value of this attribute is a reference to the medium format object + that specifies the backend properties used to store medium data. The + storage format is defined when you create a new medium or automatically + detected when you open an existing medium, and cannot be changed later. + + <note>@c null is returned if there is no associated medium format + object. This can e.g. happen for medium objects representing host + drives and other special medium objects.</note> + </desc> + </attribute> + + <attribute name="type" type="MediumType" wrap-hint-server="passcaller"> + <desc> + Type (role) of this medium. + + The following constraints apply when changing the value of this + attribute: + <ul> + <li>If a medium is attached to a virtual machine (either in the + current state or in one of the snapshots), its type cannot be + changed. + </li> + <li>As long as the medium has children, its type cannot be set + to <link to="MediumType_Writethrough"/>. + </li> + <li>The type of all differencing media is + <link to="MediumType_Normal"/> and cannot be changed. + </li> + </ul> + + The type of a newly created or opened medium is set to + <link to="MediumType_Normal"/>, except for DVD and floppy media, + which have a type of <link to="MediumType_Writethrough"/>. + </desc> + </attribute> + + <attribute name="allowedTypes" type="MediumType" safearray="yes" readonly="yes"> + <desc> + Returns which medium types can selected for this medium. + + <result name="E_NOTIMPL"> + This attribute is not implemented at the moment. + </result> + </desc> + </attribute> + + <attribute name="parent" type="IMedium" readonly="yes" wrap-hint-server="passcaller" rest="uuid"> + <desc> + Parent of this medium (the medium this medium is directly based + on). + + Only differencing media have parents. For base (non-differencing) + media, @c null is returned. + </desc> + </attribute> + + <attribute name="children" type="IMedium" safearray="yes" readonly="yes" wrap-hint-server="passcaller" rest="uuid"> + <desc> + Children of this medium (all differencing media directly based + on this medium). A @c null array is returned if this medium + does not have any children. + </desc> + </attribute> + + <attribute name="base" type="IMedium" readonly="yes" wrap-hint-server="passcaller" rest="uuid"> + <desc> + Base medium of this medium. + + If this is a differencing medium, its base medium is the medium + the given medium branch starts from. For all other types of media, this + property returns the medium object itself (i.e. the same object this + property is read on). + </desc> + </attribute> + + <attribute name="readOnly" type="boolean" readonly="yes" wrap-hint-server="passcaller"> + <desc> + Returns @c true if this medium is read-only and @c false otherwise. + + A medium is considered to be read-only when its contents cannot be + modified without breaking the integrity of other parties that depend on + this medium such as its child media or snapshots of virtual machines + where this medium is attached to these machines. If there are no + children and no such snapshots then there is no dependency and the + medium is not read-only. + + The value of this attribute can be used to determine the kind of the + attachment that will take place when attaching this medium to a + virtual machine. If the value is @c false then the medium will + be attached directly. If the value is @c true then the medium + will be attached indirectly by creating a new differencing child + medium for that. See the interface description for more information. + + Note that all <link to="MediumType_Immutable">Immutable</link> media + are always read-only while all + <link to="MediumType_Writethrough">Writethrough</link> media are + always not. + + <note> + The read-only condition represented by this attribute is related to + the medium type and usage, not to the current + <link to="IMedium::state">medium state</link> and not to the read-only + state of the storage unit. + </note> + </desc> + </attribute> + + <attribute name="logicalSize" type="long long" readonly="yes"> + <desc> + Logical size of this medium (in bytes), as reported to the + guest OS running inside the virtual machine this medium is + attached to. The logical size is defined when the medium is created + and cannot be changed later. + + <note> + For media whose state is <link to="#state"/> is <link + to="MediumState_Inaccessible"/>, the value of this property is the + last known logical size. For <link to="MediumState_NotCreated"/> + media, the returned value is zero. + </note> + </desc> + </attribute> + + <attribute name="autoReset" type="boolean"> + <desc> + Whether this differencing medium will be automatically reset each + time a virtual machine it is attached to is powered up. This + attribute is automatically set to @c true for the last + differencing image of an "immutable" medium (see + <link to="MediumType" />). + + See <link to="#reset"/> for more information about resetting + differencing media. + + <note> + Reading this property on a base (non-differencing) medium will + always @c false. Changing the value of this property in this + case is not supported. + </note> + + <result name="VBOX_E_NOT_SUPPORTED"> + This is not a differencing medium (when changing the attribute + value). + </result> + </desc> + </attribute> + + <attribute name="lastAccessError" type="wstring" readonly="yes"> + <desc> + Text message that represents the result of the last accessibility + check performed by <link to="#refreshState"/>. + + An empty string is returned if the last accessibility check + was successful or has not yet been called. As a result, if + <link to="#state" /> is "Inaccessible" and this attribute is empty, + then <link to="#refreshState"/> has yet to be called; this is the + default value of media after VirtualBox initialization. + A non-empty string indicates a failure and should normally describe + a reason of the failure (for example, a file read error). + </desc> + </attribute> + + <attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes"> + <desc> + Array of UUIDs of all machines this medium is attached to. + + A @c null array is returned if this medium is not attached to any + machine or to any machine's snapshot. + + <note> + The returned array will include a machine even if this medium is not + attached to that machine in the current state but attached to it in + one of the machine's snapshots. See <link to="#getSnapshotIds"/> for + details. + </note> + </desc> + </attribute> + + <method name="setIds" wrap-hint-server="passcaller"> + <rest request="post" path="/mediums/{mediumid}/configuration/"/> + <desc> + Changes the UUID and parent UUID for a hard disk medium. + </desc> + <param name="setImageId" type="boolean" dir="in"> + <desc> + Select whether a new image UUID is set or not. + </desc> + </param> + <param name="imageId" type="uuid" mod="string" dir="in"> + <desc> + New UUID for the image. If an empty string is passed, then a new + UUID is automatically created, provided that @a setImageId is @c true. + Specifying a zero UUID is not allowed. + </desc> + </param> + <param name="setParentId" type="boolean" dir="in"> + <desc> + Select whether a new parent UUID is set or not. + </desc> + </param> + <param name="parentId" type="uuid" mod="string" dir="in"> + <desc> + New parent UUID for the image. If an empty string is passed, then a + new UUID is automatically created, provided @a setParentId is + @c true. A zero UUID is valid. + </desc> + </param> + <result name="E_INVALIDARG"> + Invalid parameter combination. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Medium is not a hard disk medium. + </result> + </method> + + <method name="refreshState" wrap-hint-server="passcaller"> + <rest request="post" path="/mediums/{mediumid}/configuration/"/> + <desc> + If the current medium state (see <link to="MediumState"/>) is one of + "Created", "Inaccessible" or "LockedRead", then this performs an + accessibility check on the medium and sets the value of the <link to="#state"/> + attribute accordingly; that value is also returned for convenience. + + For all other state values, this does not perform a refresh but returns + the state only. + + The refresh, if performed, may take a long time (several seconds or even + minutes, depending on the storage unit location and format) because it performs an + accessibility check of the storage unit. This check may cause a significant + delay if the storage unit of the given medium is, for example, a file located + on a network share which is not currently accessible due to connectivity + problems. In that case, the call will not return until a timeout + interval defined by the host OS for this operation expires. For this reason, + it is recommended to never read this attribute on the main UI thread to avoid + making the UI unresponsive. + + If the last known state of the medium is "Created" and the accessibility + check fails, then the state would be set to "Inaccessible", and + <link to="#lastAccessError"/> may be used to get more details about the + failure. If the state of the medium is "LockedRead", then it remains the + same, and a non-empty value of <link to="#lastAccessError"/> will + indicate a failed accessibility check in this case. + + Note that not all medium states are applicable to all medium types. + </desc> + <param name="state" type="MediumState" dir="return"> + <desc> + New medium state. + </desc> + </param> + </method> + + <method name="getSnapshotIds"> + <rest request="get" path="/mediums/{mediumid}/configuration/"/> + <desc> + Returns an array of UUIDs of all snapshots of the given machine where + this medium is attached to. + + If the medium is attached to the machine in the current state, then the + first element in the array will always be the ID of the queried machine + (i.e. the value equal to the @c machineId argument), followed by + snapshot IDs (if any). + + If the medium is not attached to the machine in the current state, then + the array will contain only snapshot IDs. + + The returned array may be @c null if this medium is not attached + to the given machine at all, neither in the current state nor in one of + the snapshots. + </desc> + <param name="machineId" type="uuid" mod="string" dir="in"> + <desc> + UUID of the machine to query. + </desc> + </param> + <param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return"> + <desc> + Array of snapshot UUIDs of the given machine using this medium. + </desc> + </param> + </method> + + <method name="lockRead"> + <rest request="post" path="/mediums/{mediumid}/configuration/"/> + <desc> + Locks this medium for reading. + + A read lock is shared: many clients can simultaneously lock the + same medium for reading unless it is already locked for writing (see + <link to="#lockWrite"/>) in which case an error is returned. + + When the medium is locked for reading, it cannot be modified + from within VirtualBox. This means that any method that changes + the properties of this medium or contents of the storage unit + will return an error (unless explicitly stated otherwise). That + includes an attempt to start a virtual machine that wants to + write to the medium. + + When the virtual machine is started up, it locks for reading all + media it uses in read-only mode. If some medium cannot be locked + for reading, the startup procedure will fail. + A medium is typically locked for reading while it is used by a running + virtual machine but has a depending differencing image that receives + the actual write operations. This way one base medium can have + multiple child differencing images which can be written to + simultaneously. Read-only media such as DVD and floppy images are + also locked for reading only (so they can be in use by multiple + machines simultaneously). + + A medium is also locked for reading when it is the source of a + write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>. + + The medium locked for reading must be unlocked by abandoning the + returned token object, see <link to="IToken"/>. Calls to + <link to="#lockRead"/> can be nested and the lock is actually released + when all callers have abandoned the token. + + This method sets the medium state (see <link to="#state"/>) to + "LockedRead" on success. The medium's previous state must be + one of "Created", "Inaccessible" or "LockedRead". + + Locking an inaccessible medium is not an error; this method performs + a logical lock that prevents modifications of this medium through + the VirtualBox API, not a physical file-system lock of the underlying + storage unit. + + This method returns the current state of the medium + <i>before</i> the operation. + + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Invalid medium state (e.g. not created, locked, inaccessible, + creating, deleting). + </result> + + </desc> + <param name="token" type="IToken" dir="return"> + <desc> + Token object, when this is released (reference count reaches 0) then + the lock count is decreased. The lock is released when the lock count + reaches 0. + </desc> + </param> + </method> + + <method name="lockWrite"> + <rest request="post" path="/mediums/{mediumid}/configuration/"/> + <desc> + Locks this medium for writing. + + A write lock, as opposed to <link to="#lockRead"/>, is + exclusive: there may be only one client holding a write lock, + and there may be no read locks while the write lock is held. + As a result, read-locking fails if a write lock is held, and + write-locking fails if either a read or another write lock is held. + + When a medium is locked for writing, it cannot be modified + from within VirtualBox, and it is not guaranteed that the values + of its properties are up-to-date. Any method that changes the + properties of this medium or contents of the storage unit will + return an error (unless explicitly stated otherwise). + + When a virtual machine is started up, it locks for writing all + media it uses to write data to. If any medium could not be locked + for writing, the startup procedure will fail. If a medium has + differencing images, then while the machine is running, only + the last ("leaf") differencing image is locked for writing, + whereas its parents are locked for reading only. + + A medium is also locked for writing when it is the target of a + write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>. + + The medium locked for writing must be unlocked by abandoning the + returned token object, see <link to="IToken"/>. Write locks + <i>cannot</i> be nested. + + This method sets the medium state (see <link to="#state"/>) to + "LockedWrite" on success. The medium's previous state must be + either "Created" or "Inaccessible". + + Locking an inaccessible medium is not an error; this method performs + a logical lock that prevents modifications of this medium through + the VirtualBox API, not a physical file-system lock of the underlying + storage unit. + + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Invalid medium state (e.g. not created, locked, inaccessible, + creating, deleting). + </result> + + </desc> + <param name="token" type="IToken" dir="return"> + <desc> + Token object, when this is released (reference count reaches 0) then + the lock is released. + </desc> + </param> + </method> + + <method name="close" wrap-hint-server="passcaller"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Closes this medium. + + The medium must not be attached to any known virtual machine + and must not have any known child media, otherwise the + operation will fail. + + When the medium is successfully closed, it is removed from + the list of registered media, but its storage unit is not + deleted. In particular, this means that this medium can + later be opened again using the <link to="IVirtualBox::openMedium"/> + call. + + Note that after this method successfully returns, the given medium + object becomes uninitialized. This means that any attempt + to call any of its methods or attributes will fail with the + <tt>"Object not ready" (E_ACCESSDENIED)</tt> error. + + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Invalid medium state (other than not created, created or + inaccessible). + </result> + <result name="VBOX_E_OBJECT_IN_USE"> + Medium attached to virtual machine. + </result> + <result name="VBOX_E_FILE_ERROR"> + Settings file not accessible. + </result> + <result name="VBOX_E_XML_ERROR"> + Could not parse the settings file. + </result> + + </desc> + </method> + + <!-- property methods --> + + <method name="getProperty" const="yes"> + <rest request="get" path="/mediums/{mediumid}/configuration/"/> + <desc> + Returns the value of the custom medium property with the given name. + + The list of all properties supported by the given medium format can + be obtained with <link to="IMediumFormat::describeProperties"/>. + + <note>If this method returns an empty string in @a value, the requested + property is supported but currently not assigned any value.</note> + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Requested property does not exist (not supported by the format). + </result> + <result name="E_INVALIDARG">@a name is @c null or empty.</result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the property to get.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc>Current property value.</desc> + </param> + </method> + + <method name="setProperty"> + <rest request="post" path="/mediums/{mediumid}/configuration/"/> + <desc> + Sets the value of the custom medium property with the given name. + + The list of all properties supported by the given medium format can + be obtained with <link to="IMediumFormat::describeProperties"/>. + + <note>Setting the property value to @c null or an empty string is + equivalent to deleting the existing value. A default value (if it is + defined for this property) will be used by the format backend in this + case.</note> + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Requested property does not exist (not supported by the format). + </result> + <result name="E_INVALIDARG">@a name is @c null or empty.</result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the property to set.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc>Property value to set.</desc> + </param> + </method> + + <method name="getProperties" const="yes"> + <rest request="get" path="/mediums/{mediumid}/configuration/"/> + <desc> + Returns values for a group of properties in one call. + + The names of the properties to get are specified using the @a names + argument which is a list of comma-separated property names or + an empty string if all properties are to be returned. + <note>Currently the value of this argument is ignored and the method + always returns all existing properties.</note> + + The list of all properties supported by the given medium format can + be obtained with <link to="IMediumFormat::describeProperties"/>. + + The method returns two arrays, the array of property names corresponding + to the @a names argument and the current values of these properties. + Both arrays have the same number of elements with each element at the + given index in the first array corresponds to an element at the same + index in the second array. + + For properties that do not have assigned values, an empty string is + returned at the appropriate index in the @a returnValues array. + + </desc> + <param name="names" type="wstring" dir="in"> + <desc> + Names of properties to get. + </desc> + </param> + <param name="returnNames" type="wstring" safearray="yes" dir="out"> + <desc>Names of returned properties.</desc> + </param> + <param name="returnValues" type="wstring" safearray="yes" dir="return"> + <desc>Values of returned properties.</desc> + </param> + </method> + + <method name="setProperties"> + <rest request="post" path="/mediums/{mediumid}/configuration/"/> + <desc> + Sets values for a group of properties in one call. + + The names of the properties to set are passed in the @a names + array along with the new values for them in the @a values array. Both + arrays have the same number of elements with each element at the given + index in the first array corresponding to an element at the same index + in the second array. + + If there is at least one property name in @a names that is not valid, + the method will fail before changing the values of any other properties + from the @a names array. + + Using this method over <link to="#setProperty"/> is preferred if you + need to set several properties at once since it is more efficient. + + The list of all properties supported by the given medium format can + be obtained with <link to="IMediumFormat::describeProperties"/>. + + Setting the property value to @c null or an empty string is equivalent + to deleting the existing value. A default value (if it is defined for + this property) will be used by the format backend in this case. + </desc> + <param name="names" type="wstring" safearray="yes" dir="in"> + <desc>Names of properties to set.</desc> + </param> + <param name="values" type="wstring" safearray="yes" dir="in"> + <desc>Values of properties to set.</desc> + </param> + </method> + + <!-- storage methods --> + + <method name="createBaseStorage"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts creating a hard disk storage unit (fixed/dynamic, according + to the variant flags) in the background. The previous storage unit + created for this object, if any, must first be deleted using + <link to="#deleteStorage"/>, otherwise the operation will fail. + + Before the operation starts, the medium is placed in + <link to="MediumState_Creating"/> state. If the create operation + fails, the medium will be placed back in <link to="MediumState_NotCreated"/> + state. + + After the returned progress object reports that the operation has + successfully completed, the medium state will be set to <link + to="MediumState_Created"/>, the medium will be remembered by this + VirtualBox installation and may be attached to virtual machines. + + <result name="VBOX_E_NOT_SUPPORTED"> + The variant of storage creation operation is not supported. See <link + to="IMediumFormat::capabilities"/>. + </result> + </desc> + <param name="logicalSize" type="long long" dir="in"> + <desc>Maximum logical size of the medium in bytes.</desc> + </param> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> + <desc>Exact image variant which should be created (as a combination of + <link to="MediumVariant" /> flags).</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="deleteStorage"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts deleting the storage unit of this medium. + + The medium must not be attached to any known virtual machine and must + not have any known child media, otherwise the operation will fail. + It will also fail if there is no storage unit to delete or if deletion + is already in progress, or if the medium is being in use (locked for + read or for write) or inaccessible. Therefore, the only valid state for + this operation to succeed is <link to="MediumState_Created"/>. + + Before the operation starts, the medium is placed in + <link to="MediumState_Deleting"/> state and gets removed from the list + of remembered hard disks (media registry). If the delete operation + fails, the medium will be remembered again and placed back to + <link to="MediumState_Created"/> state. + + After the returned progress object reports that the operation is + complete, the medium state will be set to + <link to="MediumState_NotCreated"/> and you will be able to use one of + the storage creation methods to create it again. + + <see><link to="#close"/></see> + + <result name="VBOX_E_OBJECT_IN_USE"> + Medium is attached to a virtual machine. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Storage deletion is not allowed because neither of storage creation + operations are supported. See + <link to="IMediumFormat::capabilities"/>. + </result> + + <note> + If the deletion operation fails, it is not guaranteed that the storage + unit still exists. You may check the <link to="IMedium::state"/> value + to answer this question. + </note> + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <!-- diff methods --> + + <method name="createDiffStorage" wrap-hint-server="passcaller"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts creating an empty differencing storage unit based on this + medium in the format and at the location defined by the @a target + argument. + + The target medium must be in <link to="MediumState_NotCreated"/> + state (i.e. must not have an existing storage unit). Upon successful + completion, this operation will set the type of the target medium to + <link to="MediumType_Normal"/> and create a storage unit necessary to + represent the differencing medium data in the given format (according + to the storage format of the target object). + + After the returned progress object reports that the operation is + successfully complete, the target medium gets remembered by this + VirtualBox installation and may be attached to virtual machines. + + <note> + The medium will be set to <link to="MediumState_LockedRead"/> + state for the duration of this operation. + </note> + <result name="VBOX_E_OBJECT_IN_USE"> + Medium not in @c NotCreated state. + </result> + </desc> + <param name="target" type="IMedium" dir="in"> + <desc>Target medium.</desc> + </param> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> + <desc>Exact image variant which should be created (as a combination of + <link to="MediumVariant" /> flags).</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="mergeTo"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts merging the contents of this medium and all intermediate + differencing media in the chain to the given target medium. + + The target medium must be either a descendant of this medium or + its ancestor (otherwise this method will immediately return a failure). + It follows that there are two logical directions of the merge operation: + from ancestor to descendant (<i>forward merge</i>) and from descendant to + ancestor (<i>backward merge</i>). Let us consider the following medium + chain: + + <pre>Base <- Diff_1 <- Diff_2</pre> + + Here, calling this method on the <tt>Base</tt> medium object with + <tt>Diff_2</tt> as an argument will be a forward merge; calling it on + <tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward + merge. Note that in both cases the contents of the resulting medium + will be the same, the only difference is the medium object that takes + the result of the merge operation. In case of the forward merge in the + above example, the result will be written to <tt>Diff_2</tt>; in case of + the backward merge, the result will be written to <tt>Base</tt>. In + other words, the result of the operation is always stored in the target + medium. + + Upon successful operation completion, the storage units of all media in + the chain between this (source) medium and the target medium, including + the source medium itself, will be automatically deleted and the + relevant medium objects (including this medium) will become + uninitialized. This means that any attempt to call any of + their methods or attributes will fail with the + <tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above + example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will + delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media. + Note that <tt>Diff_2</tt> in this case will become a base medium + itself since it will no longer be based on any other medium. + + Considering the above, all of the following conditions must be met in + order for the merge operation to succeed: + <ul> + <li> + Neither this (source) medium nor any intermediate + differencing medium in the chain between it and the target + medium is attached to any virtual machine. + </li> + <li> + Neither the source medium nor the target medium is an + <link to="MediumType_Immutable"/> medium. + </li> + <li> + The part of the medium tree from the source medium to the + target medium is a linear chain, i.e. all medium in this + chain have exactly one child which is the next medium in this + chain. The only exception from this rule is the target medium in + the forward merge operation; it is allowed to have any number of + child media because the merge operation will not change its + logical contents (as it is seen by the guest OS or by children). + </li> + <li> + None of the involved media are in + <link to="MediumState_LockedRead"/> or + <link to="MediumState_LockedWrite"/> state. + </li> + </ul> + + <note> + This (source) medium and all intermediates will be placed to <link + to="MediumState_Deleting"/> state and the target medium will be + placed to <link to="MediumState_LockedWrite"/> state and for the + duration of this operation. + </note> + </desc> + <param name="target" type="IMedium" dir="in"> + <desc>Target medium.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <!-- clone method --> + + <method name="cloneTo"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts creating a clone of this medium in the format and at the + location defined by the @a target argument. + + The target medium must be either in <link to="MediumState_NotCreated"/> + state (i.e. must not have an existing storage unit) or in + <link to="MediumState_Created"/> state (i.e. created and not locked, and + big enough to hold the data or else the copy will be partial). Upon + successful completion, the cloned medium will contain exactly the + same sector data as the medium being cloned, except that in the + first case a new UUID for the clone will be randomly generated, and in + the second case the UUID will remain unchanged. + + The @a parent argument defines which medium will be the parent + of the clone. Passing a @c null reference indicates that the clone will + be a base image, i.e. completely independent. It is possible to specify + an arbitrary medium for this parameter, including the parent of the + medium which is being cloned. Even cloning to a child of the source + medium is possible. Note that when cloning to an existing image, the + @a parent argument is ignored. + + After the returned progress object reports that the operation is + successfully complete, the target medium gets remembered by this + VirtualBox installation and may be attached to virtual machines. + + <note> + This medium will be placed to <link to="MediumState_LockedRead"/> + state for the duration of this operation. + </note> + <result name="E_NOTIMPL"> + The specified cloning variant is not supported at the moment. + </result> + </desc> + <param name="target" type="IMedium" dir="in"> + <desc>Target medium.</desc> + </param> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> + <desc>Exact image variant which should be created (as a combination of + <link to="MediumVariant" /> flags).</desc> + </param> + <param name="parent" type="IMedium" dir="in"> + <desc>Parent of the cloned medium.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="cloneToBase"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts creating a clone of this medium in the format and at the + location defined by the @a target argument. + + The target medium must be either in <link to="MediumState_NotCreated"/> + state (i.e. must not have an existing storage unit) or in + <link to="MediumState_Created"/> state (i.e. created and not locked, and + big enough to hold the data or else the copy will be partial). Upon + successful completion, the cloned medium will contain exactly the + same sector data as the medium being cloned, except that in the + first case a new UUID for the clone will be randomly generated, and in + the second case the UUID will remain unchanged. + + The @a parent argument defines which medium will be the parent + of the clone. In this case the clone will be a base image, i.e. + completely independent. It is possible to specify an arbitrary + medium for this parameter, including the parent of the + medium which is being cloned. Even cloning to a child of the source + medium is possible. Note that when cloning to an existing image, the + @a parent argument is ignored. + + After the returned progress object reports that the operation is + successfully complete, the target medium gets remembered by this + VirtualBox installation and may be attached to virtual machines. + + <note> + This medium will be placed to <link to="MediumState_LockedRead"/> + state for the duration of this operation. + </note> + <result name="E_NOTIMPL"> + The specified cloning variant is not supported at the moment. + </result> + </desc> + <param name="target" type="IMedium" dir="in"> + <desc>Target medium.</desc> + </param> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> + <desc><link to="MediumVariant" /> flags).</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <!-- other methods --> + + <method name="moveTo" wrap-hint-server="passcaller"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Changes the location of this medium. Some medium types may support + changing the storage unit location by simply changing the value of the + associated property. In this case the operation is performed + immediately, and @a progress is returning a @c null reference. + Otherwise on success there is a progress object returned, which + signals progress and completion of the operation. This distinction is + necessary because for some formats the operation is very fast, while + for others it can be very slow (moving the image file by copying all + data), and in the former case it'd be a waste of resources to create + a progress object which will immediately signal completion. + + When setting a location for a medium which corresponds to a/several + regular file(s) in the host's file system, the given file name may be + either relative to the <link to="IVirtualBox::homeFolder">VirtualBox + home folder</link> or absolute. Note that if the given location + specification does not contain the file extension part then a proper + default extension will be automatically appended by the implementation + depending on the medium type. + + <result name="E_NOTIMPL"> + The operation is not implemented yet. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Medium format does not support changing the location. + </result> + </desc> + <param name="location" type="wstring" dir="in"> + <desc>New location.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="compact"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts compacting of this medium. This means that the medium is + transformed into a possibly more compact storage representation. + This potentially creates temporary images, which can require a + substantial amount of additional disk space. + + This medium will be placed to <link to="MediumState_LockedWrite"/> + state and all its parent media (if any) will be placed to + <link to="MediumState_LockedRead"/> state for the duration of this + operation. + + Please note that the results can be either returned straight away, + or later as the result of the background operation via the object + returned via the @a progress parameter. + + <result name="VBOX_E_NOT_SUPPORTED"> + Medium format does not support compacting (but potentially + needs it). + </result> + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="resize"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts resizing this medium. This means that the nominal size of the + medium is set to the new value. Both increasing and decreasing the + size is possible, and there are no safety checks, since VirtualBox + does not make any assumptions about the medium contents. + + Resizing usually needs additional disk space, and possibly also + some temporary disk space. Note that resize does not create a full + temporary copy of the medium, so the additional disk space requirement + is usually much lower than using the clone operation. + + This medium will be placed to <link to="MediumState_LockedWrite"/> + state for the duration of this operation. + + Please note that the results can be either returned straight away, + or later as the result of the background operation via the object + returned via the @a progress parameter. + + <result name="VBOX_E_NOT_SUPPORTED"> + Medium format does not support resizing. + </result> + </desc> + <param name="logicalSize" type="long long" dir="in"> + <desc>New nominal capacity of the medium in bytes.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="reset" wrap-hint-server="passcaller"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts erasing the contents of this differencing medium. + + This operation will reset the differencing medium to its initial + state when it does not contain any sector data and any read operation is + redirected to its parent medium. This automatically gets called + during VM power-up for every medium whose <link to="#autoReset" /> + attribute is @c true. + + The medium will be write-locked for the duration of this operation (see + <link to="#lockWrite" />). + + <result name="VBOX_E_NOT_SUPPORTED"> + This is not a differencing medium. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Medium is not in <link to="MediumState_Created"/> or + <link to="MediumState_Inaccessible"/> state. + </result> + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="changeEncryption"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + <desc> + Starts encryption of this medium. This means that the stored data in the + medium is encrypted. + + This medium will be placed to <link to="MediumState_LockedWrite"/> + state. + + Please note that the results can be either returned straight away, + or later as the result of the background operation via the object + returned via the @a progress parameter. + + <result name="VBOX_E_NOT_SUPPORTED"> + Encryption is not supported for this medium because it is attached to more than one VM + or has children. + </result> + </desc> + <param name="currentPassword" type="wstring" dir="in"> + <desc> + The current password the medium is protected with. Use an empty string to indicate + that the medium isn't encrypted. + </desc> + </param> + <param name="cipher" type="wstring" dir="in"> + <desc> + The cipher to use for encryption. An empty string indicates no encryption for the + result. + </desc> + </param> + <param name="newPassword" type="wstring" dir="in"> + <desc> + The new password the medium should be protected with. An empty password and password ID + will result in the medium being encrypted with the current password. + </desc> + </param> + <param name="newPasswordId" type="wstring" dir="in"> + <desc>The ID of the new password when unlocking the medium.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="getEncryptionSettings" const="yes" wrap-hint-server="passcaller"> + <rest request="get" path="/mediums/{mediumid}/configuration/"/> + <desc> + Returns the encryption settings for this medium. + + <result name="VBOX_E_NOT_SUPPORTED"> + Encryption is not configured for this medium. + </result> + </desc> + <param name="cipher" type="wstring" dir="out"> + <desc>The cipher used for encryption.</desc> + </param> + <param name="passwordId" type="wstring" dir="return"> + <desc>The ID of the password when unlocking the medium.</desc> + </param> + </method> + + <method name="checkEncryptionPassword" const="yes"> + <rest request="get" path="/mediums/{mediumid}/configuration/"/> + <desc> + Checks whether the supplied password is correct for the medium. + + <result name="VBOX_E_NOT_SUPPORTED"> + Encryption is not configured for this medium. + </result> + <result name="VBOX_E_PASSWORD_INCORRECT"> + The given password is incorrect. + </result> + </desc> + <param name="password" type="wstring" dir="in"> + <desc>The password to check.</desc> + </param> + </method> + + <method name="openForIO"> + <desc> + Open the medium for I/O. + </desc> + <param name="writable" type="boolean" dir="in"> + <desc>Set this to open the medium for both reading and writing. When + not set the medium is opened readonly.</desc> + </param> + <param name="password" type="wstring" dir="in"> + <desc>Password for accessing an encrypted medium. Must be empty if not encrypted.</desc> + </param> + <param name="mediumIO" type="IMediumIO" dir="return"> + <desc>Medium I/O object.</desc> + </param> + </method> + + <method name="resizeAndCloneTo"> + <rest request="post" path="/mediums/{mediumid}/actions/"/> + + <desc> + This is a helper function that combines the functionality of + <link to="IMedium::cloneTo"/> and <link to="IMedium::resize"/>. The target medium will take the + contents of the calling medium. + <result name="E_NOTIMPL"> + The specified cloning variant is not supported at the moment. + </result> + + <note> + Method will be moved to appropriate location at the next major API release. + </note> + </desc> + + <param name="target" type="IMedium" dir="in"> + <desc>Target medium.</desc> + </param> + <param name="logicalSize" type="long long" dir="in"> + <desc>New nominal capacity of the medium in bytes.</desc> + </param> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> + <desc>Exact image variant which should be created (as a combination of + <link to="MediumVariant" /> flags).</desc> + </param> + <param name="parent" type="IMedium" dir="in"> + <desc>Parent of the cloned medium.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + </interface> + + + <!-- + // IMediumFormat + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="DataType" + uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7" + > + <const name="Int32" value="0"/> + <const name="Int8" value="1"/> + <const name="String" value="2"/> + </enum> + + <enum + name="DataFlags" + uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60" + > + <const name="None" value="0x00"/> + <const name="Mandatory" value="0x01"/> + <const name="Expert" value="0x02"/> + <const name="Array" value="0x04"/> + <const name="FlagMask" value="0x07"/> + </enum> + + <enum + name="MediumFormatCapabilities" + uuid="7342ba79-7ce0-4d94-8f86-5ed5a185d9bd" + > + <desc> + Medium format capability flags. + </desc> + + <const name="Uuid" value="0x01"> + <desc> + Supports UUIDs as expected by VirtualBox code. + </desc> + </const> + + <const name="CreateFixed" value="0x02"> + <desc> + Supports creating fixed size images, allocating all space instantly. + </desc> + </const> + + <const name="CreateDynamic" value="0x04"> + <desc> + Supports creating dynamically growing images, allocating space on + demand. + </desc> + </const> + + <const name="CreateSplit2G" value="0x08"> + <desc> + Supports creating images split in chunks of a bit less than 2 GBytes. + </desc> + </const> + + <const name="Differencing" value="0x10"> + <desc> + Supports being used as a format for differencing media (see <link + to="IMedium::createDiffStorage"/>). + </desc> + </const> + + <const name="Asynchronous" value="0x20"> + <desc> + Supports asynchronous I/O operations for at least some configurations. + </desc> + </const> + + <const name="File" value="0x40"> + <desc> + The format backend operates on files (the <link to="IMedium::location"/> + attribute of the medium specifies a file used to store medium + data; for a list of supported file extensions see + <link to="IMediumFormat::describeFileExtensions"/>). + </desc> + </const> + + <const name="Properties" value="0x80"> + <desc> + The format backend uses the property interface to configure the storage + location and properties (the <link to="IMediumFormat::describeProperties"/> + method is used to get access to properties supported by the given medium format). + </desc> + </const> + + <const name="TcpNetworking" value="0x100"> + <desc> + The format backend uses the TCP networking interface for network access. + </desc> + </const> + + <const name="VFS" value="0x200"> + <desc> + The format backend supports virtual filesystem functionality. + </desc> + </const> + + <const name="Discard" value="0x400"> + <desc> + The format backend supports discarding blocks. + </desc> + </const> + + <const name="Preferred" value="0x800"> + <desc> + Indicates that this is a frequently used format backend. + </desc> + </const> + + <const name="CapabilityMask" value="0xFFF"/> + </enum> + + <interface + name="IMediumFormat" extends="$unknown" + uuid="11be93c7-a862-4dc9-8c89-bf4ba74a886a" + wsmap="managed" + rest="managed" + reservedMethods="2" reservedAttributes="4" + > + <desc> + The IMediumFormat interface represents a medium format. + + Each medium format has an associated backend which is used to handle + media stored in this format. This interface provides information + about the properties of the associated backend. + + Each medium format is identified by a string represented by the + <link to="#id"/> attribute. This string is used in calls like + <link to="IVirtualBox::createMedium"/> to specify the desired + format. + + The list of all supported medium formats can be obtained using + <link to="ISystemProperties::mediumFormats"/>. + + <see><link to="IMedium"/></see> + </desc> + + <attribute name="id" type="wstring" readonly="yes"> + <desc> + Identifier of this format. + + The format identifier is a non-@c null non-empty ASCII string. Note that + this string is case-insensitive. This means that, for example, all of + the following strings: + <pre> + "VDI" + "vdi" + "VdI"</pre> + refer to the same medium format. + + This string is used in methods of other interfaces where it is necessary + to specify a medium format, such as + <link to="IVirtualBox::createMedium"/>. + </desc> + </attribute> + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + Human readable description of this format. + + Mainly for use in file open dialogs. + </desc> + </attribute> + + <attribute name="capabilities" type="MediumFormatCapabilities" safearray="yes" readonly="yes"> + <desc> + Capabilities of the format as an array of the flags. + + For the meaning of individual capability flags see + <link to="MediumFormatCapabilities"/>. + </desc> + </attribute> + + <method name="describeFileExtensions" const="yes"> + <desc> + Returns two arrays describing the supported file extensions. + + The first array contains the supported extensions and the seconds one + the type each extension supports. Both have the same size. + + Note that some backends do not work on files, so this array may be + empty. + + <see><link to="IMediumFormat::capabilities"/></see> + </desc> + <param name="extensions" type="wstring" safearray="yes" dir="out"> + <desc>The array of supported extensions.</desc> + </param> + <param name="types" type="DeviceType" safearray="yes" dir="out"> + <desc>The array which indicates the device type for every given extension.</desc> + </param> + </method> + + <method name="describeProperties" const="yes"> + <desc> + Returns several arrays describing the properties supported by this + format. + + An element with the given index in each array describes one + property. Thus, the number of elements in each returned array is the + same and corresponds to the number of supported properties. + + The returned arrays are filled in only if the + <link to="MediumFormatCapabilities_Properties"/> flag is set. + All arguments must be non-@c null. + + <see><link to="DataType"/>, <link to="DataFlags"/></see> + </desc> + + <param name="names" type="wstring" safearray="yes" dir="out"> + <desc>Array of property names.</desc> + </param> + <param name="descriptions" type="wstring" safearray="yes" dir="out"> + <desc>Array of property descriptions.</desc> + </param> + <param name="types" type="DataType" safearray="yes" dir="out"> + <desc>Array of property types.</desc> + </param> + <param name="flags" type="unsigned long" safearray="yes" dir="out"> + <desc>Array of property flags.</desc> + </param> + <param name="defaults" type="wstring" safearray="yes" dir="out"> + <desc>Array of default property values.</desc> + </param> + </method> + + </interface> + + <!-- + // IDataStream + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IDataStream" extends="$unknown" + uuid="a338ed20-58d9-43ae-8b03-c1fd7088ef15" + wsmap="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + The IDataStream interface is used to retrieve a data stream. It is + returned by <link to="IMediumIO::convertToStream"/>. + </desc> + + <attribute name="readSize" type="unsigned long" readonly="yes"> + <desc>Recommended size of a read. Requesting a larger read may be + possible in certain situations, but it is not guaranteed.</desc> + </attribute> + + <method name="read"> + <desc> + Read data from the stream. + <result name="VBOX_E_TIMEOUT"> + Waiting time has expired. + </result> + </desc> + <param name="size" type="unsigned long" dir="in"> + <desc>How many bytes to try read.</desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) for limiting the wait time for data to be available. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="data" type="octet" dir="return" safearray="yes"> + <desc>Array of data read. This may be shorter than the specified size. + Returning a zero-sized array indicates the end of the stream, if the + status is successful.</desc> + </param> + </method> + + </interface> + + <!-- + // IMediumIO + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="PartitionTableType" + uuid="360066eb-d19e-4fa1-57ef-fed434fbe2a9" + > + <desc> + Partition table types. + </desc> + + <const name="MBR" value="1"/> + <const name="GPT" value="2"/> + </enum> + + + <interface + name="IMediumIO" extends="$unknown" + uuid="e4b301a9-5f86-4d65-ad1b-87ca284fb1c8" + wsmap="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + The IMediumIO interface is used to access and modify the content of a + medium. It is returned by <link to="IMedium::openForIO"/>. + </desc> + + <attribute name="medium" type="IMedium" readonly="yes"> + <desc>The open medium.</desc> + </attribute> + + <attribute name="writable" type="boolean" readonly="yes"> + <desc>Whether the medium can be written to. (It can always be read from.)</desc> + </attribute> + + <attribute name="explorer" type="IVFSExplorer" readonly="yes"> + <desc> + Returns the virtual file system explorer for the medium. + + This will attempt to recognize the format of the medium content and + present it as a virtual directory structure to the API user. + + A FAT floppy image will be represented will a single root subdir 'fat12' + that gives access to the file system content. + + A ISO-9660 image will have one subdir in the root for each format present + in the image, so the API user can select which data view to access (iso9660, + rockridge, joliet, udf, hfs, ...). + + A partitioned harddisk image will have subdirs for each partition. The + the filesystem content of each partition can be accessed thru the subdirs + if we have a file system interpreter for it. There will also be raw files + for each subdirectory, to provide a simple way of accessing raw partition + data from an API client. + + Please note that the explorer may show inconsistent information if + the API user modifies the raw image content after it was opened. + </desc> + </attribute> + + <method name="read"> + <desc> + Read data from the medium. + </desc> + <param name="offset" type="long long" dir="in"> + <desc>The byte offset into the medium to start reading at.</desc> + </param> + <param name="size" type="unsigned long" dir="in"> + <desc>How many bytes to try read.</desc> + </param> + <param name="data" type="octet" dir="return" safearray="yes"> + <desc>Array of data read. This may be shorter than the specified size.</desc> + </param> + </method> + + <method name="write"> + <desc> + Write data to the medium. + </desc> + <param name="offset" type="long long" dir="in"> + <desc>The byte offset into the medium to start reading at.</desc> + </param> + <param name="data" type="octet" dir="in" safearray="yes"> + <desc>Array of data to write.</desc> + </param> + <param name="written" type="unsigned long" dir="return"> + <desc>How many bytes were actually written.</desc> + </param> + </method> + + <method name="formatFAT"> + <desc> + Formats the medium as FAT. Generally only useful for floppy images as + no partition table will be created. + </desc> + <param name="quick" type="boolean" dir="in"> + <desc>Quick format it when set.</desc> + </param> + </method> + + <method name="initializePartitionTable"> + <desc> + Writes an empty partition table to the disk. + </desc> + <param name="format" type="PartitionTableType" dir="in"> + <desc>The partition table format.</desc> + </param> + <param name="wholeDiskInOneEntry" type="boolean" dir="in"> + <desc> + When @c true a partition table entry for the whole disk is created. + Otherwise the partition table is empty. + </desc> + </param> + </method> + + <method name="convertToStream"> + <desc> + Converts the currently opened image into a stream of the specified + image type/variant. It is sufficient to open the image in read-only + mode. Only few types and variants are supported due to the inherent + restrictions of the output style. + <result name="VBOX_E_NOT_SUPPORTED"> + The requested format/variant combination cannot handle stream output. + </result> + <result name="VBOX_E_FILE_ERROR"> + An error occurred during the conversion. + </result> + </desc> + <param name="format" type="wstring" dir="in"> + <desc>Identifier of the storage format to use for output.</desc> + </param> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> + <desc>The partition table format.</desc> + </param> + <param name="bufferSize" type="unsigned long" dir="in"> + <desc> + Requested buffer size (in bytes) for efficient conversion. Sizes + which are too small or too large are silently truncated to suitable + values. Tens to hundreds of Megabytes are a good choice. + </desc> + </param> + <param name="stream" type="IDataStream" dir="out"> + <desc>Data stream object for reading the target image.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="close"> + <desc> + Explictly close the medium I/O rather than waiting for garbage + collection and the destructor. + + This will wait for any pending reads and writes to complete and then + close down the I/O access without regard for open explorer instances or + anything like that. + </desc> + </method> + + </interface> + + + <!-- + // IToken + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IToken" extends="$unknown" + uuid="20479eaf-d8ed-44cf-85ac-c83a26c95a4d" + wsmap="managed" + rest="managed" + reservedMethods="1" reservedAttributes="2" + > + <desc> + The IToken interface represents a token passed to an API client, which + triggers cleanup actions when it is explicitly released by calling the + <link to="#abandon"/> method (preferred, as it is accurately defined + when the release happens), or when the object reference count drops + to 0. The latter way is implicitly used when an API client crashes, + however the discovery that there was a crash can take rather long, + depending on the platform (COM needs 6 minutes). So better don't rely + on the crash behavior too much. + </desc> + + <method name="abandon" wrap-hint-server="passcaller"> + <desc>Releases this token. Cannot be undone in any way, and makes the + token object unusable (even the <link to="#dummy"/> method will return + an error), ready for releasing. It is a more defined way than just + letting the reference count drop to 0, because the latter (depending + on the platform) can trigger asynchronous cleanup activity. + </desc> + </method> + + <method name="dummy"> + <desc>Purely a NOOP. Useful when using proxy type API bindings (e.g. the + webservice) which manage objects on behalf of the actual client, using + an object reference expiration time based garbage collector. + </desc> + </method> + + </interface> + + + <!-- + // IKeyboard + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="KeyboardLED" + uuid="ef29ea38-409b-49c7-a817-c858d426dfba" + > + <desc> + Keyboard LED indicators. + </desc> + + <const name="NumLock" value="0x01"/> + <const name="CapsLock" value="0x02"/> + <const name="ScrollLock" value="0x04"/> + </enum> + + <interface + name="IKeyboard" extends="$unknown" + uuid="755e6bdf-1640-41f9-bd74-3ef5fd653250" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="4" + > + <desc> + The IKeyboard interface represents the virtual machine's keyboard. Used + in <link to="IConsole::keyboard"/>. + + Use this interface to send keystrokes or the Ctrl-Alt-Del sequence + to the virtual machine. + </desc> + + <attribute name="keyboardLEDs" type="KeyboardLED" safearray="yes" readonly="yes"> + <desc> + Current status of the guest keyboard LEDs. + </desc> + </attribute> + + <method name="putScancode"> + <desc>Sends a scancode to the keyboard. + + <result name="VBOX_E_IPRT_ERROR"> + Could not send scan code to virtual keyboard. + </result> + + </desc> + <param name="scancode" type="long" dir="in"/> + </method> + + <method name="putScancodes"> + <desc>Sends an array of scancodes to the keyboard. + + <result name="VBOX_E_IPRT_ERROR"> + Could not send all scan codes to virtual keyboard. + </result> + + </desc> + <param name="scancodes" type="long" dir="in" safearray="yes"/> + <param name="codesStored" type="unsigned long" dir="return"/> + </method> + + <method name="putCAD"> + <desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This + function is nothing special, it is just a convenience function + calling <link to="IKeyboard::putScancodes"/> with the proper scancodes. + + <result name="VBOX_E_IPRT_ERROR"> + Could not send all scan codes to virtual keyboard. + </result> + + </desc> + </method> + + <method name="releaseKeys"> + <desc>Causes the virtual keyboard to release any keys which are + currently pressed. Useful when host and guest keyboard may be out + of sync. + + <result name="VBOX_E_IPRT_ERROR"> + Could not release some or all keys. + </result> + + </desc> + </method> + + <method name="putUsageCode"> + <desc>Sends a USB HID usage code and page to the keyboard. The + keyRelease flag is set when the key is being released. + + <result name="VBOX_E_IPRT_ERROR"> + Could not send usage code to virtual keyboard. + </result> + + </desc> + <param name="usageCode" type="long" dir="in"/> + <param name="usagePage" type="long" dir="in"/> + <param name="keyRelease" type="boolean" dir="in"/> + </method> + + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for keyboard events. + </desc> + </attribute> + + </interface> + + + <!-- + // IMouse + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="MouseButtonState" + uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8" + > + <desc> + Mouse button state. + </desc> + + <const name="LeftButton" value="0x01"/> + <const name="RightButton" value="0x02"/> + <const name="MiddleButton" value="0x04"/> + <const name="WheelUp" value="0x08"/> + <const name="WheelDown" value="0x10"/> + <const name="XButton1" value="0x20"/> + <const name="XButton2" value="0x40"/> + <const name="MouseStateMask" value="0x7F"/> + </enum> + + <enum + name="TouchContactState" + uuid="3f942686-2506-421c-927c-90d4b45f4a38" + > + <desc> + Touch event contact state. + </desc> + + <const name="None" value="0x00"> + <desc>The touch has finished.</desc> + </const> + <const name="InContact" value="0x01"> + <desc>Whether the touch is really touching the device.</desc> + </const> + <const name="InRange" value="0x02"> + <desc> + Whether the touch is close enough to the device to be detected. + </desc> + </const> + <const name="ContactStateMask" value="0x03"/> + </enum> + + <interface + name="IMousePointerShape" extends="$unknown" + uuid="1e775ea3-9070-4f9c-b0d5-53054496dbe0" + wsmap="managed" + rest="managed" + reservedAttributes="4" + > + <desc> + The guest mouse pointer description. + </desc> + + <attribute name="visible" type="boolean" readonly="yes"> + <desc> + Flag whether the pointer is visible. + </desc> + </attribute> + <attribute name="alpha" type="boolean" readonly="yes"> + <desc> + Flag whether the pointer has an alpha channel. + </desc> + </attribute> + <attribute name="hotX" type="unsigned long" readonly="yes"> + <desc> + The pointer hot spot X coordinate. + </desc> + </attribute> + <attribute name="hotY" type="unsigned long" readonly="yes"> + <desc> + The pointer hot spot Y coordinate. + </desc> + </attribute> + <attribute name="width" type="unsigned long" readonly="yes"> + <desc> + Width of the pointer shape in pixels. + </desc> + </attribute> + <attribute name="height" type="unsigned long" readonly="yes"> + <desc> + Height of the pointer shape in pixels. + </desc> + </attribute> + <attribute name="shape" type="octet" safearray="yes" readonly="yes"> + <desc> + Shape bitmaps. + + The @a shape buffer contains a 1bpp (bits per pixel) AND mask + followed by a 32bpp XOR (color) mask. + + For pointers without alpha channel the XOR mask pixels are + 32 bit values: (lsb)BGR0(msb). For pointers with alpha channel + the XOR mask consists of (lsb)BGRA(msb) 32 bit values. + + An AND mask is provided for pointers with alpha channel, so if the + client does not support alpha, the pointer could be + displayed as a normal color pointer. + + The AND mask is a 1bpp bitmap with byte aligned scanlines. The + size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 * + height</tt>. The padding bits at the end of each scanline are + undefined. + + The XOR mask follows the AND mask on the next 4-byte aligned + offset: <tt>uint8_t *pu8Xor = pu8And + (cbAnd + 3) & ~3</tt>. + Bytes in the gap between the AND and the XOR mask are undefined. + The XOR mask scanlines have no gap between them and the size of + the XOR mask is: <tt>cbXor = width * 4 * height</tt>. + + <note> + If @a shape size is 0, then the shape is not known or did not change. + This can happen if only the pointer visibility is changed. + </note> + </desc> + </attribute> + </interface> + + <interface + name="IMouse" extends="$unknown" + uuid="25360a74-55e5-4f14-ac2a-f5cf8e62e4af" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="4" + > + <desc> + The IMouse interface represents the virtual machine's mouse. Used in + <link to="IConsole::mouse"/>. + + Through this interface, the virtual machine's virtual mouse can be + controlled. + </desc> + + <attribute name="absoluteSupported" type="boolean" readonly="yes"> + <desc> + Whether the guest OS supports absolute mouse pointer positioning + or not. + <note> + You can use the <link to="IMouseCapabilityChangedEvent"/> + event to be instantly informed about changes of this attribute + during virtual machine execution. + </note> + <see><link to="#putMouseEventAbsolute"/></see> + </desc> + </attribute> + + <attribute name="relativeSupported" type="boolean" readonly="yes"> + <desc> + Whether the guest OS supports relative mouse pointer positioning + or not. + <note> + You can use the <link to="IMouseCapabilityChangedEvent"/> + event to be instantly informed about changes of this attribute + during virtual machine execution. + </note> + <see><link to="#putMouseEvent"/></see> + </desc> + </attribute> + + <attribute name="touchScreenSupported" type="boolean" readonly="yes"> + <desc> + Whether the guest OS has enabled the multi-touch reporting device, + touchscreen variant. + <note> + You can use the <link to="IMouseCapabilityChangedEvent"/> + event to be instantly informed about changes of this attribute + during virtual machine execution. + </note> + <see><link to="#putMouseEvent"/></see> + </desc> + </attribute> + + <attribute name="touchPadSupported" type="boolean" readonly="yes"> + <desc> + Whether the guest OS has enabled the multi-touch reporting device, + touchpad variant. + <note> + You can use the <link to="IMouseCapabilityChangedEvent"/> + event to be instantly informed about changes of this attribute + during virtual machine execution. + </note> + <see><link to="#putMouseEvent"/></see> + </desc> + </attribute> + + <attribute name="needsHostCursor" type="boolean" readonly="yes"> + <desc> + Whether the guest OS can currently switch to drawing it's own mouse + cursor on demand. + <note> + You can use the <link to="IMouseCapabilityChangedEvent"/> + event to be instantly informed about changes of this attribute + during virtual machine execution. + </note> + <see><link to="#putMouseEvent"/></see> + </desc> + </attribute> + + <attribute name="pointerShape" type="IMousePointerShape" readonly="yes"> + <desc> + The current mouse pointer used by the guest. + </desc> + </attribute> + + <method name="putMouseEvent"> + <desc> + Initiates a mouse event using relative pointer movements + along x and y axis. + + <result name="E_ACCESSDENIED"> + Console not powered up. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Could not send mouse event to virtual mouse. + </result> + + </desc> + + <param name="dx" type="long" dir="in"> + <desc> + Amount of pixels the mouse should move to the right. + Negative values move the mouse to the left. + </desc> + </param> + <param name="dy" type="long" dir="in"> + <desc> + Amount of pixels the mouse should move downwards. + Negative values move the mouse upwards. + </desc> + </param> + <param name="dz" type="long" dir="in"> + <desc> + Amount of mouse wheel moves. + Positive values describe clockwise wheel rotations, + negative values describe counterclockwise rotations. + </desc> + </param> + <param name="dw" type="long" dir="in"> + <desc> + Amount of horizontal mouse wheel moves. + Positive values describe a movement to the left, + negative values describe a movement to the right. + </desc> + </param> + <param name="buttonState" type="long" dir="in"> + <desc> + The current state of mouse buttons. Every bit represents + a mouse button as follows: + <dl> + <dt>Bit 0 (<tt>0x01</tt>)</dt><dd>left mouse button</dd> + <dt>Bit 1 (<tt>0x02</tt>)</dt><dd>right mouse button</dd> + <dt>Bit 2 (<tt>0x04</tt>)</dt><dd>middle mouse button</dd> + </dl> + A value of @c 1 means the corresponding button is pressed. + otherwise it is released. + </desc> + </param> + </method> + + <method name="putMouseEventAbsolute"> + <desc> + Positions the mouse pointer using absolute x and y coordinates. + These coordinates are expressed in pixels and + start from <tt>[1,1]</tt> which corresponds to the top left + corner of the virtual display. The values <tt>[-1,-1]</tt> and + <tt>[0x7fffffff,0x7fffffff]</tt> have special meanings as + respectively "no data" (to signal that the host wishes to report + absolute pointer data in future) and "out of range" (the host + pointer is outside of all guest windows). + + <result name="E_ACCESSDENIED"> + Console not powered up. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Could not send mouse event to virtual mouse. + </result> + + <note> + This method will have effect only if absolute mouse + positioning is supported by the guest OS. + </note> + + <see><link to="#absoluteSupported"/></see> + </desc> + + <param name="x" type="long" dir="in"> + <desc> + X coordinate of the pointer in pixels, starting from @c 1. + </desc> + </param> + <param name="y" type="long" dir="in"> + <desc> + Y coordinate of the pointer in pixels, starting from @c 1. + </desc> + </param> + <param name="dz" type="long" dir="in"> + <desc> + Amount of mouse wheel moves. + Positive values describe clockwise wheel rotations, + negative values describe counterclockwise rotations. + </desc> + </param> + <param name="dw" type="long" dir="in"> + <desc> + Amount of horizontal mouse wheel moves. + Positive values describe a movement to the left, + negative values describe a movement to the right. + </desc> + </param> + <param name="buttonState" type="long" dir="in"> + <desc> + The current state of mouse buttons. Every bit represents + a mouse button as follows: + <dl> + <dt>Bit 0 (<tt>0x01</tt>)</dt><dd>left mouse button</dd> + <dt>Bit 1 (<tt>0x02</tt>)</dt><dd>right mouse button</dd> + <dt>Bit 2 (<tt>0x04</tt>)</dt><dd>middle mouse button</dd> + </dl> + A value of @c 1 means the corresponding button is pressed. + otherwise it is released. + </desc> + </param> + </method> + + <method name="putEventMultiTouch"> + <desc> + Sends a multi-touch pointer event. For touchscreen events the + coordinates are expressed in pixels and start from <tt>[1,1]</tt> which + corresponds to the top left corner of the virtual display, for + touchpad events the coordinates are normalized to the range 0..0xffff. + + <result name="E_ACCESSDENIED"> + Console not powered up. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Could not send event to virtual device. + </result> + + <note> + The guest may not understand or may choose to ignore this event. + </note> + + <see><link to="#touchScreenSupported"/> and <link to="#touchPadSupported"/></see> + </desc> + + <param name="count" type="long" dir="in"> + <desc> + Number of contacts in the event. + </desc> + </param> + + <param name="contacts" type="long long" dir="in" safearray="yes"> + <desc> + Each array element contains packed information about one contact. + Bits 0..15: X coordinate in pixels or normalized X position. + Bits 16..31: Y coordinate in pixels or normalized Y position. + Bits 32..39: contact identifier. + Bit 40: "in contact" flag, which indicates that there is a contact with the touch surface. + Bit 41: "in range" flag, the contact is close enough to the touch surface. + All other bits are reserved for future use and must be set to 0. + </desc> + </param> + + <param name="isTouchScreen" type="boolean" dir="in"> + <desc> + Distinguishes between touchscreen and touchpad events. + </desc> + </param> + + <param name="scanTime" type="unsigned long" dir="in"> + <desc> + Timestamp of the event in milliseconds. Only relative time between events is important. + </desc> + </param> + </method> + + <method name="putEventMultiTouchString"> + <desc> + <see><link to="#putEventMultiTouch"/></see> + </desc> + + <param name="count" type="long" dir="in"> + <desc> + <see><link to="#putEventMultiTouch"/></see> + </desc> + </param> + + <param name="contacts" type="wstring" dir="in"> + <desc> + Contains information about all contacts: + "id1,x1,y1,inContact1,inRange1;...;idN,xN,yN,inContactN,inRangeN". + For example for two contacts: "0,10,20,1,1;1,30,40,1,1" + </desc> + </param> + + <param name="isTouchScreen" type="boolean" dir="in"> + <desc> + Distinguishes between touchscreen and touchpad events. + </desc> + </param> + + <param name="scanTime" type="unsigned long" dir="in"> + <desc> + <see><link to="#putEventMultiTouch"/></see> + </desc> + </param> + </method> + + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for mouse events. + </desc> + </attribute> + + </interface> + + <!-- + // IDisplay + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IDisplaySourceBitmap" extends="$unknown" + uuid="5094f67a-8084-11e9-b185-dbe296e54799" + wsmap="suppress" + rest="managed" + > + <attribute name="screenId" type="unsigned long" readonly="yes"/> + <method name="queryBitmapInfo"> + <desc>Information about the screen bitmap.</desc> + <param name="address" type="octet" mod="ptr" dir="out"/> + <param name="width" type="unsigned long" dir="out"/> + <param name="height" type="unsigned long" dir="out"/> + <param name="bitsPerPixel" type="unsigned long" dir="out"/> + <param name="bytesPerLine" type="unsigned long" dir="out"/> + <param name="bitmapFormat" type="BitmapFormat" dir="out"/> + </method> + + </interface> + + <enum + name="FramebufferCapabilities" + uuid="cc395839-30fa-4ca5-ae65-e6360e3edd7a" + > + <desc> + Framebuffer capability flags. + </desc> + + <const name="UpdateImage" value="0x01"> + <desc> + Requires NotifyUpdateImage. NotifyUpdate must not be called. + </desc> + </const> + + <const name="VHWA" value="0x02"> + <desc> + Supports VHWA interface. If set, then + IFramebuffer::processVHWACommand can be called. <!-- no link, otherwise trouble with javadoc --> + </desc> + </const> + + <const name="VisibleRegion" value="0x04"> + <desc> + Supports visible region. If set, then + IFramebuffer::setVisibleRegion can be called. <!-- no link, otherwise trouble with javadoc --> + </desc> + </const> + + <const name="RenderCursor" value="0x08"> + <desc> + This framebuffer implementation can render a pointer cursor itself. Unless the + MoveCursor capability is also set the cursor will always be rendered at the + location of (and usually using) the host pointer. + </desc> + </const> + + <const name="MoveCursor" value="0x10"> + <desc> + Supports rendering a pointer cursor anywhere within the guest screen. Implies + RenderCursor. + </desc> + </const> + </enum> + + <interface + name="IFramebuffer" extends="$unknown" + uuid="1e8d3f27-b45c-48ae-8b36-d35e83d207aa" + wsmap="managed" + > + <attribute name="width" type="unsigned long" readonly="yes"> + <desc>Frame buffer width, in pixels.</desc> + </attribute> + + <attribute name="height" type="unsigned long" readonly="yes"> + <desc>Frame buffer height, in pixels.</desc> + </attribute> + + <attribute name="bitsPerPixel" type="unsigned long" readonly="yes"> + <desc> + Color depth, in bits per pixel. + </desc> + </attribute> + + <attribute name="bytesPerLine" type="unsigned long" readonly="yes"> + <desc> + Scan line size, in bytes. + </desc> + </attribute> + + <attribute name="pixelFormat" type="BitmapFormat" readonly="yes"> + <desc> + Frame buffer pixel format. It's one of the values defined by <link + to="BitmapFormat"/>. + <note> + This attribute must never (and will never) return <link + to="BitmapFormat_Opaque"/> -- the format of the frame + buffer must be always known. + </note> + </desc> + </attribute> + + <attribute name="heightReduction" type="unsigned long" readonly="yes"> + <desc> + Hint from the frame buffer about how much of the standard + screen height it wants to use for itself. This information is + exposed to the guest through the VESA BIOS and VMMDev interface + so that it can use it for determining its video mode table. It + is not guaranteed that the guest respects the value. + </desc> + </attribute> + + <attribute name="overlay" type="IFramebufferOverlay" readonly="yes"> + <desc> + An alpha-blended overlay which is superposed over the frame buffer. + The initial purpose is to allow the display of icons providing + information about the VM state, including disk activity, in front + ends which do not have other means of doing that. The overlay is + designed to controlled exclusively by IDisplay. It has no locking + of its own, and any changes made to it are not guaranteed to be + visible until the affected portion of IFramebuffer is updated. The + overlay can be created lazily the first time it is requested. This + attribute can also return @c null to signal that the overlay is not + implemented. + </desc> + </attribute> + + <attribute name="winId" type="long long" readonly="yes" wsmap="suppress"> + <desc> + Platform-dependent identifier of the window where context of this + frame buffer is drawn, or zero if there's no such window. + </desc> + </attribute> + + <attribute name="capabilities" type="FramebufferCapabilities" safearray="yes" readonly="yes"> + <desc> + Capabilities of the framebuffer instance. + + For the meaning of individual capability flags see + <link to="FramebufferCapabilities"/>. + </desc> + </attribute> + + <method name="notifyUpdate"> + <desc> + Informs about an update. + Gets called by the display object where this buffer is + registered. + </desc> + <param name="x" type="unsigned long" dir="in"> + <desc>X position of update.</desc> + </param> + <param name="y" type="unsigned long" dir="in"> + <desc>Y position of update.</desc> + </param> + <param name="width" type="unsigned long" dir="in"> + <desc>Width of update.</desc> + </param> + <param name="height" type="unsigned long" dir="in"> + <desc>Height of update.</desc> + </param> + </method> + + <method name="notifyUpdateImage"> + <desc> + Informs about an update and provides 32bpp bitmap. + </desc> + <param name="x" type="unsigned long" dir="in"> + <desc>X position of update.</desc> + </param> + <param name="y" type="unsigned long" dir="in"> + <desc>Y position of update.</desc> + </param> + <param name="width" type="unsigned long" dir="in"> + <desc>Width of update.</desc> + </param> + <param name="height" type="unsigned long" dir="in"> + <desc>Height of update.</desc> + </param> + <param name="image" type="octet" dir="in" safearray="yes"> + <desc>Array with 32BPP image data.</desc> + </param> + </method> + + <method name="notifyChange"> + <desc> + Requests a size change. + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc> + Logical guest screen number. + </desc> + </param> + <param name="xOrigin" type="unsigned long" dir="in"> + <desc>Location of the screen in the guest.</desc> + </param> + <param name="yOrigin" type="unsigned long" dir="in"> + <desc>Location of the screen in the guest.</desc> + </param> + <param name="width" type="unsigned long" dir="in"> + <desc>Width of the guest display, in pixels.</desc> + </param> + <param name="height" type="unsigned long" dir="in"> + <desc>Height of the guest display, in pixels.</desc> + </param> + </method> + + <method name="videoModeSupported"> + <desc> + Returns whether the frame buffer implementation is willing to + support a given video mode. In case it is not able to render + the video mode (or for some reason not willing), it should + return @c false. Usually this method is called when the guest + asks the VMM device whether a given video mode is supported + so the information returned is directly exposed to the guest. + It is important that this method returns very quickly. + </desc> + <param name="width" type="unsigned long" dir="in"/> + <param name="height" type="unsigned long" dir="in"/> + <param name="bpp" type="unsigned long" dir="in"/> + <param name="supported" type="boolean" dir="return"/> + </method> + + <method name="getVisibleRegion" wsmap="suppress"> + <desc> + Returns the visible region of this frame buffer. + + If the @a rectangles parameter is @c null then the value of the + @a count parameter is ignored and the number of elements necessary to + describe the current visible region is returned in @a countCopied. + + If @a rectangles is not @c null but @a count is less + than the required number of elements to store region data, the method + will report a failure. If @a count is equal or greater than the + required number of elements, then the actual number of elements copied + to the provided array will be returned in @a countCopied. + + <note> + The address of the provided array must be in the process space of + this IFramebuffer object. + </note> + <note> + Method not yet implemented. + </note> + </desc> + <param name="rectangles" type="octet" mod="ptr" dir="in"> + <desc>Pointer to the @c RTRECT array to receive region data.</desc> + </param> + <param name="count" type="unsigned long" dir="in"> + <desc>Number of @c RTRECT elements in the @a rectangles array.</desc> + </param> + <param name="countCopied" type="unsigned long" dir="return"> + <desc>Number of elements copied to the @a rectangles array.</desc> + </param> + </method> + + <method name="setVisibleRegion" wsmap="suppress"> + <desc> + Suggests a new visible region to this frame buffer. This region + represents the area of the VM display which is a union of regions of + all top-level windows of the guest operating system running inside the + VM (if the Guest Additions for this system support this + functionality). This information may be used by the frontends to + implement the seamless desktop integration feature. + + <note> + The address of the provided array must be in the process space of + this IFramebuffer object. + </note> + <note> + The IFramebuffer implementation must make a copy of the provided + array of rectangles. + </note> + <note> + Method not yet implemented. + </note> + </desc> + <param name="rectangles" type="octet" mod="ptr" dir="in"> + <desc>Pointer to the @c RTRECT array.</desc> + </param> + <param name="count" type="unsigned long" dir="in"> + <desc>Number of @c RTRECT elements in the @a rectangles array.</desc> + </param> + </method> + + <method name="processVHWACommand" wsmap="suppress"> + <desc> + Posts a Video HW Acceleration Command to the frame buffer for processing. + The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color conversion, overlaying, etc.) + are posted from quest to the host to be processed by the host hardware. + + <note> + The address of the provided command must be in the process space of + this IFramebuffer object. + </note> + </desc> + + <param name="command" type="octet" mod="ptr" dir="in"> + <desc>Pointer to VBOXVHWACMD containing the command to execute.</desc> + </param> + <param name="enmCmd" type="long" dir="in"> + <desc>The validated VBOXVHWACMD::enmCmd value from the command.</desc> + </param> + <param name="fromGuest" type="boolean" dir="in"> + <desc>Set when the command origins from the guest, clear if host.</desc> + </param> + </method> + + <method name="notify3DEvent"> + <desc> + Notifies framebuffer about 3D backend event. + </desc> + + <param name="type" type="unsigned long" dir="in"> + <desc>event type. VBOX3D_NOTIFY_TYPE_* in VBoxVideo3D.h</desc> + </param> + <param name="data" type="octet" dir="in" safearray="yes"> + <desc>event-specific data, depends on the supplied event type</desc> + </param> + </method> + + </interface> + + <interface + name="IFramebufferOverlay" extends="IFramebuffer" + uuid="af398a9a-6b76-4805-8fab-00a9dcf4732b" + wsmap="managed" + > + <desc> + The IFramebufferOverlay interface represents an alpha blended overlay + for displaying status icons above an IFramebuffer. It is always created + not visible, so that it must be explicitly shown. It only covers a + portion of the IFramebuffer, determined by its width, height and + co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in + that order) format, and may be written to directly. Do re-read the + width though, after setting it, as it may be adjusted (increased) to + make it more suitable for the front end. + </desc> + <attribute name="x" type="unsigned long" readonly="yes"> + <desc>X position of the overlay, relative to the frame buffer.</desc> + </attribute> + + <attribute name="y" type="unsigned long" readonly="yes"> + <desc>Y position of the overlay, relative to the frame buffer.</desc> + </attribute> + + <attribute name="visible" type="boolean"> + <desc> + Whether the overlay is currently visible. + </desc> + </attribute> + + <attribute name="alpha" type="unsigned long"> + <desc> + The global alpha value for the overlay. This may or may not be + supported by a given front end. + </desc> + </attribute> + + <method name="move"> + <desc> + Changes the overlay's position relative to the IFramebuffer. + </desc> + <param name="x" type="unsigned long" dir="in"/> + <param name="y" type="unsigned long" dir="in"/> + </method> + + </interface> + + <enum + name="GuestMonitorStatus" + uuid="6b8d3f71-39cb-459e-a916-48917ed43e19" + > + <desc> + The current status of the guest display. + </desc> + + <const name="Disabled" value="0"> + <desc> + The guest monitor is disabled in the guest. + </desc> + </const> + + <const name="Enabled" value="1"> + <desc> + The guest monitor is enabled in the guest. + </desc> + </const> + + <const name="Blank" value="2"> + <desc> + The guest monitor is enabled in the guest but should display nothing. + </desc> + </const> + </enum> + + <enum + name="ScreenLayoutMode" + uuid="8fa1964c-8774-11e9-ae5d-1f419105e68d" + > + <desc> + How <link to="IDisplay::setScreenLayout"/> method should work. + </desc> + + <const name="Apply" value="0"> + <desc> + If the guest is already at desired mode then the API might avoid setting the mode. + </desc> + </const> + + <const name="Reset" value="1"> + <desc> + Always set the new mode even if the guest is already at desired mode. + </desc> + </const> + + <const name="Attach" value="2"> + <desc> + Attach new screens and always set the new mode for existing screens. + </desc> + </const> + + <const name="Silent" value="3"> + <desc> + Do not notify the guest of the change. Normally this is wished, but it + might not be when re-setting monitor information from the last session + (no hotplug happened, as it is still the same virtual monitor). + </desc> + </const> + </enum> + + <interface + name="IGuestScreenInfo" extends="$unknown" + uuid="6b2f98f8-9641-4397-854a-040439d0114b" + wsmap="managed" + > + <attribute name="screenId" type="unsigned long" readonly="yes"/> + <attribute name="guestMonitorStatus" type="GuestMonitorStatus" readonly="yes"/> + <attribute name="primary" type="boolean" readonly="yes"/> + <attribute name="origin" type="boolean" readonly="yes"/> + <attribute name="originX" type="long" readonly="yes"/> + <attribute name="originY" type="long" readonly="yes"/> + <attribute name="width" type="unsigned long" readonly="yes"/> + <attribute name="height" type="unsigned long" readonly="yes"/> + <attribute name="bitsPerPixel" type="unsigned long" readonly="yes"/> + <attribute name="extendedInfo" type="wstring" readonly="yes"/> + </interface> + + <interface + name="IDisplay" extends="$unknown" + uuid="4680b2de-8690-11e9-b83d-5719e53cf1de" + wsmap="managed" + wrap-hint-server-addinterfaces="IEventListener" + reservedMethods="8" reservedAttributes="16" + > + <desc> + The IDisplay interface represents the virtual machine's display. + + The object implementing this interface is contained in each + <link to="IConsole::display"/> attribute and represents the visual + output of the virtual machine. + + The virtual display supports pluggable output targets represented by the + IFramebuffer interface. Examples of the output target are a window on + the host computer or an RDP session's display on a remote computer. + </desc> + + <attribute name="guestScreenLayout" type="IGuestScreenInfo" safearray="yes" readonly="yes"> + <desc> + Layout of the guest screens. + </desc> + </attribute> + + <method name="getScreenResolution"> + <desc> + Queries certain attributes such as display width, height, color depth + and the X and Y origin for a given guest screen. + + The parameters @a xOrigin and @a yOrigin return the X and Y + coordinates of the framebuffer's origin. + + All return parameters are optional.</desc> + <param name="screenId" type="unsigned long" dir="in"/> + <param name="width" type="unsigned long" dir="out"/> + <param name="height" type="unsigned long" dir="out"/> + <param name="bitsPerPixel" type="unsigned long" dir="out"/> + <param name="xOrigin" type="long" dir="out"/> + <param name="yOrigin" type="long" dir="out"/> + <param name="guestMonitorStatus" type="GuestMonitorStatus" dir="out"/> + </method> + + <method name="attachFramebuffer"> + <desc> + Sets the graphics update target for a screen. + </desc> + <param name="screenId" type="unsigned long" dir="in"/> + <param name="framebuffer" type="IFramebuffer" dir="in"/> + <param name="id" type="uuid" mod="string" dir="return"/> + </method> + + <method name="detachFramebuffer"> + <desc> + Removes the graphics updates target for a screen. + </desc> + <param name="screenId" type="unsigned long" dir="in"/> + <param name="id" type="uuid" mod="string" dir="in"/> + </method> + + <method name="queryFramebuffer"> + <desc> + Queries the graphics updates targets for a screen. + </desc> + <param name="screenId" type="unsigned long" dir="in"/> + <param name="framebuffer" type="IFramebuffer" dir="return"/> + </method> + + <method name="setVideoModeHint"> + <desc> + Changes the monitor information reported by a given output of the guest + graphics device. This information can be read by the guest if suitable + drivers and driver tools are available, including but not limited to + those in the Guest Additions. The guest will receive monitor hotplug + notification when the monitor information is changed, and the + information itself will be available to the guest until the next change. + The information should not be resent if the guest does not resize in + response. The guest might have chosen to ignore the change, or the + resize might happen later when a suitable driver is started. + + Specifying @c 0 for either @a width, @a height or @a bitsPerPixel + parameters means that the corresponding values should be taken from the + current video mode (i.e. left unchanged). + + @todo Rename this to @a setMonitorInfo for 7.0. + + <result name="E_INVALIDARG"> + The @a display value is higher then the number of outputs. + </result> + + </desc> + <param name="display" type="unsigned long" dir="in"> + <desc> + The number of the guest output to change. + </desc> + </param> + <param name="enabled" type="boolean" dir="in"> + <desc> + @c True if a monitor is connected, + @c False otherwise. + <note internal="yes">For historical reasons the Windows drivers can + and do override this setting. Call this a virtual hardware quirk. + </note> + </desc> + </param> + <param name="changeOrigin" type="boolean" dir="in"> + <desc> + @c True, if the position of the guest screen is specified, + @c False otherwise. + </desc> + </param> + <param name="originX" type="long" dir="in"> + <desc> + The X origin of the guest screen. + </desc> + </param> + <param name="originY" type="long" dir="in"> + <desc> + The Y origin of the guest screen. + </desc> + </param> + <param name="width" type="unsigned long" dir="in"> + <desc> + The width of the guest screen. + </desc> + </param> + <param name="height" type="unsigned long" dir="in"> + <desc> + The height of the guest screen. + </desc> + </param> + <param name="bitsPerPixel" type="unsigned long" dir="in"> + <desc> + The number of bits per pixel of the guest screen. + </desc> + </param> + <param name="notify" type="boolean" dir="in"> + <desc> + Whether the guest should be notified of the change. Normally this + is wished, but it might not be when re-setting monitor information + from the last session (no hotplug happened, as it is still the same + virtual monitor). Might also be useful if several monitors are to be + changed at once, but this would not reflect physical hardware well, + and we also have @a setScreenLayout for that. + </desc> + </param> + </method> + + <method name="getVideoModeHint"> + <desc> + Queries the monitor information for a given guest output. See + @a setVideoModeHint. If no monitor information has been set yet by a + front-end the preferred mode values returned will be zero. + + @todo Rename this to @a getMonitorInfo for 7.0. + + <result name="E_INVALIDARG"> + The @a display value is higher than the number of outputs. + </result> + + </desc> + <param name="display" type="unsigned long" dir="in"> + <desc> + The number of the guest output to query. + </desc> + </param> + <param name="enabled" type="boolean" dir="out"> + <desc> + @c True if a monitor is connected, + @c False otherwise. + <note internal="yes">For historical reasons the Windows drivers can + and do override the setting requested by the host.</note> + </desc> + </param> + <param name="changeOrigin" type="boolean" dir="out"> + <desc> + @c True, if the position of the guest screen was specified, + @c False otherwise. + </desc> + </param> + <param name="originX" type="long" dir="out"> + <desc> + The X origin of the guest screen. + </desc> + </param> + <param name="originY" type="long" dir="out"> + <desc> + The Y origin of the guest screen. + </desc> + </param> + <param name="width" type="unsigned long" dir="out"> + <desc> + The width of the monitor preferred mode. + </desc> + </param> + <param name="height" type="unsigned long" dir="out"> + <desc> + The height of the monitor preferred mode. + </desc> + </param> + <param name="bitsPerPixel" type="unsigned long" dir="out"> + <desc> + The number of bits per pixel of the monitor preferred mode. + </desc> + </param> + </method> + + <method name="setSeamlessMode"> + <desc> + Enables or disables seamless guest display rendering (seamless desktop + integration) mode. + <note> + Calling this method has no effect if <link + to="IGuest::getFacilityStatus"/> with facility @c Seamless + does not return @c Active. + </note> + </desc> + <param name="enabled" type="boolean" dir="in"/> + </method> + + <method name="takeScreenShot"> + <desc> + Takes a screen shot of the requested size and format and copies it to the + buffer allocated by the caller and pointed to by @a address. + The buffer size must be enough for a 32 bits per pixel bitmap, + i.e. width * height * 4 bytes. + + <note>This API can be used only locally by a VM process through the + COM/XPCOM C++ API as it requires pointer support. It is not + available for scripting languages, Java or any webservice clients. + Unless you are writing a new VM frontend use + <link to="#takeScreenShotToArray" />. + </note> + </desc> + <param name="screenId" type="unsigned long" dir="in"/> + <param name="address" type="octet" mod="ptr" dir="in"/> + <param name="width" type="unsigned long" dir="in"/> + <param name="height" type="unsigned long" dir="in"/> + <param name="bitmapFormat" type="BitmapFormat" dir="in"/> + </method> + + <method name="takeScreenShotToArray"> + <desc> + Takes a guest screen shot of the requested size and format + and returns it as an array of bytes. + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc> + The guest monitor to take screenshot from. + </desc> + </param> + <param name="width" type="unsigned long" dir="in"> + <desc> + Desired image width. + </desc> + </param> + <param name="height" type="unsigned long" dir="in"> + <desc> + Desired image height. + </desc> + </param> + <param name="bitmapFormat" type="BitmapFormat" dir="in"> + <desc> + The requested format. + </desc> + </param> + <param name="screenData" type="octet" dir="return" safearray="yes"> + <desc> + Array with resulting screen data. + </desc> + </param> + </method> + + <method name="drawToScreen"> + <desc> + Draws a 32-bpp image of the specified size from the given buffer + to the given point on the VM display. + + <result name="E_NOTIMPL"> + Feature not implemented. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Could not draw to screen. + </result> + + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc> + Monitor to take the screenshot from. + </desc> + </param> + <param name="address" type="octet" mod="ptr" dir="in"> + <desc> + Address to store the screenshot to + </desc> + </param> + <param name="x" type="unsigned long" dir="in"> + <desc> + Relative to the screen top left corner. + </desc> + </param> + <param name="y" type="unsigned long" dir="in"> + <desc> + Relative to the screen top left corner. + </desc> + </param> + <param name="width" type="unsigned long" dir="in"> + <desc> + Desired image width. + </desc> + </param> + <param name="height" type="unsigned long" dir="in"> + <desc> + Desired image height. + </desc> + </param> + </method> + + <method name="invalidateAndUpdate"> + <desc> + Does a full invalidation of the VM display and instructs the VM + to update it. + + <result name="VBOX_E_IPRT_ERROR"> + Could not invalidate and update screen. + </result> + + </desc> + </method> + + <method name="invalidateAndUpdateScreen"> + <desc> + Redraw the specified VM screen. + </desc> + <param name="screenId" type="unsigned long" dir="in"> + <desc> + The guest screen to redraw. + </desc> + </param> + </method> + + <method name="completeVHWACommand"> + <desc> + Signals that the Video HW Acceleration command has completed. + </desc> + + <param name="command" type="octet" mod="ptr" dir="in"> + <desc>Pointer to VBOXVHWACMD containing the completed command.</desc> + </param> + </method> + + <method name="viewportChanged"> + <desc> + Signals that framebuffer window viewport has changed. + + <result name="E_INVALIDARG"> + The specified viewport data is invalid. + </result> + + </desc> + + <param name="screenId" type="unsigned long" dir="in"> + <desc> + Monitor to take the screenshot from. + </desc> + </param> + <param name="x" type="unsigned long" dir="in"> + <desc> + Framebuffer x offset. + </desc> + </param> + <param name="y" type="unsigned long" dir="in"> + <desc> + Framebuffer y offset. + </desc> + </param> + <param name="width" type="unsigned long" dir="in"> + <desc> + Viewport width. + </desc> + </param> + <param name="height" type="unsigned long" dir="in"> + <desc> + Viewport height. + </desc> + </param> + </method> + + <method name="querySourceBitmap" wsmap="suppress"> + <desc> + Obtains the guest screen bitmap parameters. + </desc> + <param name="screenId" type="unsigned long" dir="in"/> + <param name="displaySourceBitmap" type="IDisplaySourceBitmap" dir="out"/> + </method> + + <method name="notifyScaleFactorChange"> + <desc> + Notify OpenGL HGCM host service about graphics content scaling factor change. + </desc> + <param name="screenId" type="unsigned long" dir="in"/> + <param name="u32ScaleFactorWMultiplied" type="unsigned long" dir="in"/> + <param name="u32ScaleFactorHMultiplied" type="unsigned long" dir="in"/> + </method> + + <method name="notifyHiDPIOutputPolicyChange"> + <desc> + Notify OpenGL HGCM host service about HiDPI monitor scaling policy change. + </desc> + <param name="fUnscaledHiDPI" type="boolean" dir="in"/> + </method> + + <method name="setScreenLayout"> + <desc> + Set video modes for the guest screens. + </desc> + <param name="screenLayoutMode" type="ScreenLayoutMode" dir="in"/> + <param name="guestScreenInfo" type="IGuestScreenInfo" safearray="yes" dir="in"/> + </method> + + <method name="detachScreens"> + <desc> + Unplugs monitors from the virtual graphics card. + </desc> + <param name="screenIds" type="long" safearray="yes" dir="in"/> + </method> + + <method name="createGuestScreenInfo"> + <desc> + Make a IGuestScreenInfo object with the provided parameters. + </desc> + <param name="display" type="unsigned long" dir="in"> + <desc> + The number of the guest display. + </desc> + </param> + <param name="status" type="GuestMonitorStatus" dir="in"> + <desc> + @c True, if this guest screen is enabled, + @c False otherwise. + </desc> + </param> + <param name="primary" type="boolean" dir="in"> + <desc> + Whether this guest monitor must be primary. + </desc> + </param> + <param name="changeOrigin" type="boolean" dir="in"> + <desc> + @c True, if the origin of the guest screen should be changed, + @c False otherwise. + </desc> + </param> + <param name="originX" type="long" dir="in"> + <desc> + The X origin of the guest screen. + </desc> + </param> + <param name="originY" type="long" dir="in"> + <desc> + The Y origin of the guest screen. + </desc> + </param> + <param name="width" type="unsigned long" dir="in"> + <desc> + The width of the guest screen. + </desc> + </param> + <param name="height" type="unsigned long" dir="in"> + <desc> + The height of the guest screen. + </desc> + </param> + <param name="bitsPerPixel" type="unsigned long" dir="in"> + <desc> + The number of bits per pixel of the guest screen. + </desc> + </param> + <param name="guestScreenInfo" type="IGuestScreenInfo" dir="return"> + <desc> + The created object. + </desc> + </param> + </method> + + </interface> + + <!-- + // INetworkAdapter + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="NetworkAttachmentType" + uuid="cbfd17fa-fdc3-4d1c-97ec-4674da8d2a5d" + > + <desc> + Network attachment type. + </desc> + + <const name="Null" value="0"> + <desc>Null value, also means "not attached".</desc> + </const> + <const name="NAT" value="1"/> + <const name="Bridged" value="2"/> + <const name="Internal" value="3"/> + <const name="HostOnly" value="4"/> + <const name="Generic" value="5"/> + <const name="NATNetwork" value="6"/> + <const name="Cloud" value="7"/> + <const name="HostOnlyNetwork" value="8"/> + </enum> + + <enum + name="NetworkAdapterType" + uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c" + > + <desc> + Network adapter type. + </desc> + + <const name="Null" value="0"> + <desc>Null value (never used by the API).</desc> + </const> + <const name="Am79C970A" value="1"> + <desc>AMD PCNet-PCI II network card (Am79C970A).</desc> + </const> + <const name="Am79C973" value="2"> + <desc>AMD PCNet-FAST III network card (Am79C973).</desc> + </const> + <const name="I82540EM" value="3"> + <desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc> + </const> + <const name="I82543GC" value="4"> + <desc>Intel PRO/1000 T Server network card (82543GC).</desc> + </const> + <const name="I82545EM" value="5"> + <desc>Intel PRO/1000 MT Server network card (82545EM).</desc> + </const> + <const name="Virtio" value="6"> + <desc>Virtio network device.</desc> + </const> + <const name="Am79C960" value="7"> + <desc>AMD PCnet-ISA/NE2100 network card (Am79C960).</desc> + </const> + <const name="NE2000" value="8"> + <desc>Novell NE2000 network card (NE2000).</desc> + </const> + <const name="NE1000" value="9"> + <desc>Novell NE1000 network card (NE1000).</desc> + </const> + <const name="WD8013" value="10"> + <desc>WD/SMC EtherCard Plus 16 network card (WD8013EBT).</desc> + </const> + <const name="WD8003" value="11"> + <desc>WD/SMC EtherCard Plus network card (WD8003E).</desc> + </const> + <const name="ELNK2" value="12"> + <desc>3Com EtherLink II network card (3C503).</desc> + </const> + <const name="ELNK1" value="13"> + <desc>3Com EtherLink network card (3C501/3C500).</desc> + </const> + </enum> + + <enum + name="NetworkAdapterPromiscModePolicy" + uuid="c963768a-376f-4c85-8d84-d8ced4b7269e" + > + <desc> + The promiscuous mode policy of an interface. + </desc> + + <const name="Deny" value="1"> + <desc>Deny promiscuous mode requests.</desc> + </const> + <const name="AllowNetwork" value="2"> + <desc> + Allow promiscuous mode, but restrict the scope it to the internal + network so that it only applies to other VMs. + </desc> + </const> + <const name="AllowAll" value="3"> + <desc> + Allow promiscuous mode, include unrelated traffic going over the wire + and internally on the host. + </desc> + </const> + </enum> + + <interface + name="INetworkAdapter" extends="$unknown" + uuid="dcf47a1d-ed70-4db8-9a4b-2646bd166905" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + Represents a virtual network adapter that is attached to a virtual machine. + Each virtual machine has a fixed number of network adapter slots with one + instance of this attached to each of them. Call + <link to="IMachine::getNetworkAdapter" /> to get the network adapter that + is attached to a given slot in a given machine. + + Each network adapter can be in one of five attachment modes, which are + represented by the <link to="NetworkAttachmentType" /> enumeration; + see the <link to="#attachmentType" /> attribute. + </desc> + + <attribute name="adapterType" type="NetworkAdapterType"> + <desc> + Type of the virtual network adapter. Depending on this value, + VirtualBox will provide a different virtual network hardware + to the guest. + </desc> + </attribute> + + <attribute name="slot" type="unsigned long" readonly="yes"> + <desc> + Slot number this adapter is plugged into. Corresponds to + the value you pass to <link to="IMachine::getNetworkAdapter"/> + to obtain this instance. + </desc> + </attribute> + + <attribute name="enabled" type="boolean"> + <desc> + Flag whether the network adapter is present in the + guest system. If disabled, the virtual guest hardware will + not contain this network adapter. Can only be changed when + the VM is not running. + </desc> + </attribute> + + <attribute name="MACAddress" type="wstring"> + <desc> + Ethernet MAC address of the adapter, 12 hexadecimal characters. When + setting it to @c null or an empty string for an enabled adapter, + VirtualBox will generate a unique MAC address. Disabled adapters can + have an empty MAC address. + </desc> + </attribute> + + <attribute name="attachmentType" type="NetworkAttachmentType"> + <desc> + Sets/Gets network attachment type of this network adapter. + </desc> + </attribute> + + <attribute name="bridgedInterface" type="wstring"> + <desc> + Name of the network interface the VM should be bridged to. + </desc> + </attribute> + + <attribute name="hostOnlyInterface" type="wstring"> + <desc> + Name of the host only network interface the VM is attached to. + </desc> + </attribute> + + <attribute name="hostOnlyNetwork" type="wstring"> + <desc> + Name of the host only network the VM is attached to. + </desc> + </attribute> + + <attribute name="internalNetwork" type="wstring"> + <desc> + Name of the internal network the VM is attached to. + </desc> + </attribute> + + <attribute name="NATNetwork" type="wstring"> + <desc> + Name of the NAT network the VM is attached to. + </desc> + </attribute> + + <attribute name="genericDriver" type="wstring"> + <desc> + Name of the driver to use for the "Generic" network attachment type. + </desc> + </attribute> + + <attribute name="cloudNetwork" type="wstring"> + <desc> + Name of the cloud network the VM is attached to. + </desc> + </attribute> + + <attribute name="cableConnected" type="boolean"> + <desc> + Flag whether the adapter reports the cable as connected or not. + It can be used to report offline situations to a VM. + </desc> + </attribute> + + <attribute name="lineSpeed" type="unsigned long"> + <desc> + Line speed reported by custom drivers, in units of 1 kbps. + </desc> + </attribute> + + <attribute name="promiscModePolicy" type="NetworkAdapterPromiscModePolicy"> + <desc> + The promiscuous mode policy of the network adapter when attached to an + internal network, host only network or a bridge. + </desc> + </attribute> + + <attribute name="traceEnabled" type="boolean"> + <desc> + Flag whether network traffic from/to the network card should be traced. + Can only be toggled when the VM is turned off. + </desc> + </attribute> + + <attribute name="traceFile" type="wstring"> + <desc> + Filename where a network trace will be stored. If not set, VBox-pid.pcap + will be used. + </desc> + </attribute> + + <attribute name="NATEngine" type="INATEngine" readonly="yes"> + <desc> + Points to the NAT engine which handles the network address translation + for this interface. This is active only when the interface actually uses + NAT. + </desc> + </attribute> + + <attribute name="bootPriority" type="unsigned long"> + <desc> + Network boot priority of the adapter. Priority 1 is highest. If not set, + the priority is considered to be at the lowest possible setting. + </desc> + </attribute> + + <attribute name="bandwidthGroup" type="IBandwidthGroup"> + <desc>The bandwidth group this network adapter is assigned to.</desc> + </attribute> + + <!-- property methods --> + + <method name="getProperty" const="yes"> + <desc> + Returns the value of the network attachment property with the given name. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + <result name="E_INVALIDARG">@a name is @c null or empty.</result> + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the property to get.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc>Current property value.</desc> + </param> + </method> + + <method name="setProperty"> + <desc> + Sets the value of the network attachment property with the given name. + + Setting the property value to @c null or an empty string is equivalent + to deleting the existing value. + + <result name="E_INVALIDARG">@a name is @c null or empty.</result> + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the property to set.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc>Property value to set.</desc> + </param> + </method> + + <method name="getProperties" const="yes"> + <desc> + Returns values for a group of properties in one call. + + The names of the properties to get are specified using the @a names + argument which is a list of comma-separated property names or + an empty string if all properties are to be returned. + <note>Currently the value of this argument is ignored and the method + always returns all existing properties.</note> + + The method returns two arrays, the array of property names corresponding + to the @a names argument and the current values of these properties. + Both arrays have the same number of elements with each element at the + given index in the first array corresponds to an element at the same + index in the second array. + </desc> + <param name="names" type="wstring" dir="in"> + <desc> + Names of properties to get. + </desc> + </param> + <param name="returnNames" type="wstring" safearray="yes" dir="out"> + <desc>Names of returned properties.</desc> + </param> + <param name="returnValues" type="wstring" safearray="yes" dir="return"> + <desc>Values of returned properties.</desc> + </param> + </method> + + </interface> + + + <!-- + // ISerialPort + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="PortMode" + uuid="7485fcfd-d603-470a-87af-26d33beb7de9" + > + <desc> + The PortMode enumeration represents possible communication modes for + the virtual serial port device. + </desc> + + <const name="Disconnected" value="0"> + <desc>Virtual device is not attached to any real host device.</desc> + </const> + <const name="HostPipe" value="1"> + <desc>Virtual device is attached to a host pipe.</desc> + </const> + <const name="HostDevice" value="2"> + <desc>Virtual device is attached to a host device.</desc> + </const> + <const name="RawFile" value="3"> + <desc>Virtual device is attached to a raw file.</desc> + </const> + <const name="TCP" value="4"> + <desc>Virtual device is attached to a TCP socket.</desc> + </const> + </enum> + + <enum + name="UartType" + uuid="c8899d39-0b90-4265-9d02-1e38bd4d1b39" + > + <desc> + The UART type represents the emulated UART chip for the serial port device. + </desc> + + <const name="U16450" value="0"> + <desc>The most basic emulated UART which doesn't support FIFO operation.</desc> + </const> + <const name="U16550A" value="1"> + <desc> + The successor of the 16450 UART introducing a 16 byte FIFO to reduce + operational overhead. + </desc> + </const> + <const name="U16750" value="2"> + <desc> + This UART developed by Texas Instruments introduced a 64 byte FIFO + and hardware flow control. + </desc> + </const> + </enum> + + <interface + name="ISerialPort" extends="$unknown" + uuid="5587d0f6-a227-4f23-8278-2f675eea1bb2" + wsmap="managed" + rest="managed" + reservedAttributes="4" + > + + <desc> + The ISerialPort interface represents the virtual serial port device. + + The virtual serial port device acts like an ordinary serial port + inside the virtual machine. This device communicates to the real + serial port hardware in one of two modes: host pipe or host device. + + In host pipe mode, the #path attribute specifies the path to the pipe on + the host computer that represents a serial port. The #server attribute + determines if this pipe is created by the virtual machine process at + machine startup or it must already exist before starting machine + execution. + + In host device mode, the #path attribute specifies the name of the + serial port device on the host computer. + + There is also a third communication mode: the disconnected mode. In this + mode, the guest OS running inside the virtual machine will be able to + detect the serial port, but all port write operations will be discarded + and all port read operations will return no data. + + <see><link to="IMachine::getSerialPort"/></see> + </desc> + + <attribute name="slot" type="unsigned long" readonly="yes"> + <desc> + Slot number this serial port is plugged into. Corresponds to + the value you pass to <link to="IMachine::getSerialPort"/> + to obtain this instance. + </desc> + </attribute> + + <attribute name="enabled" type="boolean"> + <desc> + Flag whether the serial port is enabled. If disabled, + the serial port will not be reported to the guest OS. + </desc> + </attribute> + + <attribute name="IOBase" type="unsigned long"> + <desc>Base I/O address of the serial port.</desc> + </attribute> + + <attribute name="IRQ" type="unsigned long"> + <desc>IRQ number of the serial port.</desc> + </attribute> + + <attribute name="hostMode" type="PortMode"> + <desc> + How is this port connected to the host. + <note> + Changing this attribute may fail if the conditions for + <link to="#path"/> are not met. + </note> + </desc> + </attribute> + + <attribute name="server" type="boolean"> + <desc> + Flag whether this serial port acts as a server (creates a new pipe on + the host) or as a client (uses the existing pipe). This attribute is + used only when <link to="#hostMode"/> is PortMode_HostPipe or PortMode_TCP. + </desc> + </attribute> + + <attribute name="path" type="wstring"> + <desc> + Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is + PortMode_HostPipe, the host serial device name when + <link to="ISerialPort::hostMode"/> is PortMode_HostDevice or the TCP + <b>port</b> (server) or <b>hostname:port</b> (client) when + <link to="ISerialPort::hostMode"/> is PortMode_TCP. + For those cases, setting a @c null or empty string as the attribute's + value is an error. Otherwise, the value of this property is ignored. + </desc> + </attribute> + + <attribute name="uartType" type="UartType"> + <desc>Selects the emulated UART implementation.</desc> + </attribute> + + </interface> + + <!-- + // IParallelPort + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IParallelPort" extends="$unknown" + uuid="788b87df-7708-444b-9eef-c116ce423d39" + wsmap="managed" + rest="managed" + reservedAttributes="4" + > + + <desc> + The IParallelPort interface represents the virtual parallel port device. + + The virtual parallel port device acts like an ordinary parallel port + inside the virtual machine. This device communicates to the real + parallel port hardware using the name of the parallel device on the host + computer specified in the #path attribute. + + Each virtual parallel port device is assigned a base I/O address and an + IRQ number that will be reported to the guest operating system and used + to operate the given parallel port from within the virtual machine. + + <see><link to="IMachine::getParallelPort"/></see> + </desc> + + <attribute name="slot" type="unsigned long" readonly="yes"> + <desc> + Slot number this parallel port is plugged into. Corresponds to + the value you pass to <link to="IMachine::getParallelPort"/> + to obtain this instance. + </desc> + </attribute> + + <attribute name="enabled" type="boolean"> + <desc> + Flag whether the parallel port is enabled. If disabled, + the parallel port will not be reported to the guest OS. + </desc> + </attribute> + + <attribute name="IOBase" type="unsigned long"> + <desc>Base I/O address of the parallel port.</desc> + </attribute> + + <attribute name="IRQ" type="unsigned long"> + <desc>IRQ number of the parallel port.</desc> + </attribute> + + <attribute name="path" type="wstring"> + <desc> + Host parallel device name. If this parallel port is enabled, setting a + @c null or an empty string as this attribute's value will result in + the parallel port behaving as if not connected to any device. + </desc> + </attribute> + + </interface> + + + <!-- + // IMachineDebugger + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="VMExecutionEngine" + uuid="6e3f78f9-2dfe-4ed7-863d-67cad351e9d8" + > + <desc> + The main execution engine of a VM. + </desc> + <const name="NotSet" value="0"> + <desc>Has not yet been set (try again later).</desc> + </const> + <const name="Emulated" value="1"> + <desc>Emulated thru IEM.</desc> + </const> + <const name="HwVirt" value="2"> + <desc>Hardware assisted virtualization thru HM.</desc> + </const> + <const name="NativeApi" value="3"> + <desc>Hardware assisted virtualization thru native API (NEM).</desc> + </const> + </enum> + + <interface + name="IMachineDebugger" extends="$unknown" + uuid="fa43579a-2272-47c4-a443-9713f19a902f" + wsmap="managed" + rest="managed" + reservedMethods="16" reservedAttributes="16" + > + <method name="dumpGuestCore"> + <desc> + Takes a core dump of the guest. + + See include/VBox/dbgfcorefmt.h for details on the file format. + </desc> + <param name="filename" type="wstring" dir="in"> + <desc> + The name of the output file. The file must not exist. + </desc> + </param> + <param name="compression" type="wstring" dir="in"> + <desc> + Reserved for future compression method indicator. + </desc> + </param> + </method> + + <method name="dumpHostProcessCore"> + <desc> + Takes a core dump of the VM process on the host. + + This feature is not implemented in the 4.0.0 release but it may show up + in a dot release. + </desc> + <param name="filename" type="wstring" dir="in"> + <desc> + The name of the output file. The file must not exist. + </desc> + </param> + <param name="compression" type="wstring" dir="in"> + <desc> + Reserved for future compression method indicator. + </desc> + </param> + </method> + + <method name="info"> + <desc> + Interfaces with the info dumpers (DBGFInfo). + + This feature is not implemented in the 4.0.0 release but it may show up + in a dot release. + </desc> + <param name="name" type="wstring" dir="in"> + <desc> + The name of the info item. + </desc> + </param> + <param name="args" type="wstring" dir="in"> + <desc> + Arguments to the info dumper. + </desc> + </param> + <param name="info" type="wstring" dir="return"> + <desc> + The into string. + </desc> + </param> + </method> + + <method name="injectNMI"> + <desc> + Inject an NMI into a running VT-x/AMD-V VM. + </desc> + </method> + + <method name="modifyLogGroups"> + <desc> + Modifies the group settings of the debug or release logger. + </desc> + <param name="settings" type="wstring" dir="in"> + <desc> + The group settings string. See iprt/log.h for details. To target the + release logger, prefix the string with "release:". + </desc> + </param> + </method> + + <method name="modifyLogFlags"> + <desc> + Modifies the debug or release logger flags. + </desc> + <param name="settings" type="wstring" dir="in"> + <desc> + The flags settings string. See iprt/log.h for details. To target the + release logger, prefix the string with "release:". + </desc> + </param> + </method> + + <method name="modifyLogDestinations"> + <desc> + Modifies the debug or release logger destinations. + </desc> + <param name="settings" type="wstring" dir="in"> + <desc> + The destination settings string. See iprt/log.h for details. To target the + release logger, prefix the string with "release:". + </desc> + </param> + </method> + + <method name="readPhysicalMemory"> + <desc> + Reads guest physical memory, no side effects (MMIO++). + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + <param name="address" type="long long" dir="in"> + <desc>The guest physical address.</desc> + </param> + <param name="size" type="unsigned long" dir="in"> + <desc>The number of bytes to read.</desc> + </param> + <param name="bytes" type="octet" safearray="yes" dir="return"> + <desc>The bytes read.</desc> + </param> + </method> + + <method name="writePhysicalMemory"> + <desc> + Writes guest physical memory, access handles (MMIO++) are ignored. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + <param name="address" type="long long" dir="in"> + <desc>The guest physical address.</desc> + </param> + <param name="size" type="unsigned long" dir="in"> + <desc>The number of bytes to read.</desc> + </param> + <param name="bytes" type="octet" safearray="yes" dir="in"> + <desc>The bytes to write.</desc> + </param> + </method> + + <method name="readVirtualMemory"> + <desc> + Reads guest virtual memory, no side effects (MMIO++). + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc>The identifier of the Virtual CPU.</desc> + </param> + <param name="address" type="long long" dir="in"> + <desc>The guest virtual address.</desc> + </param> + <param name="size" type="unsigned long" dir="in"> + <desc>The number of bytes to read.</desc> + </param> + <param name="bytes" type="octet" safearray="yes" dir="return"> + <desc>The bytes read.</desc> + </param> + </method> + + <method name="writeVirtualMemory"> + <desc> + Writes guest virtual memory, access handles (MMIO++) are ignored. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc>The identifier of the Virtual CPU.</desc> + </param> + <param name="address" type="long long" dir="in"> + <desc>The guest virtual address.</desc> + </param> + <param name="size" type="unsigned long" dir="in"> + <desc>The number of bytes to read.</desc> + </param> + <param name="bytes" type="octet" safearray="yes" dir="in"> + <desc>The bytes to write.</desc> + </param> + </method> + + <method name="loadPlugIn"> + <desc> Loads a DBGF plug-in. </desc> + <param name="name" type="wstring" dir="in"> + <desc>The plug-in name or DLL. Special name 'all' loads all installed plug-ins.</desc> + </param> + <param name="plugInName" type="wstring" dir="return"> + <desc>The name of the loaded plug-in.</desc> + </param> + </method> + + <method name="unloadPlugIn"> + <desc>Unloads a DBGF plug-in.</desc> + <param name="name" type="wstring" dir="in"> + <desc>The plug-in name or DLL. Special name 'all' unloads all plug-ins.</desc> + </param> + </method> + + <method name="detectOS"> + <desc> + Tries to (re-)detect the guest OS kernel. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + <param name="os" type="wstring" dir="return"> + <desc> + The detected OS kernel on success. + </desc> + </param> + </method> + + <method name="queryOSKernelLog"> + <desc> + Tries to get the kernel log (dmesg) of the guest OS. + + </desc> + <param name="maxMessages" type="unsigned long" dir="in"> + <desc>Max number of messages to return, counting from the end of the + log. If 0, there is no limit.</desc> + </param> + <param name="dmesg" type="wstring" dir="return"> + <desc> + The kernel log. + </desc> + </param> + </method> + + <method name="getRegister"> + <desc> + Gets one register. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc>The identifier of the Virtual CPU.</desc> + </param> + <param name="name" type="wstring" dir="in"> + <desc>The register name, case is ignored.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc> + The register value. This is usually a hex value (always 0x prefixed) + but other format may be used for floating point registers (TBD). + </desc> + </param> + </method> + + <method name="getRegisters"> + <desc> + Gets all the registers for the given CPU. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc>The identifier of the Virtual CPU.</desc> + </param> + <param name="names" type="wstring" dir="out" safearray="yes"> + <desc>Array containing the lowercase register names.</desc> + </param> + <param name="values" type="wstring" dir="out" safearray="yes"> + <desc> + Array parallel to the names holding the register values as if the + register was returned by <link to="IMachineDebugger::getRegister"/>. + </desc> + </param> + </method> + + <method name="setRegister"> + <desc> + Gets one register. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc>The identifier of the Virtual CPU.</desc> + </param> + <param name="name" type="wstring" dir="in"> + <desc>The register name, case is ignored.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc> + The new register value. Hexadecimal, decimal and octal formattings + are supported in addition to any special formattings returned by + the getters. + </desc> + </param> + </method> + + <method name="setRegisters"> + <desc> + Sets zero or more registers atomically. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc>The identifier of the Virtual CPU.</desc> + </param> + <param name="names" type="wstring" dir="in" safearray="yes"> + <desc>Array containing the register names, case ignored.</desc> + </param> + <param name="values" type="wstring" dir="in" safearray="yes"> + <desc> + Array paralell to the names holding the register values. See + <link to="IMachineDebugger::setRegister"/> for formatting + guidelines. + </desc> + </param> + </method> + + <method name="dumpGuestStack"> + <desc> + Produce a simple stack dump using the current guest state. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc>The identifier of the Virtual CPU.</desc> + </param> + <param name="stack" type="wstring" dir="return"> + <desc>String containing the formatted stack dump.</desc> + </param> + </method> + + <method name="resetStats"> + <desc> + Reset VM statistics. + </desc> + <param name="pattern" type="wstring" dir="in"> + <desc>The selection pattern. A bit similar to filename globbing. + Wildchars are '*' and '?', where the asterisk matches zero or + more characters and question mark matches exactly one character. + Multiple pattern can be joined by putting '|' between them.</desc> + </param> + </method> + + <method name="dumpStats"> + <desc> + Dumps VM statistics. + </desc> + <param name="pattern" type="wstring" dir="in"> + <desc>The selection pattern. A bit similar to filename globbing. + Wildchars are '*' and '?', where the asterisk matches zero or + more characters and question mark matches exactly one character. + Multiple pattern can be joined by putting '|' between them.</desc> + </param> + </method> + + <method name="getStats"> + <desc> + Get the VM statistics in a XMLish format. + </desc> + <param name="pattern" type="wstring" dir="in"> + <desc>The selection pattern. A bit similar to filename globbing. + Wildchars are '*' and '?', where the asterisk matches zero or + more characters and question mark matches exactly one character. + Multiple pattern can be joined by putting '|' between them.</desc> + </param> + <param name="withDescriptions" type="boolean" dir="in"> + <desc>Whether to include the descriptions.</desc> + </param> + <param name="stats" type="wstring" dir="return"> + <desc>The XML document containing the statistics.</desc> + </param> + </method> + + <method name="getCPULoad"> + <desc> + Get the load percentages (as observed by the VMM) for all virtual CPUs + or a specific one. + </desc> + <param name="cpuId" type="unsigned long" dir="in"> + <desc>The ID of the virtual CPU to retrieve stats for, pass 0x7fffffff + or higher for the average accross all CPUs.</desc> + </param> + <param name="pctExecuting" type="unsigned long" dir="out"> + <desc>Percentage of the interval that the CPU(s) spend executing guest code.</desc> + </param> + <param name="pctHalted" type="unsigned long" dir="out"> + <desc>Percentage of the interval that the CPU(s) spend halted.</desc> + </param> + <param name="pctOther" type="unsigned long" dir="out"> + <desc>Percentage of the interval that the CPU(s) preempted by the host + scheduler, on virtualization overhead and on other tasks.</desc> + </param> + <param name="msInterval" type="long long" dir="return"> + <desc>The interval the percentage was calculated over in milliseconds</desc> + </param> + </method> + + <method name="takeGuestSample"> + <desc> + Creates a sample report of the guest and emulated device activity. + </desc> + <param name="filename" type="wstring" dir="in"> + <desc>The file to dump the report to.</desc> + </param> + <param name="usInterval" type="unsigned long" dir="in"> + <desc>The sample interval.</desc> + </param> + <param name="usSampleTime" type="long long" dir="in"> + <desc>The number of microseconds to sample.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>The progress object on return.</desc> + </param> + </method> + + <method name="getUVMAndVMMFunctionTable" wsmap="suppress"> + <desc> + Gets the user-mode VM handle, with a reference, and the VMM function table. + The VM handle must be passed to VMR3ReleaseUVM when done. This can only + be called from within the VM process, remote calls will always fail. + </desc> + <param name="magicVersion" type="long long" dir="in"> + <desc>The VMMR3VTABLE_MAGIC_VERSION value of the caller. The method + will fail if this is not compatible with the VMM function table.</desc> + </param> + <param name="VMMFunctionTable" type="long long" dir="out"> + <desc>The VMM function table address.</desc> + </param> + <param name="UVM" type="long long" dir="return"> + <desc>The user-mode VM handle.</desc> + </param> + </method> + + <attribute name="singleStep" type="boolean"> + <desc>Switch for enabling single-stepping.</desc> + </attribute> + + <attribute name="executeAllInIEM" type="boolean"> + <desc> + Whether to execute all the code in the instruction interpreter. This + is mainly for testing the interpreter and not an execution mode + intended for general consumption. + </desc> + </attribute> + + <attribute name="logEnabled" type="boolean"> + <desc>Switch for enabling and disabling the debug logger.</desc> + </attribute> + + <attribute name="logDbgFlags" type="wstring" readonly="yes"> + <desc>The debug logger flags.</desc> + </attribute> + + <attribute name="logDbgGroups" type="wstring" readonly="yes"> + <desc>The debug logger's group settings.</desc> + </attribute> + + <attribute name="logDbgDestinations" type="wstring" readonly="yes"> + <desc>The debug logger's destination settings.</desc> + </attribute> + + <attribute name="logRelFlags" type="wstring" readonly="yes"> + <desc>The release logger flags.</desc> + </attribute> + + <attribute name="logRelGroups" type="wstring" readonly="yes"> + <desc>The release logger's group settings.</desc> + </attribute> + + <attribute name="logRelDestinations" type="wstring" readonly="yes"> + <desc>The relase logger's destination settings.</desc> + </attribute> + + <attribute name="executionEngine" type="VMExecutionEngine" readonly="yes"> + <desc>Gets the main execution engine of the VM.</desc> + </attribute> + + <attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes"> + <desc> + Flag indicating whether the VM is currently making use of the nested paging + CPU hardware virtualization extension. + </desc> + </attribute> + + <attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes"> + <desc> + Flag indicating whether the VM is currently making use of the VPID + VT-x extension. + </desc> + </attribute> + + <attribute name="HWVirtExUXEnabled" type="boolean" readonly="yes"> + <desc> + Flag indicating whether the VM is currently making use of the + unrestricted execution feature of VT-x. + </desc> + </attribute> + + <attribute name="OSName" type="wstring" readonly="yes"> + <desc> + Query the guest OS kernel name as detected by the DBGF. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + </attribute> + + <attribute name="OSVersion" type="wstring" readonly="yes"> + <desc> + Query the guest OS kernel version string as detected by the DBGF. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + </desc> + </attribute> + + <attribute name="PAEEnabled" type="boolean" readonly="yes"> + <desc> + Flag indicating whether the VM is currently making use of the Physical + Address Extension CPU feature. + </desc> + </attribute> + + <attribute name="virtualTimeRate" type="unsigned long"> + <desc> + The rate at which the virtual time runs expressed as a percentage. + The accepted range is 2% to 20000%. + </desc> + </attribute> + + <attribute name="uptime" type="long long" readonly="yes"> + <desc>VM uptime in milliseconds, i.e. time in which it could have been + executing guest code. Excludes the time when the VM was paused.</desc> + </attribute> + + </interface> + + <!-- + // IUSBDeviceFilters + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IUSBDeviceFilters" extends="$unknown" + uuid="9709db9b-3346-49d6-8f1c-41b0c4784ff2" + wsmap="managed" + rest="managed" + reservedMethods="2" reservedAttributes="2" + > + + <attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes"> + <desc> + List of USB device filters associated with the machine. + + If the machine is currently running, these filters are activated + every time a new (supported) USB device is attached to the host + computer that was not ignored by global filters + (<link to="IHost::USBDeviceFilters"/>). + + These filters are also activated when the machine is powered up. + They are run against a list of all currently available USB + devices (in states + <link to="USBDeviceState_Available"/>, + <link to="USBDeviceState_Busy"/>, + <link to="USBDeviceState_Held"/>) that were not previously + ignored by global filters. + + If at least one filter matches the USB device in question, this + device is automatically captured (attached to) the virtual USB + controller of this machine. + + <see><link to="IUSBDeviceFilter"/>, <link to="IUSBController"/></see> + </desc> + </attribute> + + <method name="createDeviceFilter"> + <desc> + Creates a new USB device filter. All attributes except + the filter name are set to empty (any match), + <i>active</i> is @c false (the filter is not active). + + The created filter can then be added to the list of filters using + <link to="#insertDeviceFilter"/>. + + <result name="VBOX_E_INVALID_VM_STATE"> + The virtual machine is not mutable. + </result> + + <see><link to="#deviceFilters"/></see> + </desc> + <param name="name" type="wstring" dir="in"> + <desc> + Filter name. See <link to="IUSBDeviceFilter::name"/> + for more info. + </desc> + </param> + <param name="filter" type="IUSBDeviceFilter" dir="return"> + <desc>Created filter object.</desc> + </param> + </method> + + <method name="insertDeviceFilter"> + <desc> + Inserts the given USB device to the specified position + in the list of filters. + + Positions are numbered starting from <tt>0</tt>. If the specified + position is equal to or greater than the number of elements in + the list, the filter is added to the end of the collection. + + <note> + Duplicates are not allowed, so an attempt to insert a + filter that is already in the collection, will return an + error. + </note> + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is not mutable. + </result> + <result name="E_INVALIDARG"> + USB device filter not created within this VirtualBox instance. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + USB device filter already in list. + </result> + + <see><link to="#deviceFilters"/></see> + </desc> + <param name="position" type="unsigned long" dir="in"> + <desc>Position to insert the filter to.</desc> + </param> + <param name="filter" type="IUSBDeviceFilter" dir="in"> + <desc>USB device filter to insert.</desc> + </param> + </method> + + <method name="removeDeviceFilter"> + <desc> + Removes a USB device filter from the specified position in the + list of filters. + + Positions are numbered starting from <tt>0</tt>. Specifying a + position equal to or greater than the number of elements in + the list will produce an error. + + <see><link to="#deviceFilters"/></see> + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine is not mutable. + </result> + <result name="E_INVALIDARG"> + USB device filter list empty or invalid @a position. + </result> + + </desc> + <param name="position" type="unsigned long" dir="in"> + <desc>Position to remove the filter from.</desc> + </param> + <param name="filter" type="IUSBDeviceFilter" dir="return"> + <desc>Removed USB device filter.</desc> + </param> + </method> + + </interface> + + <!-- + // IUSBController + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="USBControllerType" + uuid="8fdd1c6a-5412-41da-ab07-7baed7d6e18e" + > + <desc> + The USB controller type. <link to="IUSBController::type" />. + </desc> + <const name="Null" value="0"> + <desc>@c null value. Never used by the API.</desc> + </const> + <const name="OHCI" value="1"/> + <const name="EHCI" value="2"/> + <const name="XHCI" value="3"/> + <const name="Last" value="4"> + <desc>Last element (invalid). Used for parameter checks.</desc> + </const> + </enum> + + <interface + name="IUSBController" extends="$unknown" + uuid="ee206a6e-7ff8-4a84-bd34-0c651e118bb5" + wsmap="managed" + rest="managed" + reservedAttributes="4" + > + + <attribute name="name" type="wstring"> + <desc> + The USB Controller name. + </desc> + </attribute> + + <attribute name="type" type="USBControllerType"> + <desc> + The USB Controller type. + </desc> + </attribute> + + <attribute name="USBStandard" type="unsigned short" readonly="yes"> + <desc> + USB standard version which the controller implements. + This is a BCD which means that the major version is in the + high byte and minor version is in the low byte. + </desc> + </attribute> + + </interface> + + + <!-- + // IUSBDevice + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="USBConnectionSpeed" + uuid="d2915840-ea26-4fb4-b72a-21eaf6b888ff" + > + <desc> + USB device/port speed state. This enumeration represents speeds at + which a USB device can communicate with the host. + + The speed is a function of both the device itself and the port which + it is attached to, including hubs and cables in the path. + + <note> + Due to differences in USB stack implementations on various hosts, + the reported speed may not exactly match the actual speed. + </note> + + <see><link to="IHostUSBDevice"/></see> + </desc> + + <const name="Null" value="0"> + <desc> + @c null value. Never returned by the API. + </desc> + </const> + <const name="Low" value="1"> + <desc> + Low speed, 1.5 Mbps. + </desc> + </const> + <const name="Full" value="2"> + <desc> + Full speed, 12 Mbps. + </desc> + </const> + <const name="High" value="3"> + <desc> + High speed, 480 Mbps. + </desc> + </const> + <const name="Super" value="4"> + <desc> + SuperSpeed, 5 Gbps. + </desc> + </const> + <const name="SuperPlus" value="5"> + <desc> + SuperSpeedPlus, 10 Gbps. + </desc> + </const> + </enum> + + <interface + name="IUSBDevice" extends="$unknown" + uuid="6dc83c2c-81a9-4005-9d52-fc45a78bf3f5" + wsmap="managed" + rest="managed" + reservedAttributes="4" + > + <desc> + The IUSBDevice interface represents a virtual USB device attached to the + virtual machine. + + A collection of objects implementing this interface is stored in the + <link to="IConsole::USBDevices"/> attribute which lists all USB devices + attached to a running virtual machine's USB controller. + </desc> + + <attribute name="id" type="uuid" mod="string" readonly="yes"> + <desc> + Unique USB device ID. This ID is built from #vendorId, + #productId, #revision and #serialNumber. + </desc> + </attribute> + + <attribute name="vendorId" type="unsigned short" readonly="yes"> + <desc>Vendor ID.</desc> + </attribute> + + <attribute name="productId" type="unsigned short" readonly="yes"> + <desc>Product ID.</desc> + </attribute> + + <attribute name="revision" type="unsigned short" readonly="yes"> + <desc> + Product revision number. This is a packed BCD represented as + unsigned short. The high byte is the integer part and the low + byte is the decimal. + </desc> + </attribute> + + <attribute name="manufacturer" type="wstring" readonly="yes"> + <desc>Manufacturer string.</desc> + </attribute> + + <attribute name="product" type="wstring" readonly="yes"> + <desc>Product string.</desc> + </attribute> + + <attribute name="serialNumber" type="wstring" readonly="yes"> + <desc>Serial number string.</desc> + </attribute> + + <attribute name="address" type="wstring" readonly="yes"> + <desc> + Host-specific address of the device, uniquely + identifying a physically connected device in the system. + Note that the address of a USB device may change across + device re-plugs and host suspend/resume cycles or reboots. + </desc> + </attribute> + + <attribute name="port" type="unsigned short" readonly="yes"> + <desc> + Host USB port number on the hub the device is physically + connected to. + </desc> + </attribute> + + <attribute name="portPath" type="wstring" readonly="yes"> + <desc> + Host-specific identifier of the port (including hub) the USB + device is physically connected to. Note that hubs may be + dynamically added and removed, and that hub enumeration may not + be consistent across host reboots. + </desc> + </attribute> + + <attribute name="version" type="unsigned short" readonly="yes"> + <desc> + The major USB version of the device - 1, 2 or 3. + </desc> + </attribute> + + <attribute name="speed" type="USBConnectionSpeed" readonly="yes"> + <desc> + The speed at which the device is currently communicating. + </desc> + </attribute> + + <attribute name="remote" type="boolean" readonly="yes"> + <desc> + Whether the device is physically connected to a remote VRDE + client or to a local host machine. + </desc> + </attribute> + + <attribute name="deviceInfo" type="wstring" readonly="yes" safearray="yes"> + <desc> + Array of device attributes as single strings. + + So far the following are used: + 0: The manufacturer string, if the device doesn't expose the ID one is taken + from an internal database or an empty string if none is found. + 1: The product string, if the device doesn't expose the ID one is taken + from an internal database or an empty string if none is found. + </desc> + </attribute> + + <attribute name="backend" type="wstring" readonly="yes"> + <desc> + The backend which will be used to communicate with this device. + </desc> + </attribute> + + </interface> + + + <!-- + // IUSBDeviceFilter + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IUSBDeviceFilter" extends="$unknown" + uuid="45587218-4289-ef4e-8e6a-e5b07816b631" + wsmap="managed" + rest="managed" + reservedAttributes="8" + > + <desc> + The IUSBDeviceFilter interface represents an USB device filter used + to perform actions on a group of USB devices. + + This type of filters is used by running virtual machines to + automatically capture selected USB devices once they are physically + attached to the host computer. + + A USB device is matched to the given device filter if and only if all + attributes of the device match the corresponding attributes of the + filter (that is, attributes are joined together using the logical AND + operation). On the other hand, all together, filters in the list of + filters carry the semantics of the logical OR operation. So if it is + desirable to create a match like "this vendor id OR this product id", + one needs to create two filters and specify "any match" (see below) + for unused attributes. + + All filter attributes used for matching are strings. Each string + is an expression representing a set of values of the corresponding + device attribute, that will match the given filter. Currently, the + following filtering expressions are supported: + + <ul> + <li><i>Interval filters</i>. Used to specify valid intervals for + integer device attributes (Vendor ID, Product ID and Revision). + The format of the string is: + + <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt> + + where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal + (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>) + or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt> + is omitted before a dash (<tt>-</tt>), the minimum possible integer + is assumed; if <tt>n</tt> is omitted after a dash, the maximum + possible integer is assumed. + </li> + <li><i>Boolean filters</i>. Used to specify acceptable values for + boolean device attributes. The format of the string is: + + <tt>true|false|yes|no|0|1</tt> + + </li> + <li><i>Exact match</i>. Used to specify a single value for the given + device attribute. Any string that doesn't start with <tt>int:</tt> + represents the exact match. String device attributes are compared to + this string including case of symbols. Integer attributes are first + converted to a string (see individual filter attributes) and then + compared ignoring case. + + </li> + <li><i>Any match</i>. Any value of the corresponding device attribute + will match the given filter. An empty or @c null string is + used to construct this type of filtering expressions. + + </li> + </ul> + + <note> + On the Windows host platform, interval filters are not currently + available. Also all string filter attributes + (<link to="#manufacturer"/>, <link to="#product"/>, + <link to="#serialNumber"/>) are ignored, so they behave as + <i>any match</i> no matter what string expression is specified. + </note> + + <see><link to="IUSBDeviceFilters::deviceFilters"/>, + <link to="IHostUSBDeviceFilter"/></see> + </desc> + + <attribute name="name" type="wstring"> + <desc> + Visible name for this filter. + This name is used to visually distinguish one filter from another, + so it can neither be @c null nor an empty string. + </desc> + </attribute> + + <attribute name="active" type="boolean"> + <desc>Whether this filter active or has been temporarily disabled.</desc> + </attribute> + + <attribute name="vendorId" type="wstring"> + <desc> + <link to="IUSBDevice::vendorId">Vendor ID</link> filter. + The string representation for the <i>exact matching</i> + has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit + (including leading zeroes). + </desc> + </attribute> + + <attribute name="productId" type="wstring"> + <desc> + <link to="IUSBDevice::productId">Product ID</link> filter. + The string representation for the <i>exact matching</i> + has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit + (including leading zeroes). + </desc> + </attribute> + + <attribute name="revision" type="wstring"> + <desc> + <link to="IUSBDevice::productId">Product revision number</link> + filter. The string representation for the <i>exact matching</i> + has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit + of the integer part of the revision, and <tt>F</tt> is the + decimal digit of its fractional part (including leading and + trailing zeros). + Note that for interval filters, it's best to use the hexadecimal + form, because the revision is stored as a 16 bit packed BCD value; + so the expression <tt>int:0x0100-0x0199</tt> will match any + revision from <tt>1.0</tt> to <tt>1.99</tt>. + </desc> + </attribute> + + <attribute name="manufacturer" type="wstring"> + <desc> + <link to="IUSBDevice::manufacturer">Manufacturer</link> filter. + </desc> + </attribute> + + <attribute name="product" type="wstring"> + <desc> + <link to="IUSBDevice::product">Product</link> filter. + </desc> + </attribute> + + <attribute name="serialNumber" type="wstring"> + <desc> + <link to="IUSBDevice::serialNumber">Serial number</link> filter. + </desc> + </attribute> + + <attribute name="port" type="wstring"> + <desc> + <link to="IUSBDevice::port">Host USB port</link> filter. + </desc> + </attribute> + + <attribute name="remote" type="wstring"> + <desc> + <link to="IUSBDevice::remote">Remote state</link> filter. + <note> + This filter makes sense only for machine USB filters, + i.e. it is ignored by IHostUSBDeviceFilter objects. + </note> + </desc> + </attribute> + + <attribute name="maskedInterfaces" type="unsigned long"> + <desc> + This is an advanced option for hiding one or more USB interfaces + from the guest. The value is a bit mask where the bits that are set + means the corresponding USB interface should be hidden, masked off + if you like. + This feature only works on Linux hosts. + </desc> + </attribute> + + </interface> + + + <!-- + // IHostUSBDevice + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="USBDeviceState" + uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4" + > + <desc> + USB device state. This enumeration represents all possible states + of the USB device physically attached to the host computer regarding + its state on the host computer and availability to guest computers + (all currently running virtual machines). + + Once a supported USB device is attached to the host, global USB + filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can + either ignore the device, or put it to USBDeviceState_Held state, or do + nothing. Unless the device is ignored by global filters, filters of all + currently running guests (<link to="IUSBDeviceFilters::deviceFilters"/>) are + activated that can put it to USBDeviceState_Captured state. + + If the device was ignored by global filters, or didn't match + any filters at all (including guest ones), it is handled by the host + in a normal way. In this case, the device state is determined by + the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy + or USBDeviceState_Available, depending on the current device usage. + + Besides auto-capturing based on filters, the device can be manually + captured by guests (<link to="IConsole::attachUSBDevice"/>) if its + state is USBDeviceState_Busy, USBDeviceState_Available or + USBDeviceState_Held. + + <note> + Due to differences in USB stack implementations in Linux and Win32, + states USBDeviceState_Busy and USBDeviceState_Unavailable are applicable + only to the Linux version of the product. This also means that (<link + to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the + device state is USBDeviceState_Held. + </note> + + <see><link to="IHostUSBDevice"/>, <link to="IHostUSBDeviceFilter"/></see> + </desc> + + <const name="NotSupported" value="0"> + <desc> + Not supported by the VirtualBox server, not available to guests. + </desc> + </const> + <const name="Unavailable" value="1"> + <desc> + Being used by the host computer exclusively, + not available to guests. + </desc> + </const> + <const name="Busy" value="2"> + <desc> + Being used by the host computer, potentially available to guests. + </desc> + </const> + <const name="Available" value="3"> + <desc> + Not used by the host computer, available to guests (the host computer + can also start using the device at any time). + </desc> + </const> + <const name="Held" value="4"> + <desc> + Held by the VirtualBox server (ignored by the host computer), + available to guests. + </desc> + </const> + <const name="Captured" value="5"> + <desc> + Captured by one of the guest computers, not available + to anybody else. + </desc> + </const> + </enum> + + <interface + name="IHostUSBDevice" extends="IUSBDevice" + uuid="c19073dd-cc7b-431b-98b2-951fda8eab89" + wsmap="managed" + rest="managed" + reservedAttributes="4" + > + <desc> + The IHostUSBDevice interface represents a physical USB device attached + to the host computer. + + Besides properties inherited from IUSBDevice, this interface adds the + <link to="#state"/> property that holds the current state of the USB + device. + + <see><link to="IHost::USBDevices"/>, + <link to="IHost::USBDeviceFilters"/></see> + </desc> + + <attribute name="state" type="USBDeviceState" readonly="yes"> + <desc> + Current state of the device. + </desc> + </attribute> + + <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. --> + + </interface> + + + <!-- + // IHostUSBDeviceFilter + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="USBDeviceFilterAction" + uuid="cbc30a49-2f4e-43b5-9da6-121320475933" + > + <desc> + Actions for host USB device filters. + <see><link to="IHostUSBDeviceFilter"/>, <link to="USBDeviceState"/></see> + </desc> + + <const name="Null" value="0"> + <desc>Null value (never used by the API).</desc> + </const> + <const name="Ignore" value="1"> + <desc>Ignore the matched USB device.</desc> + </const> + <const name="Hold" value="2"> + <desc>Hold the matched USB device.</desc> + </const> + </enum> + + <interface + name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter" + uuid="01adb2d6-aedf-461c-be2c-99e91bdad8a1" + wsmap="managed" + rest="managed" + reservedAttributes="8" + > + <desc> + The IHostUSBDeviceFilter interface represents a global filter for a + physical USB device used by the host computer. Used indirectly in + <link to="IHost::USBDeviceFilters"/>. + + Using filters of this type, the host computer determines the initial + state of the USB device after it is physically attached to the + host's USB controller. + + <note> + The <link to="IUSBDeviceFilter::remote"/> attribute is ignored by this type of + filters, because it makes sense only for + <link to="IUSBDeviceFilters::deviceFilters">machine USB filters</link>. + </note> + + <see><link to="IHost::USBDeviceFilters"/></see> + </desc> + + <attribute name="action" type="USBDeviceFilterAction"> + <desc> + Action performed by the host when an attached USB device + matches this filter. + </desc> + </attribute> + + </interface> + + + <!-- + // IUSBProxyBackend + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IUSBProxyBackend" extends="$unknown" + uuid="dfe56449-6989-4002-80cf-3607f377d40c" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + The USBProxyBackend interface represents a source for USB devices available + to the host for attaching to the VM. + </desc> + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + The unique name of the proxy backend. + </desc> + </attribute> + + <attribute name="type" type="wstring" readonly="yes"> + <desc> + The type of the backend. + </desc> + </attribute> + + </interface> + + <!-- + // IAudioAdapter + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="AudioDriverType" + uuid="32b4acfd-79ab-4b7e-9a1c-92e99f4e000b" + > + <desc> + Host audio driver type. + </desc> + + <const name="Default" value="0"> + <desc>Use the default audio driver automatically determined for the host + that this VirtualBox instance is running on. + Useful for VMs which need to run on different host OSes. + </desc> + </const> + <!-- When changing the enum anyway, keep the enum grouped per platforms, starting + from oldest audio stack to newest one (if possible). --> + <const name="Null" value="1"> + <desc>Null value, also means "dummy audio driver".</desc> + </const> + <const name="OSS" value="2"> + <desc>Open Sound System (Linux / Unix hosts only).</desc> + </const> + <const name="ALSA" value="3"> + <desc>Advanced Linux Sound Architecture (Linux hosts only).</desc> + </const> + <const name="Pulse" value="4"> + <desc>PulseAudio (Linux hosts only).</desc> + </const> + <const name="WinMM" value="5"> + <desc>Windows multimedia (Windows hosts only, not supported at the moment).</desc> + </const> + <const name="DirectSound" value="6"> + <desc>DirectSound (Windows hosts only).</desc> + </const> + <const name="WAS" value="7"> + <desc>Windows Audio Session (Windows hosts only).</desc> + </const> + <const name="CoreAudio" value="8"> + <desc>CoreAudio (Mac hosts only).</desc> + </const> + <const name="MMPM" value="9"> + <desc>Reserved for historical reasons.</desc> + </const> + <const name="SolAudio" value="10"> + <desc>Reserved for historical reasons.</desc> + </const> + </enum> + + <enum + name="AudioControllerType" + uuid="7afd395c-42c3-444e-8788-3ce80292f36c" + > + <desc> + Virtual audio controller type. + </desc> + + <const name="AC97" value="0"/> + <const name="SB16" value="1"/> + <const name="HDA" value="2"/> + </enum> + + <enum + name="AudioCodecType" + uuid="7b406301-f520-420c-9805-8ce11c086370" + > + <desc> + The exact variant of audio codec hardware presented + to the guest; see <link to="IAudioAdapter::audioCodec" />. + </desc> + + <const name="Null" value="0"> + <desc>@c null value. Never used by the API.</desc> + </const> + <const name="SB16" value="1"> + <desc>SB16; this is the only option for the SB16 device.</desc> + </const> + <const name="STAC9700" value="2"> + <desc>A STAC9700 AC'97 codec.</desc> + </const> + <const name="AD1980" value="3"> + <desc>An AD1980 AC'97 codec. Recommended for Linux guests.</desc> + </const> + <const name="STAC9221" value="4"> + <desc>A STAC9221 HDA codec.</desc> + </const> + </enum> + + <interface + name="IAudioAdapter" extends="$unknown" + uuid="5155bfd3-7ba7-45a8-b26d-c91ae3754e37" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + The IAudioAdapter interface represents the virtual audio adapter of + the virtual machine. Used in <link to="IAudioSettings::adapter"/>. + </desc> + <attribute name="enabled" type="boolean"> + <desc> + Flag whether the audio adapter is present in the + guest system. If disabled, the virtual guest hardware will + not contain any audio adapter. Can only be changed when + the VM is not running. + </desc> + </attribute> + <attribute name="enabledIn" type="boolean"> + <desc> + Flag whether the audio adapter is enabled for audio + input. Only relevant if the adapter is enabled. + </desc> + </attribute> + <attribute name="enabledOut" type="boolean"> + <desc> + Flag whether the audio adapter is enabled for audio + output. Only relevant if the adapter is enabled. + </desc> + </attribute> + <attribute name="audioController" type="AudioControllerType"> + <desc> + The emulated audio controller. + </desc> + </attribute> + <attribute name="audioCodec" type="AudioCodecType"> + <desc> + The exact variant of audio codec hardware presented + to the guest. + For HDA and SB16, only one variant is available, but for AC'97, + there are several. + </desc> + </attribute> + <attribute name="audioDriver" type="AudioDriverType"> + <desc> + Audio driver the adapter is connected to. This setting + can only be changed when the VM is not running. + </desc> + </attribute> + <attribute name="propertiesList" type="wstring" readonly="yes" safearray="yes"> + <desc> + Array of names of tunable properties, which can be supported by audio driver. + </desc> + </attribute> + + <method name="setProperty"> + <desc> + Sets an audio specific property string. + + If you pass @c null or empty string as a key @a value, the given @a key + will be deleted. + + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the key to set.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc>Value to assign to the key.</desc> + </param> + </method> + + <method name="getProperty" const="yes"> + <desc> + Returns an audio specific property string. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the key to get.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc>Value of the requested key.</desc> + </param> + </method> + + </interface> + + <enum + name="AudioDirection" + uuid="f27d209b-040c-4ae9-beae-85f9693ca07a" + > + <desc> + Audio direction enumeration. + </desc> + + <const name="Unknown" value="0"> + <desc>Direction cannot be determined.</desc> + </const> + <const name="In" value="1"> + <desc>Input (Recording).</desc> + </const> + <const name="Out" value="2"> + <desc>Output (Playback).</desc> + </const> + <const name="Duplex" value="3"> + <desc>Duplex (Recording + Playback).</desc> + </const> + </enum> + + <enum + name="AudioDeviceType" + uuid="95457071-ef88-45a9-8416-fc05b08731d2" + > + <desc> + Audio device type enumeration. + </desc> + + <const name="Unknown" value="0"> + <desc>Device type is unknown / cannot be determined</desc> + </const> + <const name="BuiltLin" value="1"> + <desc>Built-in device (cannot be removed).</desc> + </const> + <const name="ExternalUSB" value="2"> + <desc>External device, connected via USB.</desc> + </const> + <const name="ExternalOther" value="3"> + <desc>External device, connected via some other method.</desc> + </const> + </enum> + + <enum + name="AudioDeviceState" + uuid="45c1b969-556a-4277-8570-b438d2ef5ebe" + > + <desc> + Audio device state enumeration. + </desc> + + <const name="Unknown" value="0"> + <desc>Device state is unknown / cannot be determined</desc> + </const> + <const name="Active" value="1"> + <desc>Device is active and can be used.</desc> + </const> + <const name="Disabled" value="2"> + <desc>Device is in a disabled state.</desc> + </const> + <const name="NotPresent" value="3"> + <desc>Device is marked as not being present.</desc> + </const> + <const name="Unplugged" value="4"> + <desc>Device has been unplugged.</desc> + </const> + </enum> + + <interface + name="IHostAudioDevice" extends="$unknown" + uuid="cfde1265-3140-4048-a81f-a1e280dfbd75" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + Represents an audio device provided by the host OS. + </desc> + + <attribute name="id" type="uuid" mod="string" readonly="yes"> + <desc> + Unique device ID. + </desc> + </attribute> + + <attribute name="name" type="wstring"> + <desc> + Friendly name of the device. + </desc> + </attribute> + <attribute name="type" type="AudioDeviceType"> + <desc> + Device type. + </desc> + </attribute> + <attribute name="usage" type="AudioDirection"> + <desc> + Usage type of the device. + </desc> + </attribute> + <attribute name="defaultIn" type="boolean"> + <desc> + Whether this device is being marked as the default input + device by the host OS. + </desc> + </attribute> + <attribute name="defaultOut" type="boolean"> + <desc> + Whether this device is being marked as the default output + device by the host OS. + </desc> + </attribute> + <attribute name="isHotPlug" type="boolean"> + <desc> + Whether this device is being marked as a hotplug device, i.e. can + be removed from the system. + </desc> + </attribute> + <attribute name="state" type="AudioDeviceState"> + <desc> + Current device state. + </desc> + </attribute> + <method name="getProperty" const="yes"> + <desc> + Returns an audio specific property string. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the key to get.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc>Value of the requested key.</desc> + </param> + </method> + + </interface> + + <interface + name="IAudioSettings" extends="$unknown" + uuid="52f40b16-520e-473f-9428-3e69b0d915c3" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + The IAudioSettings interface represents the audio settings for a virtual machine. + </desc> + + <method name="getHostAudioDevice"> + <desc> + Returns the machine's current host audio device for the specified usage. + <result name="E_NOTIMPL"> + This method is not implemented yet. + </result> + </desc> + <param name="usage" type="AudioDirection" dir="in"> + <desc>Usage to retrieve audio device for.</desc> + </param> + <param name="device" type="IHostAudioDevice" dir="return"> + <desc>Host audio device for the specified direction.</desc> + </param> + </method> + + <method name="setHostAudioDevice"> + <desc> + Sets the machine's current host audio device for the specified usage. + <result name="E_NOTIMPL"> + This method is not implemented yet. + </result> + </desc> + <param name="device" type="IHostAudioDevice" dir="in"> + <desc>Sets the host audio device for the specified usage.</desc> + </param> + <param name="usage" type="AudioDirection" dir="in"> + <desc>Usage to set audio device for.</desc> + </param> + </method> + + <attribute name="adapter" type="IAudioAdapter" readonly="yes"> + <desc>Associated audio adapter, always present.</desc> + </attribute> + + </interface> + + <enum + name="AuthType" + uuid="7eef6ef6-98c2-4dc2-ab35-10d2b292028d" + > + <desc> + VirtualBox authentication type. + </desc> + + <const name="Null" value="0"> + <desc>Null value, also means "no authentication".</desc> + </const> + <const name="External" value="1"/> + <const name="Guest" value="2"/> + </enum> + + <!-- + // IVRDEServer + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IVRDEServer" extends="$unknown" + uuid="08e25756-08a2-41af-a05f-d7c661abaebe" + wsmap="managed" + rest="managed" + reservedMethods="2" reservedAttributes="4" + > + + <attribute name="enabled" type="boolean"> + <desc>Flag if VRDE server is enabled.</desc> + </attribute> + + <attribute name="authType" type="AuthType"> + <desc>VRDE authentication method.</desc> + </attribute> + + <attribute name="authTimeout" type="unsigned long"> + <desc>Timeout for guest authentication. Milliseconds.</desc> + </attribute> + + <attribute name="allowMultiConnection" type="boolean"> + <desc> + Flag whether multiple simultaneous connections to the VM are permitted. + Note that this will be replaced by a more powerful mechanism in the future. + </desc> + </attribute> + + <attribute name="reuseSingleConnection" type="boolean"> + <desc> + Flag whether the existing connection must be dropped and a new connection + must be established by the VRDE server, when a new client connects in single + connection mode. + </desc> + </attribute> + + <attribute name="VRDEExtPack" type="wstring"> + <desc> + The name of Extension Pack providing VRDE for this VM. Overrides + <link to="ISystemProperties::defaultVRDEExtPack"/>. + </desc> + </attribute> + + <attribute name="authLibrary" type="wstring"> + <desc> + Library used for authentication of RDP clients by this VM. Overrides + <link to="ISystemProperties::VRDEAuthLibrary"/>. + </desc> + </attribute> + + <attribute name="VRDEProperties" type="wstring" readonly="yes" safearray="yes"> + <desc> + Array of names of properties, which are supported by this VRDE server. + </desc> + </attribute> + + <method name="setVRDEProperty"> + <desc> + Sets a VRDE specific property string. + + If you pass @c null or empty string as a key @a value, the given @a key + will be deleted. + + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the key to set.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc>Value to assign to the key.</desc> + </param> + </method> + + <method name="getVRDEProperty" const="yes"> + <desc> + Returns a VRDE specific property string. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + </desc> + <param name="key" type="wstring" dir="in"> + <desc>Name of the key to get.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc>Value of the requested key.</desc> + </param> + </method> + + </interface> + + + <!-- + // ISharedFolder + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="ISharedFolder" extends="$unknown" + uuid="9622225a-5409-414b-bd16-77df7ba3451e" + wsmap="managed" + rest="managed" + reservedAttributes="8" + > + <desc> + The ISharedFolder interface represents a folder in the host computer's + file system accessible from the guest OS running inside a virtual + machine using an associated logical name. + + There are three types of shared folders: + <ul> + <li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared + folders available to all virtual machines.</li> + <li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>), + VM-specific shared folders available to the given virtual machine at + startup.</li> + <li><i>Transient</i> (<link to="IConsole::sharedFolders"/>), + VM-specific shared folders created in the session context (for + example, when the virtual machine is running) and automatically + discarded when the session is closed (the VM is powered off).</li> + </ul> + + Logical names of shared folders must be unique within the given scope + (global, permanent or transient). However, they do not need to be unique + across scopes. In this case, the definition of the shared folder in a + more specific scope takes precedence over definitions in all other + scopes. The order of precedence is (more specific to more general): + <ol> + <li>Transient definitions</li> + <li>Permanent definitions</li> + <li>Global definitions</li> + </ol> + + For example, if MyMachine has a shared folder named + <tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a + transient shared folder named <tt>C_DRIVE</tt> (that points + to <tt>C:\\\\WINDOWS</tt>) will change the definition + of <tt>C_DRIVE</tt> in the guest OS so + that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access + to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host + PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore + the previous (permanent) definition of <tt>C_DRIVE</tt> that points + to <tt>C:\\</tt> if it still exists. + + Note that permanent and transient shared folders of different machines + are in different name spaces, so they don't overlap and don't need to + have unique logical names. + + <note> + Global shared folders are not implemented in the current version of the + product. + </note> + </desc> + + <attribute name="name" type="wstring" readonly="yes"> + <desc>Logical name of the shared folder.</desc> + </attribute> + + <attribute name="hostPath" type="wstring" readonly="yes"> + <desc>Full path to the shared folder in the host file system.</desc> + </attribute> + + <attribute name="accessible" type="boolean" readonly="yes"> + <desc> + Whether the folder defined by the host path is currently + accessible or not. + + For example, the folder can be inaccessible if it is placed + on the network share that is not available by the time + this property is read. + </desc> + </attribute> + + <attribute name="writable" type="boolean"> + <desc> + Whether the folder defined by the host path is writable or + not. + </desc> + </attribute> + + <attribute name="autoMount" type="boolean"> + <desc> + Whether the folder gets automatically mounted by the guest or not. + </desc> + </attribute> + + <attribute name="autoMountPoint" type="wstring"> + <desc> + Desired mount point in the guest for automatically mounting the folder + when <link to="ISharedFolder::autoMount"/> is set. For Windows and + OS/2 guests this should be a drive letter, while other guests it should + be a absolute directory. It is possible to combine the two, e.g. + "T:/mnt/testrsrc" will be attached to "T:" by windows and OS/2 while + the unixy guests will mount it at "/mnt/testrsrc". + + When empty the guest will choose a mount point. The guest may do so + too should the specified mount point be in use or otherwise unusable. + </desc> + </attribute> + + <attribute name="lastAccessError" type="wstring" readonly="yes"> + <desc> + Text message that represents the result of the last accessibility + check. + + Accessibility checks are performed each time the <link to="#accessible"/> + attribute is read. An empty string is returned if the last + accessibility check was successful. A non-empty string indicates a + failure and should normally describe a reason of the failure (for + example, a file read error). + </desc> + </attribute> + + </interface> + + <!-- + // ISession + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="Reason" + uuid="e7e8e097-299d-4e98-8bbc-c31c2d47d0cc" + > + <desc> + Internal event reason type. + </desc> + + <const name="Unspecified" value="0"> + <desc>Null value, means "no known reason".</desc> + </const> + <const name="HostSuspend" value="1"> + <desc>Host is being suspended (power management event).</desc> + </const> + <const name="HostResume" value="2"> + <desc>Host is being resumed (power management event).</desc> + </const> + <const name="HostBatteryLow" value="3"> + <desc>Host is running low on battery (power management event).</desc> + </const> + <const name="Snapshot" value="4"> + <desc>A snapshot of the VM is being taken.</desc> + </const> + </enum> + + <interface + name="IInternalSessionControl" extends="$unknown" + uuid="5045c372-2e8f-4d9e-ad9d-121ab1661146" + internal="yes" + wsmap="suppress" + > + <attribute name="PID" type="unsigned long" readonly="yes"> + <desc>PID of the process that has created this Session object. + </desc> + </attribute> + + <attribute name="remoteConsole" type="IConsole" readonly="yes"> + <desc> + Returns the console object suitable for remote control. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + </attribute> + + <attribute name="nominalState" type="MachineState" readonly="yes"> + <desc>Returns suitable machine state for the VM execution state. Useful + for choosing a sensible machine state after a complex operation which + failed or otherwise resulted in an unclear situation. + </desc> + </attribute> + +<if target="midl"> + <method name="assignMachine"> + <desc> + Assigns the machine object associated with this direct-type + session or informs the session that it will be a remote one + (if @a machine == @c null). + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="machine" type="IMachine" dir="in"/> + <param name="lockType" type="LockType" dir="in"/> + <param name="tokenId" type="wstring" dir="in"/> + </method> +</if> +<if target="xpidl"> + <method name="assignMachine"> + <desc> + Assigns the machine object associated with this direct-type + session or informs the session that it will be a remote one + (if @a machine == @c null). + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="machine" type="IMachine" dir="in"/> + <param name="lockType" type="LockType" dir="in"/> + <param name="token" type="IToken" dir="in"/> + </method> +</if> + + <method name="assignRemoteMachine"> + <desc> + Assigns the machine and the (remote) console object associated with + this remote-type session. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + + </desc> + <param name="machine" type="IMachine" dir="in"/> + <param name="console" type="IConsole" dir="in"/> + </method> + + <method name="updateMachineState"> + <desc> + Updates the machine state in the VM process. + Must be called only in certain cases + (see the method implementation). + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="machineState" type="MachineState" dir="in"/> + </method> + + <method name="uninitialize"> + <desc> + Uninitializes (closes) this session. Used by VirtualBox to close + the corresponding remote session when the direct session dies + or gets closed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + + </desc> + </method> + + <method name="onNetworkAdapterChange"> + <desc> + Triggered when settings of a network adapter of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="networkAdapter" type="INetworkAdapter" dir="in"/> + <param name="changeAdapter" type="boolean" dir="in"/> + </method> + + <method name="onAudioAdapterChange"> + <desc> + Triggerd when settings of the audio adapter of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="audioAdapter" type="IAudioAdapter" dir="in"/> + </method> + + <method name="onHostAudioDeviceChange"> + <desc> + Triggerd when the state of a host audio device + has changed. + </desc> + <param name="device" type="IHostAudioDevice" dir="in" readonly="yes"> + <desc>Device the state has been changed for.</desc> + </param> + <param name="isNew" type="boolean" dir="in" readonly="yes"> + <desc>Whether this is a newly detected device or not.</desc> + </param> + <param name="state" type="AudioDeviceState" dir="in" readonly="yes"> + <desc>The new device state.</desc> + </param> + <param name="errorInfo" type="IVirtualBoxErrorInfo" dir="in" readonly="yes"> + <desc>Error information.</desc> + </param> + </method> + + <method name="onSerialPortChange"> + <desc> + Triggered when settings of a serial port of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="serialPort" type="ISerialPort" dir="in"/> + </method> + + <method name="onParallelPortChange"> + <desc> + Triggered when settings of a parallel port of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="parallelPort" type="IParallelPort" dir="in"/> + </method> + + <method name="onStorageControllerChange"> + <desc> + Triggered when settings of a storage controller of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="machineId" type="uuid" mod="string" dir="in"> + <desc>The id of the machine containing the storage controller.</desc> + </param> + <param name="controllerName" type="wstring" dir="in"> + <desc>The name of the storage controller.</desc> + </param> + </method> + + <method name="onMediumChange"> + <desc> + Triggered when attached media of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + + <param name="mediumAttachment" type="IMediumAttachment" dir="in"> + <desc>The medium attachment which changed.</desc> + </param> + <param name="force" type="boolean" dir="in"> + <desc>If the medium change was forced.</desc> + </param> + </method> + + <method name="onStorageDeviceChange"> + <desc> + Triggered when attached storage devices of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + + <param name="mediumAttachment" type="IMediumAttachment" dir="in"> + <desc>The medium attachment which changed.</desc> + </param> + <param name="remove" type="boolean" dir="in"> + <desc>TRUE if the device is removed, FALSE if it was added.</desc> + </param> + <param name="silent" type="boolean" dir="in"> + <desc>TRUE if the device is is silently reconfigured without + notifying the guest about it.</desc> + </param> + </method> + + <method name="onVMProcessPriorityChange"> + <desc> + Triggered when process priority of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + <result name="VBOX_E_VM_ERROR"> + Error from underlying level. See additional error info. + </result> + + </desc> + + <param name="priority" type="VMProcPriority" dir="in"> + <desc>The priority which set.</desc> + </param> + </method> + + <method name="onClipboardModeChange"> + <desc> + Notification when the shared clipboard mode changes. + </desc> + <param name="clipboardMode" type="ClipboardMode" dir="in"> + <desc>The new shared clipboard mode.</desc> + </param> + </method> + + <method name="onClipboardFileTransferModeChange"> + <desc> + Notification when the shared clipboard file transfers mode changes. + </desc> + <param name="enabled" type="boolean" dir="in"> + <desc>Flag whether clipboard file transfers are allowed or not.</desc> + </param> + </method> + + <method name="onDnDModeChange"> + <desc> + Notification when the drag'n drop mode changes. + </desc> + <param name="dndMode" type="DnDMode" dir="in"> + <desc>The new mode for drag'n drop.</desc> + </param> + </method> + + <method name="onCPUChange"> + <desc> + Notification when a CPU changes. + </desc> + <param name="cpu" type="unsigned long" dir="in"> + <desc>The CPU which changed</desc> + </param> + <param name="add" type="boolean" dir="in"> + <desc>Flag whether the CPU was added or removed</desc> + </param> + </method> + + <method name="onCPUExecutionCapChange"> + <desc> + Notification when the CPU execution cap changes. + </desc> + <param name="executionCap" type="unsigned long" dir="in"> + <desc>The new CPU execution cap value. (1-100)</desc> + </param> + </method> + + <method name="onVRDEServerChange"> + <desc> + Triggered when settings of the VRDE server object of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="restart" type="boolean" dir="in"> + <desc>Flag whether the server must be restarted</desc> + </param> + </method> + + <method name="onRecordingChange"> + <desc> + Triggered when recording settings have changed. + </desc> + <param name="enable" type="boolean" dir="in"> + <desc>TODO</desc> + </param> + </method> + + <method name="onUSBControllerChange"> + <desc> + Triggered when settings of the USB controller object of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + </method> + + <method name="onSharedFolderChange"> + <desc> + Triggered when a permanent (global or machine) shared folder has been + created or removed. + <note> + We don't pass shared folder parameters in this notification because + the order in which parallel notifications are delivered is not defined, + therefore it could happen that these parameters were outdated by the + time of processing this notification. + </note> + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="global" type="boolean" dir="in"/> + </method> + + <method name="onGuestDebugControlChange"> + <desc> + Triggered when settings of the guest debug settings of the + associated virtual machine have changed. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="guestDebugControl" type="IGuestDebugControl" dir="in"/> + </method> + + <method name="onUSBDeviceAttach"> + <desc> + Triggered when a request to capture a USB device (as a result + of matched USB filters or direct call to + <link to="IConsole::attachUSBDevice"/>) has completed. + A @c null @a error object means success, otherwise it + describes a failure. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="device" type="IUSBDevice" dir="in"/> + <param name="error" type="IVirtualBoxErrorInfo" dir="in"/> + <param name="maskedInterfaces" type="unsigned long" dir="in"/> + <param name="captureFilename" type="wstring" dir="in"/> + </method> + + <method name="onUSBDeviceDetach"> + <desc> + Triggered when a request to release the USB device (as a result + of machine termination or direct call to + <link to="IConsole::detachUSBDevice"/>) has completed. + A @c null @a error object means success, otherwise it + describes a failure. + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="id" type="uuid" mod="string" dir="in"/> + <param name="error" type="IVirtualBoxErrorInfo" dir="in"/> + </method> + + <method name="onShowWindow"> + <desc> + Called by <link to="IMachine::canShowConsoleWindow"/> and by + <link to="IMachine::showConsoleWindow"/> in order to notify + console listeners + <link to="ICanShowWindowEvent"/> + and <link to="IShowWindowEvent"/>. + + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="check" type="boolean" dir="in"/> + <param name="canShow" type="boolean" dir="out"/> + <param name="winId" type="long long" dir="out"/> + </method> + + <method name="onBandwidthGroupChange"> + <desc> + Notification when one of the bandwidth groups change. + </desc> + <param name="bandwidthGroup" type="IBandwidthGroup" dir="in"> + <desc>The bandwidth group which changed.</desc> + </param> + </method> + + <method name="accessGuestProperty"> + <desc> + Called by <link to="IMachine::getGuestProperty"/> and by + <link to="IMachine::setGuestProperty"/> in order to read and + modify guest properties. + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type is not direct. + </result> + + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of guest property.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc>Value of guest property.</desc> + </param> + <param name="flags" type="wstring" dir="in"> + <desc>Flags of guest property.</desc> + </param> + <param name="accessMode" type="unsigned long" dir="in"> + <desc>0 = get, 1 = set, 2 = delete.</desc> + </param> + <param name="retValue" type="wstring" dir="out"> + <desc>When getting: Value of guest property.</desc> + </param> + <param name="retTimestamp" type="long long" dir="out"> + <desc>When getting: Timestamp of guest property.</desc> + </param> + <param name="retFlags" type="wstring" dir="out"> + <desc>When getting: Flags of guest property.</desc> + </param> + </method> + + <method name="enumerateGuestProperties" const="yes"> + <desc> + Return a list of the guest properties matching a set of patterns along + with their values, timestamps and flags. + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type is not direct. + </result> + + </desc> + <param name="patterns" type="wstring" dir="in"> + <desc> + The patterns to match the properties against as a comma-separated + string. If this is empty, all properties currently set will be + returned. + </desc> + </param> + <param name="keys" type="wstring" dir="out" safearray="yes"> + <desc> + The key names of the properties returned. + </desc> + </param> + <param name="values" type="wstring" dir="out" safearray="yes"> + <desc> + The values of the properties returned. The array entries match the + corresponding entries in the @a key array. + </desc> + </param> + <param name="timestamps" type="long long" dir="out" safearray="yes"> + <desc> + The timestamps of the properties returned. The array entries match + the corresponding entries in the @a key array. + </desc> + </param> + <param name="flags" type="wstring" dir="out" safearray="yes"> + <desc> + The flags of the properties returned. The array entries match the + corresponding entries in the @a key array. + </desc> + </param> + </method> + + <method name="onlineMergeMedium"> + <desc> + Triggers online merging of a hard disk. Used internally when deleting + a snapshot while a VM referring to the same hard disk chain is running. + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type is not direct. + </result> + + </desc> + <param name="mediumAttachment" type="IMediumAttachment" dir="in"> + <desc>The medium attachment to identify the medium chain.</desc> + </param> + <param name="sourceIdx" type="unsigned long" dir="in"> + <desc>The index of the source image in the chain. + Redundant, but drastically reduces IPC.</desc> + </param> + <param name="targetIdx" type="unsigned long" dir="in"> + <desc>The index of the target image in the chain. + Redundant, but drastically reduces IPC.</desc> + </param> + <param name="progress" type="IProgress" dir="in"> + <desc> + Progress object for this operation. + </desc> + </param> + </method> + + <method name="reconfigureMediumAttachments"> + <desc> + Reconfigure all specified medium attachments in one go, making sure + the current state corresponds to the specified medium. + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type is not direct. + </result> + </desc> + <param name="attachments" type="IMediumAttachment" dir="in" safearray="yes"> + <desc>Array containing the medium attachments which need to be + reconfigured.</desc> + </param> + </method> + + <method name="enableVMMStatistics"> + <desc> + Enables or disables collection of VMM RAM statistics. + + <result name="VBOX_E_INVALID_VM_STATE"> + Machine session is not open. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type is not direct. + </result> + + </desc> + <param name="enable" type="boolean" dir="in"> + <desc>True enables statistics collection.</desc> + </param> + </method> + + <method name="pauseWithReason"> + <desc> + Internal method for triggering a VM pause with a specified reason code. + The reason code can be interpreted by device/drivers and thus it might + behave slightly differently than a normal VM pause. + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Running state. + </result> + <result name="VBOX_E_VM_ERROR"> + Virtual machine error in suspend operation. + </result> + <see><link to="IConsole::pause"/></see> + </desc> + + <param name="reason" type="Reason" dir="in"> + <desc>Specify the best matching reason code please.</desc> + </param> + </method> + + <method name="resumeWithReason"> + <desc> + Internal method for triggering a VM resume with a specified reason code. + The reason code can be interpreted by device/drivers and thus it might + behave slightly differently than a normal VM resume. + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Paused state. + </result> + <result name="VBOX_E_VM_ERROR"> + Virtual machine error in resume operation. + </result> + <see><link to="IConsole::resume"/></see> + </desc> + + <param name="reason" type="Reason" dir="in"> + <desc>Specify the best matching reason code please.</desc> + </param> + </method> + + <method name="saveStateWithReason"> + <desc> + Internal method for triggering a VM save state with a specified reason + code. The reason code can be interpreted by device/drivers and thus it + might behave slightly differently than a normal VM save state. + + This call is fully synchronous, and the caller is expected to have set + the machine state appropriately (and has to set the follow-up machine + state if this call failed). + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine state is not one of the expected values. + </result> + <result name="VBOX_E_FILE_ERROR"> + Failed to create directory for saved state file. + </result> + <see><link to="IMachine::saveState"/></see> + </desc> + + <param name="reason" type="Reason" dir="in"> + <desc>Specify the best matching reason code please.</desc> + </param> + <param name="progress" type="IProgress" dir="in"> + <desc>Progress object to track the operation completion.</desc> + </param> + <param name="snapshot" type="ISnapshot" dir="in"> + <desc>Snapshot object for which this save state operation is executed.</desc> + </param> + <param name="stateFilePath" type="wstring" dir="in"> + <desc>File path the VM process must save the execution state to.</desc> + </param> + <param name="pauseVM" type="boolean" dir="in"> + <desc>The VM should be paused before saving state. It is automatically + unpaused on error in the "vanilla save state" case.</desc> + </param> + <param name="leftPaused" type="boolean" dir="return"> + <desc>Returns if the VM was left in paused state, which is necessary + in many situations (snapshots, teleportation).</desc> + </param> + </method> + + <method name="cancelSaveStateWithReason"> + <desc> + Internal method for cancelling a VM save state. + <see><link to="IInternalSessionControl::saveStateWithReason"/></see> + </desc> + </method> + + </interface> + + <interface + name="ISession" extends="$unknown" + uuid="c0447716-ff5a-4795-b57a-ecd5fffa18a4" + wsmap="managed" + rest="managed" + wrap-hint-server-addinterfaces="IInternalSessionControl" + reservedMethods="4" reservedAttributes="8" + > + <desc> + The ISession interface represents a client process and allows for locking + virtual machines (represented by IMachine objects) to prevent conflicting + changes to the machine. + + Any caller wishing to manipulate a virtual machine needs to create a session + object first, which lives in its own process space. Such session objects are + then associated with <link to="IMachine" /> objects living in the VirtualBox + server process to coordinate such changes. + + There are two typical scenarios in which sessions are used: + + <ul> + <li>To alter machine settings or control a running virtual machine, one + needs to lock a machine for a given session (client process) by calling + <link to="IMachine::lockMachine"/>. + + Whereas multiple sessions may control a running virtual machine, only + one process can obtain a write lock on the machine to prevent conflicting + changes. A write lock is also needed if a process wants to actually run a + virtual machine in its own context, such as the VirtualBox GUI or + VBoxHeadless front-ends. They must also lock a machine for their own + sessions before they are allowed to power up the virtual machine. + + As a result, no machine settings can be altered while another process is + already using it, either because that process is modifying machine settings + or because the machine is running. + </li> + <li>To start a VM using one of the existing VirtualBox front-ends (e.g. the + VirtualBox GUI or VBoxHeadless), one would use + <link to="IMachine::launchVMProcess"/>, which also takes a session object + as its first parameter. This session then identifies the caller and lets the + caller control the started machine (for example, pause machine execution or + power it down) as well as be notified about machine execution state changes. + </li> + </ul> + + How sessions objects are created in a client process depends on whether you use + the Main API via COM or via the webservice: + + <ul> + <li>When using the COM API directly, an object of the Session class from the + VirtualBox type library needs to be created. In regular COM C++ client code, + this can be done by calling <tt>createLocalObject()</tt>, a standard COM API. + This object will then act as a local session object in further calls to open + a session. + </li> + + <li>In the webservice, the session manager (IWebsessionManager) instead creates + a session object automatically whenever <link to="IWebsessionManager::logon" /> + is called. A managed object reference to that session object can be retrieved by + calling <link to="IWebsessionManager::getSessionObject" />. + </li> + </ul> + </desc> + + <attribute name="state" type="SessionState" readonly="yes"> + <desc>Current state of this session.</desc> + </attribute> + + <attribute name="type" type="SessionType" readonly="yes"> + <desc> + Type of this session. The value of this attribute is valid only + if the session currently has a machine locked (i.e. its + <link to="#state" /> is Locked), otherwise an error will be returned. + </desc> + </attribute> + + <attribute name="name" type="wstring"> + <desc> + Name of this session. Important only for VM sessions, otherwise it + it will be remembered, but not used for anything significant (and can + be left at the empty string which is the default). The value can only + be changed when the session state is SessionState_Unlocked. Make sure + that you use a descriptive name which does not conflict with the VM + process session names: "GUI/Qt", "GUI/SDL" and "headless". + </desc> + </attribute> + + <attribute name="machine" type="IMachine" readonly="yes" rest="uuid"> + <desc>Machine object associated with this session.</desc> + </attribute> + + <attribute name="console" type="IConsole" readonly="yes"> + <desc>Console object associated with this session. Only sessions + which locked the machine for a VM process have a non-null console.</desc> + </attribute> + + <method name="unlockMachine"> + <desc> + Unlocks a machine that was previously locked for the current session. + + Calling this method is required every time a machine has been locked + for a particular session using the <link to="IMachine::launchVMProcess" /> + or <link to="IMachine::lockMachine" /> calls. Otherwise the state of + the machine will be set to <link to="MachineState_Aborted" /> on the + server, and changes made to the machine settings will be lost. + + Generally, it is recommended to unlock all machines explicitly + before terminating the application (regardless of the reason for + the termination). + + <note> + Do not expect the session state (<link to="ISession::state" /> + to return to "Unlocked" immediately after you invoke this method, + particularly if you have started a new VM process. The session + state will automatically return to "Unlocked" once the VM is no + longer executing, which can of course take a very long time. + </note> + + <result name="E_UNEXPECTED"> + Session is not locked. + </result> + + </desc> + </method> + + </interface> + + <!-- + // IStorageController + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="StorageBus" + uuid="f9510869-7d07-46ba-96a6-6728fbf4adee" + > + <desc> + The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy); + see <link to="IStorageController::bus" />. + </desc> + <const name="Null" value="0"> + <desc>@c null value. Never used by the API.</desc> + </const> + <const name="IDE" value="1"/> + <const name="SATA" value="2"/> + <const name="SCSI" value="3"/> + <const name="Floppy" value="4"/> + <const name="SAS" value="5"/> + <const name="USB" value="6"/> + <const name="PCIe" value="7"/> + <const name="VirtioSCSI" value="8"/> + </enum> + + <enum + name="StorageControllerType" + uuid="a77d457d-66a3-4368-b24c-293d0f562a9f" + > + <desc> + The exact variant of storage controller hardware presented + to the guest; see <link to="IStorageController::controllerType" />. + </desc> + + <const name="Null" value="0"> + <desc>@c null value. Never used by the API.</desc> + </const> + <const name="LsiLogic" value="1"> + <desc>A SCSI controller of the LsiLogic variant.</desc> + </const> + <const name="BusLogic" value="2"> + <desc>A SCSI controller of the BusLogic variant.</desc> + </const> + <const name="IntelAhci" value="3"> + <desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc> + </const> + <const name="PIIX3" value="4"> + <desc>An IDE controller of the PIIX3 variant.</desc> + </const> + <const name="PIIX4" value="5"> + <desc>An IDE controller of the PIIX4 variant.</desc> + </const> + <const name="ICH6" value="6"> + <desc>An IDE controller of the ICH6 variant.</desc> + </const> + <const name="I82078" value="7"> + <desc>A floppy disk controller; this is the only variant for floppy drives.</desc> + </const> + <const name="LsiLogicSas" value="8"> + <desc>A variant of the LsiLogic controller using SAS.</desc> + </const> + <const name="USB" value="9"> + <desc>Special USB based storage controller.</desc> + </const> + <const name="NVMe" value="10"> + <desc>An NVMe storage controller.</desc> + </const> + <const name="VirtioSCSI" value="11"> + <desc>Virtio SCSI storage controller.</desc> + </const> + </enum> + + <enum + name="ChipsetType" + uuid="8b4096a8-a7c3-4d3b-bbb1-05a0a51ec394" + > + <desc> + Type of emulated chipset (mostly southbridge). + </desc> + + <const name="Null" value="0"> + <desc>@c null value. Never used by the API.</desc> + </const> + <const name="PIIX3" value="1"> + <desc>A PIIX3 (PCI IDE ISA Xcelerator) chipset.</desc> + </const> + <const name="ICH9" value="2"> + <desc>A ICH9 (I/O Controller Hub) chipset.</desc> + </const> + </enum> + + <interface + name="IStorageController" extends="$unknown" + uuid="ddca7247-bf98-47fb-ab2f-b5177533f493" + wsmap="managed" + reservedMethods="4" reservedAttributes="8" + rest="managed" + > + <desc> + Represents a storage controller that is attached to a virtual machine + (<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are + attached to storage controllers in a real computer, virtual drives + (represented by <link to="IMediumAttachment" />) are attached to virtual + storage controllers, represented by this interface. + + As opposed to physical hardware, VirtualBox has a very generic concept + of a storage controller, and for purposes of the Main API, all virtual + storage is attached to virtual machines via instances of this interface. + There are five types of such virtual storage controllers: IDE, SCSI, SATA, + SAS and Floppy (see <link to="#bus" />). Depending on which of these four + is used, certain sub-types may be available and can be selected in + <link to="#controllerType" />. + + Depending on these settings, the guest operating system might see + significantly different virtual hardware. + </desc> + + <attribute name="name" type="wstring"> + <desc> + Name of the storage controller, as originally specified with + <link to="IMachine::addStorageController" />. This then uniquely + identifies this controller with other method calls such as + <link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />. + </desc> + </attribute> + + <attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes"> + <desc> + Maximum number of devices which can be attached to one port. + </desc> + </attribute> + + <attribute name="minPortCount" type="unsigned long" readonly="yes"> + <desc> + Minimum number of ports that <link to="IStorageController::portCount"/> can be set to. + </desc> + </attribute> + + <attribute name="maxPortCount" type="unsigned long" readonly="yes"> + <desc> + Maximum number of ports that <link to="IStorageController::portCount"/> can be set to. + </desc> + </attribute> + + <attribute name="instance" type="unsigned long"> + <desc> + The instance number of the device in the running VM. + </desc> + </attribute> + + <attribute name="portCount" type="unsigned long"> + <desc> + The number of currently usable ports on the controller. + The minimum and maximum number of ports for one controller are + stored in <link to="IStorageController::minPortCount"/> + and <link to="IStorageController::maxPortCount"/>. + </desc> + </attribute> + + <attribute name="bus" type="StorageBus" readonly="yes"> + <desc> + The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy). + </desc> + </attribute> + + <attribute name="controllerType" type="StorageControllerType"> + <desc> + The exact variant of storage controller hardware presented + to the guest. + Depending on this value, VirtualBox will provide a different + virtual storage controller hardware to the guest. + For SATA, SAS and floppy controllers, only one variant is + available, but for IDE and SCSI, there are several. + + For SCSI controllers, the default type is LsiLogic. + </desc> + </attribute> + + <attribute name="useHostIOCache" type="boolean"> + <desc> + If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O + caches and use synchronous file APIs on the host. This was the only option in the API before + VirtualBox 3.2 and is still the default for IDE controllers. + + If false, the host I/O cache will be disabled for image files attached to this storage controller. + Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes + it possible to turn off the host I/O caches because the emulation can handle unaligned access to + the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many + virtual machines are running at the same time to prevent I/O cache related hangs. + This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers. + </desc> + </attribute> + + <attribute name="bootable" type="boolean" readonly="yes"> + <desc> + Returns whether it is possible to boot from disks attached to this controller. + </desc> + </attribute> + </interface> + +<if target="wsdl"> + + <!-- + // IManagedObjectRef + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IManagedObjectRef" extends="$unknown" + uuid="9474d09d-2313-46de-b568-a42b8718e8ed" + internal="yes" + wsmap="managed" + wscpp="hardcoded" + > + <desc> + Managed object reference. + + Only within the webservice, a managed object reference (which is really + an opaque number) allows a webservice client to address an object + that lives in the address space of the webservice server. + + Behind each managed object reference, there is a COM object that lives + in the webservice server's address space. The COM object is not freed + until the managed object reference is released, either by an explicit + call to <link to="IManagedObjectRef::release" /> or by logging off from + the webservice (<link to="IWebsessionManager::logoff" />), which releases + all objects created during the webservice session. + + Whenever a method call of the VirtualBox API returns a COM object, the + webservice representation of that method will instead return a + managed object reference, which can then be used to invoke methods + on that object. + </desc> + + <method name="getInterfaceName"> + <desc> + Returns the name of the interface that this managed object represents, + for example, "IMachine", as a string. + </desc> + <param name="return" type="wstring" dir="return"/> + </method> + + <method name="release"> + <desc> + Releases this managed object reference and frees the resources that + were allocated for it in the webservice server process. After calling + this method, the identifier of the reference can no longer be used. + </desc> + </method> + + </interface> + + <!-- + // IWebsessionManager + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IWebsessionManager" extends="$unknown" + uuid="930c8fea-453a-4a65-aca9-19ed9a872f88" + internal="yes" + wsmap="global" + wscpp="hardcoded" + > + <desc> + Websession manager. This provides essential services + to webservice clients. + </desc> + <method name="logon"> + <desc> + Logs a new client onto the webservice and returns a managed object reference to + the IVirtualBox instance, which the client can then use as a basis to further + queries, since all calls to the VirtualBox API are based on the IVirtualBox + interface, in one way or the other. + </desc> + <param name="username" type="wstring" dir="in"/> + <param name="password" type="wstring" dir="in"/> + <param name="return" type="IVirtualBox" dir="return"/> + </method> + + <method name="getSessionObject"> + <desc> + Returns a managed object reference to a new ISession object for every + call to this method. + + <see><link to="ISession"/></see> + </desc> + <param name="refIVirtualBox" type="IVirtualBox" dir="in"/> + <param name="return" type="ISession" dir="return"/> + </method> + + <method name="logoff"> + <desc> + Logs off the client who has previously logged on with <link to="IWebsessionManager::logon" /> + and destroys all resources associated with the websession (most + importantly, all managed objects created in the server while the + websession was active). + </desc> + <param name="refIVirtualBox" type="IVirtualBox" dir="in"/> + </method> + + </interface> + +</if> + + <!-- + // IPerformanceCollector & friends + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IPerformanceMetric" extends="$unknown" + uuid="81314d14-fd1c-411a-95c5-e9bb1414e632" wsmap="managed" + rest="managed" + reservedAttributes="8" + > + <desc> + The IPerformanceMetric interface represents parameters of the given + performance metric. + </desc> + + <attribute name="metricName" type="wstring" readonly="yes"> + <desc> + Name of the metric. + </desc> + </attribute> + + <attribute name="object" type="$unknown" readonly="yes"> + <desc> + Object this metric belongs to. + </desc> + </attribute> + + <attribute name="description" type="wstring" readonly="yes"> + <desc> + Textual description of the metric. + </desc> + </attribute> + + <attribute name="period" type="unsigned long" readonly="yes"> + <desc> + Time interval between samples, measured in seconds. + </desc> + </attribute> + + <attribute name="count" type="unsigned long" readonly="yes"> + <desc> + Number of recent samples retained by the performance collector for this + metric. + + When the collected sample count exceeds this number, older samples + are discarded. + </desc> + </attribute> + + <attribute name="unit" type="wstring" readonly="yes"> + <desc> + Unit of measurement. + </desc> + </attribute> + + <attribute name="minimumValue" type="long" readonly="yes"> + <desc> + Minimum possible value of this metric. + </desc> + </attribute> + + <attribute name="maximumValue" type="long" readonly="yes"> + <desc> + Maximum possible value of this metric. + </desc> + </attribute> + </interface> + + <interface + name="IPerformanceCollector" extends="$unknown" + uuid="b14290ad-cd54-400c-b858-797bcb82570e" + wsmap="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc> + The IPerformanceCollector interface represents a service that collects + and stores performance metrics data. + + Performance metrics are associated with objects of interfaces like IHost + and IMachine. Each object has a distinct set of performance metrics. The + set can be obtained with <link to="IPerformanceCollector::getMetrics"/>. + + Metric data is collected at the specified intervals and is retained + internally. The interval and the number of retained samples can be set + with <link to="IPerformanceCollector::setupMetrics" />. Both metric data + and collection settings are not persistent, they are discarded as soon as + VBoxSVC process terminates. Moreover, metric settings and data associated + with a particular VM only exist while VM is running. They disappear as + soon as VM shuts down. It is not possible to set up metrics for machines + that are powered off. One needs to start VM first, then set up metric + collection parameters. + + Metrics are organized hierarchically, with each level separated by a + slash (/) character. Generally, the scheme for metric names is like this: + + <tt>Category/Metric[/SubMetric][:aggregation]</tt> + + "Category/Metric" together form the base metric name. A base metric is + the smallest unit for which a sampling interval and the number of + retained samples can be set. Only base metrics can be enabled and + disabled. All sub-metrics are collected when their base metric is + collected. Collected values for any set of sub-metrics can be queried + with <link to="IPerformanceCollector::queryMetricsData" />. + + For example "CPU/Load/User:avg" metric name stands for the "CPU" + category, "Load" metric, "User" submetric, "average" aggregate. An + aggregate function is computed over all retained data. Valid aggregate + functions are: + + <ul> + <li>avg -- average</li> + <li>min -- minimum</li> + <li>max -- maximum</li> + </ul> + + When setting up metric parameters, querying metric data, enabling or + disabling metrics wildcards can be used in metric names to specify a + subset of metrics. For example, to select all CPU-related metrics + use <tt>CPU/*</tt>, all averages can be queried using <tt>*:avg</tt> and + so on. To query metric values without aggregates <tt>*:</tt> can be used. + + The valid names for base metrics are: + + <ul> + <li>CPU/Load</li> + <li>CPU/MHz</li> + <li>RAM/Usage</li> + <li>RAM/VMM</li> + </ul> + + The general sequence for collecting and retrieving the metrics is: + <ul> + <li> + Obtain an instance of IPerformanceCollector with + <link to="IVirtualBox::performanceCollector" /> + </li> + <li> + Allocate and populate an array with references to objects the metrics + will be collected for. Use references to IHost and IMachine objects. + </li> + <li> + Allocate and populate an array with base metric names the data will + be collected for. + </li> + <li> + Call <link to="IPerformanceCollector::setupMetrics" />. From now on + the metric data will be collected and stored. + </li> + <li> + Wait for the data to get collected. + </li> + <li> + Allocate and populate an array with references to objects the metric + values will be queried for. You can re-use the object array used for + setting base metrics. + </li> + <li> + Allocate and populate an array with metric names the data will be + collected for. Note that metric names differ from base metric names. + </li> + <li> + Call <link to="IPerformanceCollector::queryMetricsData" />. The data + that have been collected so far are returned. Note that the values + are still retained internally and data collection continues. + </li> + </ul> + + For an example of usage refer to the following files in VirtualBox SDK: + <ul> + <li> + Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt> + </li> + <li> + Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt> + </li> + </ul> + </desc> + + <attribute name="metricNames" type="wstring" readonly="yes" safearray="yes"> + <desc> + Array of unique names of metrics. + + This array represents all metrics supported by the performance + collector. Individual objects do not necessarily support all of them. + <link to="IPerformanceCollector::getMetrics"/> can be used to get the + list of supported metrics for a particular object. + </desc> + </attribute> + + <method name="getMetrics"> + <desc> + Returns parameters of specified metrics for a set of objects. + <note> + @c Null metrics array means all metrics. @c Null object array means + all existing objects. + </note> + </desc> + <param name="metricNames" type="wstring" dir="in" safearray="yes"> + <desc> + Metric name filter. Currently, only a comma-separated list of metrics + is supported. + </desc> + </param> + <param name="objects" type="$unknown" dir="in" safearray="yes"> + <desc> + Set of objects to return metric parameters for. + </desc> + </param> + <param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes"> + <desc> + Array of returned metric parameters. + </desc> + </param> + </method> + + <method name="setupMetrics"> + <desc> + Sets parameters of specified base metrics for a set of objects. Returns + an array of <link to="IPerformanceMetric" /> describing the metrics + have been affected. + <note> + @c Null or empty metric name array means all metrics. @c Null or + empty object array means all existing objects. If metric name array + contains a single element and object array contains many, the single + metric name array element is applied to each object array element to + form metric/object pairs. + </note> + </desc> + <param name="metricNames" type="wstring" dir="in" safearray="yes"> + <desc> + Metric name filter. Comma-separated list of metrics with wildcard + support. + </desc> + </param> + <param name="objects" type="$unknown" dir="in" safearray="yes"> + <desc> + Set of objects to setup metric parameters for. + </desc> + </param> + <param name="period" type="unsigned long" dir="in"> + <desc> + Time interval in seconds between two consecutive samples of + performance data. + </desc> + </param> + <param name="count" type="unsigned long" dir="in"> + <desc> + Number of samples to retain in performance data history. Older + samples get discarded. + </desc> + </param> + <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes"> + <desc> + Array of metrics that have been modified by the call to this method. + </desc> + </param> + </method> + + <method name="enableMetrics"> + <desc> + Turns on collecting specified base metrics. Returns an array of + <link to="IPerformanceMetric" /> describing the metrics have been + affected. + <note> + @c Null or empty metric name array means all metrics. @c Null or + empty object array means all existing objects. If metric name array + contains a single element and object array contains many, the single + metric name array element is applied to each object array element to + form metric/object pairs. + </note> + </desc> + <param name="metricNames" type="wstring" dir="in" safearray="yes"> + <desc> + Metric name filter. Comma-separated list of metrics with wildcard + support. + </desc> + </param> + <param name="objects" type="$unknown" dir="in" safearray="yes"> + <desc> + Set of objects to enable metrics for. + </desc> + </param> + <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes"> + <desc> + Array of metrics that have been modified by the call to this method. + </desc> + </param> + </method> + + <method name="disableMetrics"> + <desc> + Turns off collecting specified base metrics. Returns an array of + <link to="IPerformanceMetric" /> describing the metrics have been + affected. + <note> + @c Null or empty metric name array means all metrics. @c Null or + empty object array means all existing objects. If metric name array + contains a single element and object array contains many, the single + metric name array element is applied to each object array element to + form metric/object pairs. + </note> + </desc> + <param name="metricNames" type="wstring" dir="in" safearray="yes"> + <desc> + Metric name filter. Comma-separated list of metrics with wildcard + support. + </desc> + </param> + <param name="objects" type="$unknown" dir="in" safearray="yes"> + <desc> + Set of objects to disable metrics for. + </desc> + </param> + <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes"> + <desc> + Array of metrics that have been modified by the call to this method. + </desc> + </param> + </method> + + <method name="queryMetricsData"> + <desc> + Queries collected metrics data for a set of objects. + + The data itself and related metric information are returned in seven + parallel and one flattened array of arrays. Elements of + <tt>returnMetricNames, returnObjects, returnUnits, returnScales, + returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with + the same index describe one set of values corresponding to a single + metric. + + The <tt>returnData</tt> parameter is a flattened array of arrays. Each + start and length of a sub-array is indicated by + <tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first + value for metric <tt>metricNames[i]</tt> is at + <tt>returnData[returnIndices[i]]</tt>. + + <note> + @c Null or empty metric name array means all metrics. @c Null or + empty object array means all existing objects. If metric name array + contains a single element and object array contains many, the single + metric name array element is applied to each object array element to + form metric/object pairs. + </note> + <note> + Data collection continues behind the scenes after call to + @c queryMetricsData. The return data can be seen as the snapshot of + the current state at the time of @c queryMetricsData call. The + internally kept metric values are not cleared by the call. This + allows querying different subsets of metrics or aggregates with + subsequent calls. If periodic querying is needed it is highly + suggested to query the values with @c interval*count period to avoid + confusion. This way a completely new set of data values will be + provided by each query. + </note> + </desc> + <param name="metricNames" type="wstring" dir="in" safearray="yes"> + <desc> + Metric name filter. Comma-separated list of metrics with wildcard + support. + </desc> + </param> + <param name="objects" type="$unknown" dir="in" safearray="yes"> + <desc> + Set of objects to query metrics for. + </desc> + </param> + <param name="returnMetricNames" type="wstring" dir="out" safearray="yes"> + <desc> + Names of metrics returned in @c returnData. + </desc> + </param> + <param name="returnObjects" type="$unknown" dir="out" safearray="yes"> + <desc> + Objects associated with metrics returned in @c returnData. + </desc> + </param> + <param name="returnUnits" type="wstring" dir="out" safearray="yes"> + <desc> + Units of measurement for each returned metric. + </desc> + </param> + <param name="returnScales" type="unsigned long" dir="out" safearray="yes"> + <desc> + Divisor that should be applied to return values in order to get + floating point values. For example: + <tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt> + will retrieve the floating point value of i-th sample of the first + metric. + </desc> + </param> + <param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes"> + <desc> + Sequence numbers of the first elements of value sequences of + particular metrics returned in @c returnData. For aggregate metrics + it is the sequence number of the sample the aggregate started + calculation from. + </desc> + </param> + <param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes"> + <desc> + Indices of the first elements of value sequences of particular + metrics returned in @c returnData. + </desc> + </param> + <param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes"> + <desc> + Lengths of value sequences of particular metrics. + </desc> + </param> + <param name="returnData" type="long" dir="return" safearray="yes"> + <desc> + Flattened array of all metric data containing sequences of values for + each metric. + </desc> + </param> + </method> + + </interface> + + <enum + name="NATAliasMode" + uuid="67772168-50d9-11df-9669-7fb714ee4fa1" + > + <desc></desc> + <const name="AliasLog" value="0x1"> + <desc></desc> + </const> + <const name="AliasProxyOnly" value="0x02"> + <desc></desc> + </const> + <const name="AliasUseSamePorts" value="0x04"> + <desc></desc> + </const> + </enum> + + <enum + name="NATProtocol" + uuid="e90164be-eb03-11de-94af-fff9b1c1b19f" + > + <desc>Protocol definitions used with NAT port-forwarding rules.</desc> + <const name="UDP" value="0"> + <desc>Port-forwarding uses UDP protocol.</desc> + </const> + <const name="TCP" value="1"> + <desc>Port-forwarding uses TCP protocol.</desc> + </const> + </enum> + + <interface + name="INATEngine" extends="$unknown" + uuid="a06253a7-dcd2-44e3-8689-9c9c4b6b6234" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + <desc>Interface for managing a NAT engine which is used with a virtual machine. This + allows for changing NAT behavior such as port-forwarding rules. This interface is + used in the <link to="INetworkAdapter::NATEngine" /> attribute.</desc> + <attribute name="network" type="wstring"> + <desc>The network attribute of the NAT engine (the same value is used with built-in + DHCP server to fill corresponding fields of DHCP leases).</desc> + </attribute> + <attribute name="hostIP" type="wstring"> + <desc>IP of host interface to bind all opened sockets to. + <note>Changing this does not change binding of port forwarding.</note> + </desc> + </attribute> + <attribute name="TFTPPrefix" type="wstring"> + <desc>TFTP prefix attribute which is used with the built-in DHCP server to fill + the corresponding fields of DHCP leases.</desc> + </attribute> + <attribute name="TFTPBootFile" type="wstring"> + <desc>TFTP boot file attribute which is used with the built-in DHCP server to fill + the corresponding fields of DHCP leases.</desc> + </attribute> + <attribute name="TFTPNextServer" type="wstring"> + <desc>TFTP server attribute which is used with the built-in DHCP server to fill + the corresponding fields of DHCP leases. + <note>The preferred form is IPv4 addresses.</note> + </desc> + </attribute> + <attribute name="aliasMode" type="unsigned long"> + <desc></desc> + </attribute> + <attribute name="DNSPassDomain" type="boolean"> + <desc>Whether the DHCP server should pass the DNS domain used by the host.</desc> + </attribute> + <attribute name="DNSProxy" type="boolean"> + <desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address + of the DNS proxy and process traffic using DNS servers registered on the host.</desc> + </attribute> + <attribute name="DNSUseHostResolver" type="boolean"> + <desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address + of the DNS proxy and process traffic using the host resolver mechanism.</desc> + </attribute> + <attribute name="redirects" type="wstring" readonly="yes" safearray="yes"> + <desc>Array of NAT port-forwarding rules in string representation, in the following + format: "name,protocol id,host ip,host port,guest ip,guest port".</desc> + </attribute> + <attribute name="localhostReachable" type="boolean"> + <desc>Whether traffic from the guest directed to 10.0.2.2 will reach the + host's loopback interface, i.e. localhost or 127.0.0.1.</desc> + </attribute> + <method name="setNetworkSettings"> + <desc>Sets network configuration of the NAT engine.</desc> + <param name="mtu" type="unsigned long" dir="in"> + <desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc> + </param> + <param name="sockSnd" type="unsigned long" dir="in"> + <desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc> + </param> + <param name="sockRcv" type="unsigned long" dir="in"> + <desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc> + </param> + <param name="TcpWndSnd" type="unsigned long" dir="in"> + <desc>Initial size of the NAT engine's sending TCP window in bytes when + establishing a new TCP connection.</desc> + </param> + <param name="TcpWndRcv" type="unsigned long" dir="in"> + <desc>Initial size of the NAT engine's receiving TCP window in bytes when + establishing a new TCP connection.</desc> + </param> + </method> + <method name="getNetworkSettings"> + <desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" /> + for parameter descriptions.</desc> + <param name="mtu" type="unsigned long" dir="out" /> + <param name="sockSnd" type="unsigned long" dir="out" /> + <param name="sockRcv" type="unsigned long" dir="out" /> + <param name="TcpWndSnd" type="unsigned long" dir="out" /> + <param name="TcpWndRcv" type="unsigned long" dir="out" /> + </method> + <method name="addRedirect"> + <desc>Adds a new NAT port-forwarding rule.</desc> + <param name="name" type="wstring" dir="in"> + <desc>The name of the rule. An empty name is acceptable, in which case the NAT engine + auto-generates one using the other parameters.</desc> + </param> + <param name="proto" type="NATProtocol" dir="in"> + <desc>Protocol handled with the rule.</desc> + </param> + <param name="hostIP" type="wstring" dir="in"> + <desc>IP of the host interface to which the rule should apply. An empty ip address is + acceptable, in which case the NAT engine binds the handling socket to any interface.</desc> + </param> + <param name="hostPort" type="unsigned short" dir="in"> + <desc>The port number to listen on.</desc> + </param> + <param name="guestIP" type="wstring" dir="in"> + <desc>The IP address of the guest which the NAT engine will forward matching packets + to. An empty IP address is acceptable, in which case the NAT engine will forward + packets to the first DHCP lease (x.x.x.15).</desc> + </param> + <param name="guestPort" type="unsigned short" dir="in"> + <desc>The port number to forward.</desc> + </param> + </method> + <method name="removeRedirect"> + <desc>Removes a port-forwarding rule that was previously registered.</desc> + <param name="name" type="wstring" dir="in"> + <desc>The name of the rule to delete.</desc> + </param> + </method> + </interface> + + <!-- + // IExtPackManager + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IExtPackPlugIn" extends="$unknown" + uuid="78861431-d545-44aa-8013-181b8c288554" + wsmap="suppress" + reservedAttributes="4" + > + <desc> + Interface for keeping information about a plug-in that ships with an + extension pack. + </desc> + <attribute name="name" type="wstring" readonly="yes"> + <desc>The plug-in name.</desc> + </attribute> + <attribute name="description" type="wstring" readonly="yes"> + <desc>The plug-in description.</desc> + </attribute> + <attribute name="frontend" type="wstring" readonly="yes"> + <desc> + The name of the frontend or component name this plug-in plugs into. + </desc> + </attribute> + <attribute name="modulePath" type="wstring" readonly="yes"> + <desc> The module path. </desc> + </attribute> + </interface> + + <interface + name="IExtPackBase" extends="$unknown" + uuid="aa204a12-5b29-45a5-b5d6-c2bafcdb9b0b" + wsmap="suppress" + reservedMethods="4" reservedAttributes="8" + > + <desc> + Interface for querying information about an extension pack as well as + accessing COM objects within it. + </desc> + <attribute name="name" type="wstring" readonly="yes"> + <desc>The extension pack name. This is unique.</desc> + </attribute> + <attribute name="description" type="wstring" readonly="yes"> + <desc>The extension pack description.</desc> + </attribute> + <attribute name="version" type="wstring" readonly="yes"> + <desc> + The extension pack version string. This is restricted to the dotted + version number and optionally a build indicator. No tree revision or + tag will be included in the string as those things are available as + separate properties. An optional publisher tag may be present like for + <link to="IVirtualBox::version"/>. + + Examples: "1.2.3", "1.2.3_BETA1" and "1.2.3_RC2". + </desc> + </attribute> + <attribute name="revision" type="unsigned long" readonly="yes"> + <desc>The extension pack internal revision number.</desc> + </attribute> + <attribute name="edition" type="wstring" readonly="yes"> + <desc> + Edition indicator. This is usually empty. + + Can for instance be used to help distinguishing between two editions + of the same extension pack where only the license, service contract or + something differs. + </desc> + </attribute> + <attribute name="VRDEModule" type="wstring" readonly="yes"> + <desc>The name of the VRDE module if the extension pack sports one.</desc> + </attribute> + <attribute name="CryptoModule" type="wstring" readonly="yes"> + <desc> + The name of the crypto module if the extension pack sports one. + This module is required for full VM encryption. + </desc> + </attribute> + <attribute name="plugIns" type="IExtPackPlugIn" safearray="yes" readonly="yes"> + <desc>Plug-ins provided by this extension pack.</desc> + </attribute> + <attribute name="usable" type="boolean" readonly="yes"> + <desc> + Indicates whether the extension pack is usable or not. + + There are a number of reasons why an extension pack might be unusable, + typical examples would be broken installation/file or that it is + incompatible with the current VirtualBox version. + </desc> + </attribute> + <attribute name="whyUnusable" type="wstring" readonly="yes"> + <desc> + String indicating why the extension pack is not usable. This is an + empty string if usable and always a non-empty string if not usable. + </desc> + </attribute> + <attribute name="showLicense" type="boolean" readonly="yes"> + <desc>Whether to show the license before installation</desc> + </attribute> + <attribute name="license" type="wstring" readonly="yes"> + <desc> + The default HTML license text for the extension pack. Same as + calling <link to="#queryLicense">queryLicense</link> with + preferredLocale and preferredLanguage as empty strings and format set + to html. + </desc> + </attribute> + + <method name="queryLicense"> + <desc> + Full feature version of the license attribute. + </desc> + <param name="preferredLocale" type="wstring" dir="in"> + <desc> + The preferred license locale. Pass an empty string to get the default + license. + </desc> + </param> + <param name="preferredLanguage" type="wstring" dir="in"> + <desc> + The preferred license language. Pass an empty string to get the + default language for the locale. + </desc> + </param> + <param name="format" type="wstring" dir="in"> + <desc> + The license format: html, rtf or txt. If a license is present there + will always be an HTML of it, the rich text format (RTF) and plain + text (txt) versions are optional. If + </desc> + </param> + <param name="licenseText" type="wstring" dir="return"> + <desc>The license text.</desc> + </param> + </method> + + </interface> + + <interface + name="IExtPack" extends="IExtPackBase" + uuid="431685da-3618-4ebc-b038-833ba829b4b2" + wsmap="suppress" + > + <desc> + Interface for querying information about an extension pack as well as + accessing COM objects within it. + </desc> + <method name="queryObject"> + <desc> + Queries the IUnknown interface to an object in the extension pack + main module. This allows plug-ins and others to talk directly to an + extension pack. + </desc> + <param name="objUuid" type="wstring" dir="in"> + <desc>The object ID. What exactly this is </desc> + </param> + <param name="returnInterface" type="$unknown" dir="return"> + <desc>The queried interface.</desc> + </param> + </method> + </interface> + + <interface + name="IExtPackFile" extends="IExtPackBase" + uuid="41304f1b-7e72-4f34-b8f6-682785620c57" + wsmap="suppress" + reservedMethods="2" reservedAttributes="4" + > + <desc> + Extension pack file (aka tarball, .vbox-extpack) representation returned + by <link to="IExtPackManager::openExtPackFile"/>. This provides the base + extension pack information with the addition of the file name. + </desc> + <attribute name="filePath" type="wstring" readonly="yes"> + <desc> + The path to the extension pack file. + </desc> + </attribute> + + <method name="install"> + <desc> + Install the extension pack. + </desc> + <param name="replace" type="boolean" dir="in"> + <desc> + Set this to automatically uninstall any existing extension pack with + the same name as the one being installed. + </desc> + </param> + <param name="displayInfo" type="wstring" dir="in"> + <desc> + Platform specific display information. Reserved for future hacks. + </desc> + </param> + <param name="progess" type="IProgress" dir="return"> + <desc> + Progress object for the operation. + </desc> + </param> + </method> + </interface> + + <interface + name="IExtPackManager" extends="$unknown" + uuid="70401eef-c8e9-466b-9660-45cb3e9979e4" + wsmap="suppress" + reservedMethods="4" reservedAttributes="8" + > + <desc> + Interface for managing VirtualBox Extension Packs. + + @todo Describe extension packs, how they are managed and how to create one. + </desc> + + <attribute name="installedExtPacks" type="IExtPack" safearray="yes" readonly="yes"> + <desc> + List of the installed extension packs. + </desc> + </attribute> + + <method name="find"> + <desc> + Returns the extension pack with the specified name if found. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + No extension pack matching @a name was found. + </result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>The name of the extension pack to locate.</desc> + </param> + <param name="returnData" type="IExtPack" dir="return"> + <desc>The extension pack if found.</desc> + </param> + </method> + + <method name="openExtPackFile"> + <desc> + Attempts to open an extension pack file in preparation for + installation. + </desc> + <param name="path" type="wstring" dir="in"> + <desc>The path of the extension pack tarball. This can optionally be + followed by a "::SHA-256=hex-digit" of the tarball. </desc> + </param> + <param name="file" type="IExtPackFile" dir="return"> + <desc>The interface of the extension pack file object.</desc> + </param> + </method> + + <method name="uninstall"> + <desc>Uninstalls an extension pack, removing all related files.</desc> + <param name="name" type="wstring" dir="in"> + <desc>The name of the extension pack to uninstall.</desc> + </param> + <param name="forcedRemoval" type="boolean" dir="in"> + <desc> + Forced removal of the extension pack. This means that the uninstall + hook will not be called. + </desc> + </param> + <param name="displayInfo" type="wstring" dir="in"> + <desc> + Platform specific display information. Reserved for future hacks. + </desc> + </param> + <param name="progess" type="IProgress" dir="return"> + <desc> + Progress object for the operation. + </desc> + </param> + </method> + + <method name="cleanup"> + <desc>Cleans up failed installs and uninstalls</desc> + </method> + + <method name="queryAllPlugInsForFrontend"> + <desc> + Gets the path to all the plug-in modules for a given frontend. + + This is a convenience method that is intended to simplify the plug-in + loading process for a frontend. + </desc> + <param name="frontendName" type="wstring" dir="in"> + <desc>The name of the frontend or component.</desc> + </param> + <param name="plugInModules" type="wstring" dir="return" safearray="yes"> + <desc>Array containing the plug-in modules (full paths).</desc> + </param> + </method> + + <method name="isExtPackUsable"> + <desc>Check if the given extension pack is loaded and usable.</desc> + <param name="name" type="wstring" dir="in"> + <desc>The name of the extension pack to check for.</desc> + </param> + <param name="usable" type="boolean" dir="return"> + <desc>Is the given extension pack loaded and usable.</desc> + </param> + </method> + + </interface> + + <!-- + // BandwidthGroupType + ///////////////////////////////////////////////////////////////////////// + --> + <enum + name="BandwidthGroupType" + uuid="1d92b67d-dc69-4be9-ad4c-93a01e1e0c8e"> + + <desc> + Type of a bandwidth control group. + </desc> + + <const name="Null" value="0"> + <desc> + Null type, must be first. + </desc> + </const> + + <const name="Disk" value="1"> + <desc> + The bandwidth group controls disk I/O. + </desc> + </const> + + <const name="Network" value="2"> + <desc> + The bandwidth group controls network I/O. + </desc> + </const> + + </enum> + + <!-- + // IBandwidthGroup + ///////////////////////////////////////////////////////////////////////// + --> + <interface + name="IBandwidthGroup" extends="$unknown" + uuid="31587f93-2d12-4d7c-ba6d-ce51d0d5b265" + wsmap="managed" + rest="managed" + reservedAttributes="4" + > + <desc>Represents one bandwidth group.</desc> + + <attribute name="name" type="wstring" readonly="yes"> + <desc>Name of the group.</desc> + </attribute> + + <attribute name="type" type="BandwidthGroupType" readonly="yes"> + <desc>Type of the group.</desc> + </attribute> + + <attribute name="reference" type="unsigned long" readonly="yes"> + <desc>How many devices/medium attachments use this group.</desc> + </attribute> + + <attribute name="maxBytesPerSec" type="long long"> + <desc>The maximum number of bytes which can be transfered by all + entities attached to this group during one second.</desc> + </attribute> + + </interface> + + <!-- + // IBandwidthControl + ///////////////////////////////////////////////////////////////////////// + --> + <interface + name="IBandwidthControl" extends="$unknown" + uuid="48c7f4c0-c9d6-4742-957c-a6fd52e8c4ae" + wsmap="managed" + rest="managed" + reservedMethods="2" reservedAttributes="2" + > + <desc> + Controls the bandwidth groups of one machine used to cap I/O done by a VM. + This includes network and disk I/O. + </desc> + + <attribute name="numGroups" type="unsigned long" readonly="yes"> + <desc> + The current number of existing bandwidth groups managed. + </desc> + </attribute> + + <method name="createBandwidthGroup"> + <desc> + Creates a new bandwidth group. + </desc> + + <param name="name" type="wstring" dir="in"> + <desc>Name of the bandwidth group.</desc> + </param> + <param name="type" type="BandwidthGroupType" dir="in"> + <desc>The type of the bandwidth group (network or disk).</desc> + </param> + <param name="maxBytesPerSec" type="long long" dir="in"> + <desc>The maximum number of bytes which can be transfered by all + entities attached to this group during one second.</desc> + </param> + </method> + + <method name="deleteBandwidthGroup"> + <desc> + Deletes a new bandwidth group. + </desc> + + <param name="name" type="wstring" dir="in"> + <desc>Name of the bandwidth group to delete.</desc> + </param> + </method> + + <method name="getBandwidthGroup" const="yes"> + <desc> + Get a bandwidth group by name. + </desc> + + <param name="name" type="wstring" dir="in"> + <desc>Name of the bandwidth group to get.</desc> + </param> + <param name="bandwidthGroup" type="IBandwidthGroup" dir="return"> + <desc>Where to store the bandwidth group on success.</desc> + </param> + </method> + + <method name="getAllBandwidthGroups" const="yes"> + <desc> + Get all managed bandwidth groups. + </desc> + + <param name="bandwidthGroups" type="IBandwidthGroup" dir="return" safearray="yes"> + <desc>The array of managed bandwidth groups.</desc> + </param> + </method> + </interface> + + <!-- + // IGuestDebugControl + ///////////////////////////////////////////////////////////////////////// + --> + <enum + name="GuestDebugProvider" + uuid="acdaddc5-aa0f-4f2e-be1f-a9be2828d24a" + > + <desc> + The enabled guest debug provider. This enumeration represents possible + values for the <link to="IGuestDebugControl::debugProvider"/> attribute. + </desc> + <const name="None" value="0"> + <desc>Guest debugging is disabled.</desc> + </const> + <const name="Native" value="1"> + <desc>The native debugger console is enabled.</desc> + </const> + <const name="GDB" value="2"> + <desc>The GDB remote stub is enabled.</desc> + </const> + <const name="KD" value="3"> + <desc>The WinDbg/KD remote stub is enabled.</desc> + </const> + </enum> + + <enum + name="GuestDebugIoProvider" + uuid="0cf00b1b-2ff7-414c-81c6-6cf410eaec4a" + > + <desc> + The enabled guest debug I/O provider. This enumeration represents possible + values for the <link to="IGuestDebugControl::debugIoProvider"/> attribute. + </desc> + <const name="None" value="0"> + <desc>No connection available (only useful with + <link to="GuestDebugProvider::None"/>). + </desc> + </const> + <const name="TCP" value="1"> + <desc>The remote stub is available through a TCP connection.</desc> + </const> + <const name="UDP" value="2"> + <desc>The remote stub is available through a UDP connection.</desc> + </const> + <const name="IPC" value="3"> + <desc>The remote stub is available through a IPC connection, + namely a named pipe on Windows or a unix socket on other hosts.</desc> + </const> + </enum> + + <interface + name="IGuestDebugControl" extends="$unknown" + uuid="1474bb3a-f096-4cd7-a857-8d8e3cea7331" + wsmap="managed" + rest="managed" + reservedMethods="2" reservedAttributes="2" + > + <desc> + Controls the guest debug settings of one virtual machine. + </desc> + + <attribute name="debugProvider" type="GuestDebugProvider"> + <desc>The currently active debug provider.</desc> + </attribute> + + <attribute name="debugIoProvider" type="GuestDebugIoProvider"> + <desc>The I/O backend for the selected debug provider.</desc> + </attribute> + + <attribute name="debugAddress" type="wstring"> + <desc> + The address to connect to or listen on, + depending on the type. + </desc> + </attribute> + + <attribute name="debugPort" type="unsigned long"> + <desc> + The port to listen on or connect to, depending on the selected I/O + provider. Might be ignored by some providers. + </desc> + </attribute> + </interface> + + <!-- + // IVirtualBoxClient + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IVirtualBoxClient" extends="$unknown" + uuid="d2937a8e-cb8d-4382-90ba-b7da78a74573" + wsmap="suppress" + reservedMethods="4" reservedAttributes="4" + > + <desc> + Convenience interface for client applications. Treat this as a + singleton, i.e. never create more than one instance of this interface. + + At the moment only available for clients of the local API (not usable + via the webservice). Once the session logic is redesigned this might + change. + + Error information handling is a bit special with IVirtualBoxClient: + creating an instance will always succeed. The return of the actual error + code/information is postponed to any attribute or method call. The + reason for this is that COM likes to mutilate the error code and lose + the detailed error information returned by instance creation. + </desc> + + <attribute name="virtualBox" type="IVirtualBox" readonly="yes"> + <desc> + Reference to the server-side API root object. + </desc> + </attribute> + + <attribute name="session" type="ISession" readonly="yes"> + <desc> + Create a new session object and return the reference to it. + </desc> + </attribute> + + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for VirtualBoxClient events. + </desc> + </attribute> + + <method name="checkMachineError"> + <desc> + Perform error checking before using an <link to="IMachine"/> object. + Generally useful before starting a VM and all other uses. If anything + is not as it should be then this method will return an appropriate + error. + </desc> + + <param name="machine" type="IMachine" dir="in"> + <desc>The machine object to check.</desc> + </param> + </method> + </interface> + + <!-- + // Events + ///////////////////////////////////////////////////////////////////////// + --> + <enum + name="VBoxEventType" + uuid="e4c5252d-7d1a-4051-8cfb-5b2d7a73d992" + > + + <desc> + Type of an event. + See <link to="IEvent" /> for an introduction to VirtualBox event handling. + </desc> + + <const name="Invalid" value="0"> + <desc> + Invalid event, must be first. + </desc> + </const> + + <const name="Any" value="1"> + <desc> + Wildcard for all events. + Events of this type are never delivered, and only used in + <link to="IEventSource::registerListener"/> call to simplify registration. + </desc> + </const> + + <const name="Vetoable" value="2"> + <desc> + Wildcard for all vetoable events. Events of this type are never delivered, and only + used in <link to="IEventSource::registerListener"/> call to simplify registration. + </desc> + </const> + + <const name="MachineEvent" value="3"> + <desc> + Wildcard for all machine events. Events of this type are never delivered, and only used in + <link to="IEventSource::registerListener"/> call to simplify registration. + </desc> + </const> + + <const name="SnapshotEvent" value="4"> + <desc> + Wildcard for all snapshot events. Events of this type are never delivered, and only used in + <link to="IEventSource::registerListener"/> call to simplify registration. + </desc> + </const> + + <const name="InputEvent" value="5"> + <desc> + Wildcard for all input device (keyboard, mouse) events. + Events of this type are never delivered, and only used in + <link to="IEventSource::registerListener"/> call to simplify registration. + </desc> + </const> + + <const name="LastWildcard" value="31"> + <desc> + Last wildcard. + </desc> + </const> + + <const name="OnMachineStateChanged" value="32"> + <desc> + See <link to="IMachineStateChangedEvent">IMachineStateChangedEvent</link>. + </desc> + </const> + <const name="OnMachineDataChanged" value="33"> + <desc> + See <link to="IMachineDataChangedEvent">IMachineDataChangedEvent</link>. + </desc> + </const> + <const name="OnExtraDataChanged" value="34"> + <desc> + See <link to="IExtraDataChangedEvent">IExtraDataChangedEvent</link>. + </desc> + </const> + <const name="OnExtraDataCanChange" value="35"> + <desc> + See <link to="IExtraDataCanChangeEvent">IExtraDataCanChangeEvent</link>. + </desc> + </const> + <const name="OnMediumRegistered" value="36"> + <desc> + See <link to="IMediumRegisteredEvent">IMediumRegisteredEvent</link>. + </desc> + </const> + <const name="OnMachineRegistered" value="37"> + <desc> + See <link to="IMachineRegisteredEvent">IMachineRegisteredEvent</link>. + </desc> + </const> + <const name="OnSessionStateChanged" value="38"> + <desc> + See <link to="ISessionStateChangedEvent">ISessionStateChangedEvent</link>. + </desc> + </const> + <const name="OnSnapshotTaken" value="39"> + <desc> + See <link to="ISnapshotTakenEvent">ISnapshotTakenEvent</link>. + </desc> + </const> + <const name="OnSnapshotDeleted" value="40"> + <desc> + See <link to="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>. + </desc> + </const> + <const name="OnSnapshotChanged" value="41"> + <desc> + See <link to="ISnapshotChangedEvent">ISnapshotChangedEvent</link>. + </desc> + </const> + <const name="OnGuestPropertyChanged" value="42"> + <desc> + See <link to="IGuestPropertyChangedEvent">IGuestPropertyChangedEvent</link>. + </desc> + </const> + <!-- Console events --> + <const name="OnMousePointerShapeChanged" value="43"> + <desc> + See <link to="IMousePointerShapeChangedEvent">IMousePointerShapeChangedEvent</link>. + </desc> + </const> + <const name="OnMouseCapabilityChanged" value="44"> + <desc> + See <link to="IMouseCapabilityChangedEvent">IMouseCapabilityChangedEvent</link>. + </desc> + </const> + <const name="OnKeyboardLedsChanged" value="45"> + <desc> + See <link to="IKeyboardLedsChangedEvent">IKeyboardLedsChangedEvent</link>. + </desc> + </const> + <const name="OnStateChanged" value="46"> + <desc> + See <link to="IStateChangedEvent">IStateChangedEvent</link>. + </desc> + </const> + <const name="OnAdditionsStateChanged" value="47"> + <desc> + See <link to="IAdditionsStateChangedEvent">IAdditionsStateChangedEvent</link>. + </desc> + </const> + <const name="OnNetworkAdapterChanged" value="48"> + <desc> + See <link to="INetworkAdapterChangedEvent">INetworkAdapterChangedEvent</link>. + </desc> + </const> + <const name="OnSerialPortChanged" value="49"> + <desc> + See <link to="ISerialPortChangedEvent">ISerialPortChangedEvent</link>. + </desc> + </const> + <const name="OnParallelPortChanged" value="50"> + <desc> + See <link to="IParallelPortChangedEvent">IParallelPortChangedEvent</link>. + </desc> + </const> + <const name="OnStorageControllerChanged" value="51"> + <desc> + See <link to="IStorageControllerChangedEvent">IStorageControllerChangedEvent</link>. + </desc> + </const> + <const name="OnMediumChanged" value="52"> + <desc> + See <link to="IMediumChangedEvent">IMediumChangedEvent</link>. + </desc> + </const> + <const name="OnVRDEServerChanged" value="53"> + <desc> + See <link to="IVRDEServerChangedEvent">IVRDEServerChangedEvent</link>. + </desc> + </const> + <const name="OnUSBControllerChanged" value="54"> + <desc> + See <link to="IUSBControllerChangedEvent">IUSBControllerChangedEvent</link>. + </desc> + </const> + <const name="OnUSBDeviceStateChanged" value="55"> + <desc> + See <link to="IUSBDeviceStateChangedEvent">IUSBDeviceStateChangedEvent</link>. + </desc> + </const> + <const name="OnSharedFolderChanged" value="56"> + <desc> + See <link to="ISharedFolderChangedEvent">ISharedFolderChangedEvent</link>. + </desc> + </const> + <const name="OnRuntimeError" value="57"> + <desc> + See <link to="IRuntimeErrorEvent">IRuntimeErrorEvent</link>. + </desc> + </const> + <const name="OnCanShowWindow" value="58"> + <desc> + See <link to="ICanShowWindowEvent">ICanShowWindowEvent</link>. + </desc> + </const> + <const name="OnShowWindow" value="59"> + <desc> + See <link to="IShowWindowEvent">IShowWindowEvent</link>. + </desc> + </const> + <const name="OnCPUChanged" value="60"> + <desc> + See <link to="ICPUChangedEvent">ICPUChangedEvent</link>. + </desc> + </const> + <const name="OnVRDEServerInfoChanged" value="61"> + <desc> + See <link to="IVRDEServerInfoChangedEvent">IVRDEServerInfoChangedEvent</link>. + </desc> + </const> + <const name="OnEventSourceChanged" value="62"> + <desc> + See <link to="IEventSourceChangedEvent">IEventSourceChangedEvent</link>. + </desc> + </const> + <const name="OnCPUExecutionCapChanged" value="63"> + <desc> + See <link to="ICPUExecutionCapChangedEvent">ICPUExecutionCapChangedEvent</link>. + </desc> + </const> + <const name="OnGuestKeyboard" value="64"> + <desc> + See <link to="IGuestKeyboardEvent">IGuestKeyboardEvent</link>. + </desc> + </const> + <const name="OnGuestMouse" value="65"> + <desc> + See <link to="IGuestMouseEvent">IGuestMouseEvent</link>. + </desc> + </const> + <const name="OnNATRedirect" value="66"> + <desc> + See <link to="INATRedirectEvent">INATRedirectEvent</link>. + </desc> + </const> + <const name="OnHostPCIDevicePlug" value="67"> + <desc> + See <link to="IHostPCIDevicePlugEvent">IHostPCIDevicePlugEvent</link>. + </desc> + </const> + <const name="OnVBoxSVCAvailabilityChanged" value="68"> + <desc> + See <link to="IVBoxSVCAvailabilityChangedEvent">IVBoxSVCAvailablityChangedEvent</link>. + </desc> + </const> + <const name="OnBandwidthGroupChanged" value="69"> + <desc> + See <link to="IBandwidthGroupChangedEvent">IBandwidthGroupChangedEvent</link>. + </desc> + </const> + <const name="OnGuestMonitorChanged" value="70"> + <desc> + See <link to="IGuestMonitorChangedEvent">IGuestMonitorChangedEvent</link>. + </desc> + </const> + <const name="OnStorageDeviceChanged" value="71"> + <desc> + See <link to="IStorageDeviceChangedEvent">IStorageDeviceChangedEvent</link>. + </desc> + </const> + <const name="OnClipboardModeChanged" value="72"> + <desc> + See <link to="IClipboardModeChangedEvent">IClipboardModeChangedEvent</link>. + </desc> + </const> + <const name="OnDnDModeChanged" value="73"> + <desc> + See <link to="IDnDModeChangedEvent">IDnDModeChangedEvent</link>. + </desc> + </const> + <const name="OnNATNetworkChanged" value="74"> + <desc> + See <link to="INATNetworkChangedEvent">INATNetworkChangedEvent</link>. + </desc> + </const> + <const name="OnNATNetworkStartStop" value="75"> + <desc> + See <link to="INATNetworkStartStopEvent">INATNetworkStartStopEvent</link>. + </desc> + </const> + <const name="OnNATNetworkAlter" value="76"> + <desc> + See <link to="INATNetworkAlterEvent">INATNetworkAlterEvent</link>. + </desc> + </const> + <const name="OnNATNetworkCreationDeletion" value="77"> + <desc> + See <link to="INATNetworkCreationDeletionEvent">INATNetworkCreationDeletionEvent</link>. + </desc> + </const> + <const name="OnNATNetworkSetting" value="78"> + <desc> + See <link to="INATNetworkSettingEvent">INATNetworkSettingEvent</link>. + </desc> + </const> + <const name="OnNATNetworkPortForward" value="79"> + <desc> + See <link to="INATNetworkPortForwardEvent">INATNetworkPortForwardEvent</link>. + </desc> + </const> + <const name="OnGuestSessionStateChanged" value="80"> + <desc> + See <link to="IGuestSessionStateChangedEvent">IGuestSessionStateChangedEvent</link>. + </desc> + </const> + <const name="OnGuestSessionRegistered" value="81"> + <desc> + See <link to="IGuestSessionRegisteredEvent">IGuestSessionRegisteredEvent</link>. + </desc> + </const> + <const name="OnGuestProcessRegistered" value="82"> + <desc> + See <link to="IGuestProcessRegisteredEvent">IGuestProcessRegisteredEvent</link>. + </desc> + </const> + <const name="OnGuestProcessStateChanged" value="83"> + <desc> + See <link to="IGuestProcessStateChangedEvent">IGuestProcessStateChangedEvent</link>. + </desc> + </const> + <const name="OnGuestProcessInputNotify" value="84"> + <desc> + See <link to="IGuestProcessInputNotifyEvent">IGuestProcessInputNotifyEvent</link>. + </desc> + </const> + <const name="OnGuestProcessOutput" value="85"> + <desc> + See <link to="IGuestProcessOutputEvent">IGuestProcessOutputEvent</link>. + </desc> + </const> + <const name="OnGuestFileRegistered" value="86"> + <desc> + See <link to="IGuestFileRegisteredEvent">IGuestFileRegisteredEvent</link>. + </desc> + </const> + <const name="OnGuestFileStateChanged" value="87"> + <desc> + See <link to="IGuestFileStateChangedEvent">IGuestFileStateChangedEvent</link>. + </desc> + </const> + <const name="OnGuestFileOffsetChanged" value="88"> + <desc> + See <link to="IGuestFileOffsetChangedEvent">IGuestFileOffsetChangedEvent</link>. + </desc> + </const> + <const name="OnGuestFileRead" value="89"> + <desc> + See <link to="IGuestFileReadEvent">IGuestFileReadEvent</link>. + + <note internal="yes">For performance reasons this is a separate event to + not unnecessarily overflow the event queue.</note> + </desc> + </const> + <const name="OnGuestFileWrite" value="90"> + <desc> + See <link to="IGuestFileWriteEvent">IGuestFileWriteEvent</link>. + + <note internal="yes">For performance reasons this is a separate event to + not unnecessarily overflow the event queue.</note> + </desc> + </const> + <const name="OnRecordingChanged" value="91"> + <desc> + See <link to="IRecordingChangedEvent">IRecordingChangeEvent</link>. + </desc> + </const> + <const name="OnGuestUserStateChanged" value="92"> + <desc> + See <link to="IGuestUserStateChangedEvent">IGuestUserStateChangedEvent</link>. + </desc> + </const> + <const name="OnGuestMultiTouch" value="93"> + <desc> + See <link to="IGuestMultiTouchEvent">IGuestMultiTouchEvent</link>. + </desc> + </const> + <const name="OnHostNameResolutionConfigurationChange" value="94"> + <desc> + See <link to="IHostNameResolutionConfigurationChangeEvent">IHostNameResolutionConfigurationChangeEvent</link>. + </desc> + </const> + <const name="OnSnapshotRestored" value="95"> + <desc> + See <link to="ISnapshotRestoredEvent">ISnapshotRestoredEvent</link>. + </desc> + </const> + <const name="OnMediumConfigChanged" value="96"> + <desc> + See <link to="IMediumConfigChangedEvent">IMediumConfigChangedEvent</link>. + </desc> + </const> + <const name="OnAudioAdapterChanged" value="97"> + <desc> + See <link to="IAudioAdapterChangedEvent">IAudioAdapterChangedEvent</link>. + </desc> + </const> + <const name="OnProgressPercentageChanged" value="98"> + <desc> + See <link to="IProgressPercentageChangedEvent">IProgressPercentageChangedEvent</link>. + </desc> + </const> + <const name="OnProgressTaskCompleted" value="99"> + <desc> + See <link to="IProgressTaskCompletedEvent">IProgressTaskCompletedEvent</link>. + </desc> + </const> + <const name="OnCursorPositionChanged" value="100"> + <desc> + See <link to="ICursorPositionChangedEvent">ICursorPositionChangedEvent</link>. + </desc> + </const> + <const name="OnGuestAdditionsStatusChanged" value="101"> + <desc> + See <link to="IGuestAdditionsStatusChangedEvent">IGuestAdditionsStatusChangedEvent</link>. + </desc> + </const> + <const name="OnGuestMonitorInfoChanged" value="102"> + <desc> + See <link to="IGuestMonitorInfoChangedEvent">IGuestMonitorInfoChangedEvent</link>. + </desc> + </const> + <const name="OnGuestFileSizeChanged" value="103"> + <desc> + See <link to="IGuestFileSizeChangedEvent">IGuestFileSizeChangedEvent</link>. + </desc> + </const> + <const name="OnClipboardFileTransferModeChanged" value="104"> + <desc> + See <link to="IClipboardFileTransferModeChangedEvent">IClipboardFileTransferModeChangedEvent</link>. + </desc> + </const> + <const name="OnCloudProviderListChanged" value="105"> + <desc> + See <link to="ICloudProviderListChangedEvent"/>. + </desc> + </const> + <const name="OnCloudProviderRegistered" value="106"> + <desc> + See <link to="ICloudProviderRegisteredEvent"/>. + </desc> + </const> + <const name="OnCloudProviderUninstall" value="107"> + <desc> + See <link to="ICloudProviderUninstallEvent"/>. + </desc> + </const> + <const name="OnCloudProfileRegistered" value="108"> + <desc> + See <link to="ICloudProfileRegisteredEvent"/>. + </desc> + </const> + <const name="OnCloudProfileChanged" value="109"> + <desc> + See <link to="ICloudProfileChangedEvent"/>. + </desc> + </const> + <const name="OnProgressCreated" value="110"> + <desc> + See <link to="IProgressCreatedEvent"/>. + </desc> + </const> + <const name="OnLanguageChanged" value="111"> + <desc> + See <link to="ILanguageChangedEvent"/>. + </desc> + </const> + <const name="OnUpdateAgentAvailable" value="112"> + <desc> + See <link to="IUpdateAgentAvailableEvent">IUpdateAgentAvailableEvent</link>. + </desc> + </const> + <const name="OnUpdateAgentError" value="113"> + <desc> + See <link to="IUpdateAgentErrorEvent">IUpdateAgentErrorEvent</link>. + </desc> + </const> + <const name="OnUpdateAgentSettingsChanged" value="114"> + <desc> + See <link to="IUpdateAgentSettingsChangedEvent">IUpdateAgentSettingsChangedEvent</link>. + </desc> + </const> + <const name="OnUpdateAgentStateChanged" value="115"> + <desc> + See <link to="IUpdateAgentStateChangedEvent">IUpdateAgentStateChangedEvent</link>. + </desc> + </const> + <const name="OnHostAudioDeviceChanged" value="116"> + <desc> + See <link to="IHostAudioDeviceChangedEvent">IHostAudioDeviceChangedEvent</link>. + </desc> + </const> + <const name="OnGuestDebugControlChanged" value="117"> + <desc> + See <link to="IGuestDebugControlChangedEvent">IGuestDebugControlChangedEvent</link>. + </desc> + </const> + <const name="OnMachineGroupsChanged" value="118"> + <desc> + See <link to="IMachineGroupsChangedEvent">IMachineGroupsChangedEvent</link>. + </desc> + </const> + <!-- End event marker --> + <const name="End" value="119"> + <desc> + Must be last event, used for iterations and structures relying on numerical event values. + </desc> + </const> + + </enum> + + <interface + name="IEventSource" extends="$unknown" + uuid="9b6e1aee-35f3-4f4d-b5bb-ed0ecefd8538" + wsmap="managed" + rest="managed" + > + <desc> + Event source. Generally, any object which could generate events can be an event source, + or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S), + an event source can work with listeners in either active or passive mode. In active mode it is up to + the IEventSource implementation to call <link to="IEventListener::handleEvent" />, in passive mode the + event source keeps track of pending events for each listener and returns available events on demand. + + See <link to="IEvent" /> for an introduction to VirtualBox event handling. + </desc> + + <method name="createListener"> + <desc> + Creates a new listener object, useful for passive mode. + </desc> + <param name="listener" type="IEventListener" dir="return"/> + </method> + + <method name="createAggregator"> + <desc> + Creates an aggregator event source, collecting events from multiple sources. + This way a single listener can listen for events coming from multiple sources, + using a single blocking <link to="#getEvent"/> on the returned aggregator. + </desc> + <param name="subordinates" type="IEventSource" dir="in" safearray="yes"> + <desc> + Subordinate event source this one aggregates. + </desc> + </param> + <param name="result" type="IEventSource" dir="return"> + <desc> + Event source aggregating passed sources. + </desc> + </param> + </method> + + <method name="registerListener"> + <desc> + Register an event listener. + + <note> + To avoid system overload, the VirtualBox server process checks if passive event + listeners call <link to="IEventSource::getEvent"/> frequently enough. In the + current implementation, if more than 500 pending events are detected for a passive + event listener, it is forcefully unregistered by the system, and further + <link to="#getEvent" /> calls will return @c VBOX_E_OBJECT_NOT_FOUND. + </note> + </desc> + <param name="listener" type="IEventListener" dir="in"> + <desc>Listener to register.</desc> + </param> + <param name="interesting" type="VBoxEventType" dir="in" safearray="yes"> + <desc> + Event types listener is interested in. One can use wildcards like - + <link to="VBoxEventType_Any"/> to specify wildcards, matching more + than one event. + </desc> + </param> + <param name="active" type="boolean" dir="in"> + <desc> + Which mode this listener is operating in. + In active mode, <link to="IEventListener::handleEvent" /> is called directly. + In passive mode, an internal event queue is created for this this IEventListener. + For each event coming in, it is added to queues for all interested registered passive + listeners. It is then up to the external code to call the listener's + <link to="IEventListener::handleEvent" /> method. When done with an event, the + external code must call <link to="#eventProcessed" />. + </desc> + </param> + </method> + + <method name="unregisterListener"> + <desc> + Unregister an event listener. If listener is passive, and some waitable events are still + in queue they are marked as processed automatically. + </desc> + <param name="listener" type="IEventListener" dir="in"> + <desc>Listener to unregister.</desc> + </param> + </method> + + <method name="fireEvent"> + <desc> + Fire an event for this source. + </desc> + <param name="event" type="IEvent" dir="in"> + <desc>Event to deliver.</desc> + </param> + <param name="timeout" type="long" dir="in"> + <desc> + Maximum time to wait for event processing (if event is waitable), in ms; + 0 = no wait, -1 = indefinite wait. + </desc> + </param> + <param name="result" type="boolean" dir="return"> + <desc>true if an event was delivered to all targets, or is non-waitable.</desc> + </param> + </method> + + <method name="getEvent"> + <desc> + Get events from this peer's event queue (for passive mode). Calling this method + regularly is required for passive event listeners to avoid system overload; + see <link to="IEventSource::registerListener" /> for details. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Listener is not registered, or autounregistered. + </result> + </desc> + <param name="listener" type="IEventListener" dir="in"> + <desc>Which listener to get data for.</desc> + </param> + <param name="timeout" type="long" dir="in"> + <desc> + Maximum time to wait for events, in ms; + 0 = no wait, -1 = indefinite wait. + </desc> + </param> + <param name="event" type="IEvent" dir="return"> + <desc>Event retrieved, or null if none available.</desc> + </param> + </method> + + <method name="eventProcessed"> + <desc> + Must be called for waitable events after a particular listener finished its + event processing. When all listeners of a particular event have called this + method, the system will then call <link to="IEvent::setProcessed" />. + </desc> + <param name="listener" type="IEventListener" dir="in"> + <desc>Which listener processed event.</desc> + </param> + <param name="event" type="IEvent" dir="in"> + <desc>Which event.</desc> + </param> + </method> + + </interface> + + <interface + name="IEventListener" extends="$unknown" + uuid="67099191-32e7-4f6c-85ee-422304c71b90" + wsmap="managed" + rest="managed" + > + <desc> + Event listener. An event listener can work in either active or passive mode, depending on the way + it was registered. + See <link to="IEvent" /> for an introduction to VirtualBox event handling. + </desc> + + <method name="handleEvent"> + <desc> + Handle event callback for active listeners. It is not called for + passive listeners. After calling <link to="#handleEvent"/> on all active listeners + and having received acknowledgement from all passive listeners via + <link to="IEventSource::eventProcessed"/>, the event is marked as + processed and <link to="IEvent::waitProcessed"/> will return + immediately. + </desc> + <param name="event" type="IEvent" dir="in"> + <desc>Event available.</desc> + </param> + </method> + + </interface> + + <interface + name="IEvent" extends="$unknown" + uuid="0ca2adba-8f30-401b-a8cd-fe31dbe839c0" + wsmap="managed" + rest="managed" + > + <desc> + Abstract parent interface for VirtualBox events. Actual events will typically implement + a more specific interface which derives from this (see below). + + <b>Introduction to VirtualBox events</b> + + Generally speaking, an event (represented by this interface) signals that something + happened, while an event listener (see <link to="IEventListener" />) represents an + entity that is interested in certain events. In order for this to work with + unidirectional protocols (i.e. web services), the concepts of passive and active + listener are used. + + Event consumers can register themselves as listeners, providing an array of + events they are interested in (see <link to="IEventSource::registerListener" />). + When an event triggers, the listener is notified about the event. The exact + mechanism of the notification depends on whether the listener was registered as + an active or passive listener: + + <ul> + <li>An active listener is very similar to a callback: it is a function invoked + by the API. As opposed to the callbacks that were used in the API before + VirtualBox 4.0 however, events are now objects with an interface hierarchy. + </li> + + <li>Passive listeners are somewhat trickier to implement, but do not require + a client function to be callable, which is not an option with scripting + languages or web service clients. Internally the <link to="IEventSource" /> + implementation maintains an event queue for each passive listener, and + newly arrived events are put in this queue. When the listener calls + <link to="IEventSource::getEvent"/>, first element from its internal event + queue is returned. When the client completes processing of an event, + the <link to="IEventSource::eventProcessed" /> function must be called, + acknowledging that the event was processed. It supports implementing + waitable events. On passive listener unregistration, all events from its + queue are auto-acknowledged. + </li> + </ul> + + Waitable events are useful in situations where the event generator wants to track + delivery or a party wants to wait until all listeners have completed the event. A + typical example would be a vetoable event (see <link to="IVetoEvent" />) where a + listeners might veto a certain action, and thus the event producer has to make + sure that all listeners have processed the event and not vetoed before taking + the action. + + A given event may have both passive and active listeners at the same time. + + <b>Using events</b> + + Any VirtualBox object capable of producing externally visible events provides an + @c eventSource read-only attribute, which is of the type <link to="IEventSource" />. + This event source object is notified by VirtualBox once something has happened, so + consumers may register event listeners with this event source. To register a listener, + an object implementing the <link to="IEventListener" /> interface must be provided. + For active listeners, such an object is typically created by the consumer, while for + passive listeners <link to="IEventSource::createListener" /> should be used. Please + note that a listener created with <link to="IEventSource::createListener"/> must not be used as an active listener. + + Once created, the listener must be registered to listen for the desired events + (see <link to="IEventSource::registerListener" />), providing an array of + <link to="VBoxEventType" /> enums. Those elements can either be the individual + event IDs or wildcards matching multiple event IDs. + + After registration, the callback's <link to="IEventListener::handleEvent" /> method is + called automatically when the event is triggered, while passive listeners have to call + <link to="IEventSource::getEvent" /> and <link to="IEventSource::eventProcessed" /> in + an event processing loop. + + The IEvent interface is an abstract parent interface for all such VirtualBox events + coming in. As a result, the standard use pattern inside <link to="IEventListener::handleEvent" /> + or the event processing loop is to check the <link to="#type" /> attribute of the event and + then cast to the appropriate specific interface using @c QueryInterface(). + </desc> + + <attribute name="type" readonly="yes" type="VBoxEventType"> + <desc> + Event type. + </desc> + </attribute> + + <attribute name="source" readonly="yes" type="IEventSource"> + <desc> + Source of this event. + </desc> + </attribute> + + <attribute name="waitable" readonly="yes" type="boolean"> + <desc> + If we can wait for this event being processed. If false, <link to="#waitProcessed"/> returns immediately, + and <link to="#setProcessed"/> doesn't make sense. Non-waitable events are generally better performing, + as no additional overhead associated with waitability imposed. + Waitable events are needed when one need to be able to wait for particular event processed, + for example for vetoable changes, or if event refers to some resource which need to be kept immutable + until all consumers confirmed events. + </desc> + </attribute> + + <method name="setProcessed"> + <desc> + Internal method called by the system when all listeners of a particular event have called + <link to="IEventSource::eventProcessed" />. This should not be called by client code. + </desc> + </method> + + <method name="waitProcessed"> + <desc> + Wait until time outs, or this event is processed. Event must be waitable for this operation to have + described semantics, for non-waitable returns true immediately. + </desc> + <param name="timeout" type="long" dir="in"> + <desc> + Maximum time to wait for event processing, in ms; + 0 = no wait, -1 = indefinite wait. + </desc> + </param> + <param name="result" type="boolean" dir="return"> + <desc>If this event was processed before timeout.</desc> + </param> + </method> + </interface> + + + <interface + name="IReusableEvent" extends="IEvent" + uuid="69bfb134-80f6-4266-8e20-16371f68fa25" + wsmap="managed" + > + <desc>Base abstract interface for all reusable events.</desc> + + <attribute name="generation" readonly="yes" type="unsigned long"> + <desc>Current generation of event, incremented on reuse.</desc> + </attribute> + + <method name="reuse"> + <desc> + Marks an event as reused, increments 'generation', fields shall no + longer be considered valid. + </desc> + </method> + </interface> + + <interface + name="IMachineEvent" extends="IEvent" + uuid="92ed7b1a-0d96-40ed-ae46-a564d484325e" + wsmap="managed" id="MachineEvent" + > + <desc>Base abstract interface for all machine events.</desc> + + <attribute name="machineId" readonly="yes" type="uuid" mod="string"> + <desc>ID of the machine this event relates to.</desc> + </attribute> + + </interface> + + <interface + name="IMachineStateChangedEvent" extends="IMachineEvent" + uuid="5748F794-48DF-438D-85EB-98FFD70D18C9" + wsmap="managed" autogen="VBoxEvent" id="OnMachineStateChanged" + > + <desc>Machine state change event.</desc> + + <attribute name="state" readonly="yes" type="MachineState"> + <desc>New execution state.</desc> + </attribute> + </interface> + + <interface + name="IMachineDataChangedEvent" extends="IMachineEvent" + uuid="abe94809-2e88-4436-83d7-50f3e64d0503" + wsmap="managed" autogen="VBoxEvent" id="OnMachineDataChanged" + > + <desc> + Any of the settings of the given machine has changed. + </desc> + + <attribute name="temporary" readonly="yes" type="boolean"> + <desc>@c true if the settings change is temporary. All permanent + settings changes will trigger an event, and only temporary settings + changes for running VMs will trigger an event. Note: sending events + for temporary changes is NOT IMPLEMENTED.</desc> + </attribute> + </interface> + + <interface + name="IMediumRegisteredEvent" extends="IEvent" + uuid="53fac49a-b7f1-4a5a-a4ef-a11dd9c2a458" + wsmap="managed" autogen="VBoxEvent" id="OnMediumRegistered" + > + <desc> + The given medium was registered or unregistered + within this VirtualBox installation. + </desc> + + <attribute name="mediumId" readonly="yes" type="uuid" mod="string"> + <desc>ID of the medium this event relates to.</desc> + </attribute> + + <attribute name="mediumType" readonly="yes" type="DeviceType"> + <desc>Type of the medium this event relates to.</desc> + </attribute> + + <attribute name="registered" type="boolean" readonly="yes"> + <desc> + If @c true, the medium was registered, otherwise it was + unregistered. + </desc> + </attribute> + </interface> + + <interface + name="IMediumConfigChangedEvent" extends="IEvent" + uuid="dd3e2654-a161-41f1-b583-4892f4a9d5d5" + wsmap="managed" autogen="VBoxEvent" id="OnMediumConfigChanged" + > + <desc> + The configuration of the given medium was changed (location, properties, + child/parent or anything else). + </desc> + + <attribute name="medium" type="IMedium" readonly="yes"> + <desc>ID of the medium this event relates to.</desc> + </attribute> + </interface> + + <interface + name="IMachineRegisteredEvent" extends="IMachineEvent" + uuid="c354a762-3ff2-4f2e-8f09-07382ee25088" + wsmap="managed" autogen="VBoxEvent" id="OnMachineRegistered" + > + <desc> + The given machine was registered or unregistered + within this VirtualBox installation. + </desc> + + <attribute name="registered" type="boolean" readonly="yes"> + <desc> + If @c true, the machine was registered, otherwise it was + unregistered. + </desc> + </attribute> + </interface> + + <interface + name="ISessionStateChangedEvent" extends="IMachineEvent" + uuid="714a3eef-799a-4489-86cd-fe8e45b2ff8e" + wsmap="managed" autogen="VBoxEvent" id="OnSessionStateChanged" + > + <desc> + The state of the session for the given machine was changed. + <see><link to="IMachine::sessionState"/></see> + </desc> + + <attribute name="state" type="SessionState" readonly="yes"> + <desc> + New session state. + </desc> + </attribute> + </interface> + + <interface + name="IGuestPropertyChangedEvent" extends="IMachineEvent" + uuid="2d0f4c6f-a77e-45c5-96d2-7ca7daae63a9" + wsmap="managed" autogen="VBoxEvent" id="OnGuestPropertyChanged" + > + <desc> + Notification when a guest property has changed. + </desc> + + <attribute name="name" readonly="yes" type="wstring"> + <desc> + The name of the property that has changed. + </desc> + </attribute> + + <attribute name="value" readonly="yes" type="wstring"> + <desc> + The new property value. + </desc> + </attribute> + + <attribute name="flags" readonly="yes" type="wstring"> + <desc> + The new property flags. + </desc> + </attribute> + + <attribute name="fWasDeleted" readonly="yes" type="boolean"> + <desc> + A flag which indicates that property was deleted. + </desc> + </attribute> + + </interface> + + <interface + name="ISnapshotEvent" extends="IMachineEvent" + uuid="21637b0e-34b8-42d3-acfb-7e96daf77c22" + wsmap="managed" id="SnapshotEvent" + > + <desc>Base interface for all snapshot events.</desc> + + <attribute name="snapshotId" readonly="yes" type="uuid" mod="string"> + <desc>ID of the snapshot this event relates to.</desc> + </attribute> + + </interface> + + <interface + name="ISnapshotTakenEvent" extends="ISnapshotEvent" + uuid="d27c0b3d-6038-422c-b45e-6d4a0503d9f1" + wsmap="managed" autogen="VBoxEvent" id="OnSnapshotTaken" + > + <desc> + A new snapshot of the machine has been taken. + <see><link to="ISnapshot"/></see> + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="ISnapshotDeletedEvent" extends="ISnapshotEvent" + uuid="c48f3401-4a9e-43f4-b7a7-54bd285e22f4" + wsmap="managed" autogen="VBoxEvent" id="OnSnapshotDeleted" + > + <desc> + Snapshot of the given machine has been deleted. + + <note> + This notification is delivered <b>after</b> the snapshot + object has been uninitialized on the server (so that any + attempt to call its methods will return an error). + </note> + + <see><link to="ISnapshot"/></see> + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="ISnapshotRestoredEvent" extends="ISnapshotEvent" + uuid="f4d803b4-9b2d-4377-bfe6-9702e881516b" + wsmap="managed" autogen="VBoxEvent" id="OnSnapshotRestored" + > + <desc> + Snapshot of the given machine has been restored. + <see><link to="ISnapshot"/></see> + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="ISnapshotChangedEvent" extends="ISnapshotEvent" + uuid="07541941-8079-447a-a33e-47a69c7980db" + wsmap="managed" autogen="VBoxEvent" id="OnSnapshotChanged" + > + <desc> + Snapshot properties (name and/or description) have been changed. + <see><link to="ISnapshot"/></see> + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IMousePointerShapeChangedEvent" extends="IEvent" + uuid="a6dcf6e8-416b-4181-8c4a-45ec95177aef" + wsmap="managed" autogen="VBoxEvent" id="OnMousePointerShapeChanged" + > + <desc> + Notification when the guest mouse pointer shape has + changed. The new shape data is given. + </desc> + + <attribute name="visible" type="boolean" readonly="yes"> + <desc> + Flag whether the pointer is visible. + </desc> + </attribute> + <attribute name="alpha" type="boolean" readonly="yes"> + <desc> + Flag whether the pointer has an alpha channel. + </desc> + </attribute> + <attribute name="xhot" type="unsigned long" readonly="yes"> + <desc> + The pointer hot spot X coordinate. + </desc> + </attribute> + <attribute name="yhot" type="unsigned long" readonly="yes"> + <desc> + The pointer hot spot Y coordinate. + </desc> + </attribute> + <attribute name="width" type="unsigned long" readonly="yes"> + <desc> + Width of the pointer shape in pixels. + </desc> + </attribute> + <attribute name="height" type="unsigned long" readonly="yes"> + <desc> + Height of the pointer shape in pixels. + </desc> + </attribute> + <attribute name="shape" type="octet" safearray="yes" readonly="yes"> + <desc> + Shape buffer arrays. + + The @a shape buffer contains a 1-bpp (bits per pixel) AND mask + followed by a 32-bpp XOR (color) mask. + + For pointers without alpha channel the XOR mask pixels are + 32-bit values: (lsb)BGR0(msb). For pointers with alpha channel + the XOR mask consists of (lsb)BGRA(msb) 32-bit values. + + An AND mask is used for pointers with alpha channel, so if the + callback does not support alpha, the pointer could be + displayed as a normal color pointer. + + The AND mask is a 1-bpp bitmap with byte aligned scanlines. The + size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 * + height</tt>. The padding bits at the end of each scanline are + undefined. + + The XOR mask follows the AND mask on the next 4-byte aligned + offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>. + Bytes in the gap between the AND and the XOR mask are undefined. + The XOR mask scanlines have no gap between them and the size of + the XOR mask is: <tt>cXor = width * 4 * height</tt>. + + <note> + If @a shape is 0, only the pointer visibility is changed. + </note> + </desc> + </attribute> + </interface> + + <interface + name="IMouseCapabilityChangedEvent" extends="IEvent" + uuid="4a773393-7a8c-4d57-b228-9ade4049a81f" + wsmap="managed" autogen="VBoxEvent" id="OnMouseCapabilityChanged" + > + <desc> + Notification when the mouse capabilities reported by the + guest have changed. The new capabilities are passed. + </desc> + <attribute name="supportsAbsolute" type="boolean" readonly="yes"> + <desc> + Supports absolute coordinates. + </desc> + </attribute> + <attribute name="supportsRelative" type="boolean" readonly="yes"> + <desc> + Supports relative coordinates. + </desc> + </attribute> + <attribute name="supportsTouchScreen" type="boolean" readonly="yes"> + <desc> + Supports multi-touch events, touchscreen variant. + </desc> + </attribute> + <attribute name="supportsTouchPad" type="boolean" readonly="yes"> + <desc> + Supports multi-touch events, touchpad variant. + </desc> + </attribute> + <attribute name="needsHostCursor" type="boolean" readonly="yes"> + <desc> + If host cursor is needed. + </desc> + </attribute> + </interface> + + <interface + name="IKeyboardLedsChangedEvent" extends="IEvent" + uuid="6DDEF35E-4737-457B-99FC-BC52C851A44F" + wsmap="managed" autogen="VBoxEvent" id="OnKeyboardLedsChanged" + > + <desc> + Notification when the guest OS executes the KBD_CMD_SET_LEDS command + to alter the state of the keyboard LEDs. + </desc> + <attribute name="numLock" type="boolean" readonly="yes"> + <desc> + NumLock status. + </desc> + </attribute> + <attribute name="capsLock" type="boolean" readonly="yes"> + <desc> + CapsLock status. + </desc> + </attribute> + <attribute name="scrollLock" type="boolean" readonly="yes"> + <desc> + ScrollLock status. + </desc> + </attribute> + </interface> + + <interface + name="IStateChangedEvent" extends="IEvent" + uuid="4376693C-CF37-453B-9289-3B0F521CAF27" + wsmap="managed" autogen="VBoxEvent" id="OnStateChanged" + > + <desc> + Notification when the execution state of the machine has changed. + The new state is given. + </desc> + <attribute name="state" type="MachineState" readonly="yes"> + <desc> + New machine state. + </desc> + </attribute> + </interface> + + <interface + name="IAdditionsStateChangedEvent" extends="IEvent" + uuid="D70F7915-DA7C-44C8-A7AC-9F173490446A" + wsmap="managed" autogen="VBoxEvent" id="OnAdditionsStateChanged" + > + <desc> + Notification when a Guest Additions property changes. + Interested callees should query IGuest attributes to + find out what has changed. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="INetworkAdapterChangedEvent" extends="IEvent" + uuid="08889892-1EC6-4883-801D-77F56CFD0103" + wsmap="managed" autogen="VBoxEvent" id="OnNetworkAdapterChanged" + > + <desc> + Notification when a property of one of the + virtual <link to="IMachine::getNetworkAdapter">network adapters</link> + changes. Interested callees should use INetworkAdapter methods and + attributes to find out what has changed. + </desc> + <attribute name="networkAdapter" type="INetworkAdapter" readonly="yes"> + <desc> + Network adapter that is subject to change. + </desc> + </attribute> + </interface> + + <interface + name="IAudioAdapterChangedEvent" extends="IEvent" + uuid="D5ABC823-04D0-4DB6-8D66-DC2F033120E1" + wsmap="managed" autogen="VBoxEvent" id="OnAudioAdapterChanged" + > + <desc> + Notification when a property of the audio adapter changes. + Interested callees should use IAudioAdapter methods and attributes + to find out what has changed. + </desc> + <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes"> + <desc> + Audio adapter that is subject to change. + </desc> + </attribute> + </interface> + + <interface + name="ISerialPortChangedEvent" extends="IEvent" + uuid="3BA329DC-659C-488B-835C-4ECA7AE71C6C" + wsmap="managed" autogen="VBoxEvent" id="OnSerialPortChanged" + > + <desc> + Notification when a property of one of the + virtual <link to="IMachine::getSerialPort">serial ports</link> changes. + Interested callees should use ISerialPort methods and attributes + to find out what has changed. + </desc> + <attribute name="serialPort" type="ISerialPort" readonly="yes"> + <desc> + Serial port that is subject to change. + </desc> + </attribute> + </interface> + + <interface + name="IParallelPortChangedEvent" extends="IEvent" + uuid="813C99FC-9849-4F47-813E-24A75DC85615" + wsmap="managed" autogen="VBoxEvent" id="OnParallelPortChanged" + > + <desc> + Notification when a property of one of the + virtual <link to="IMachine::getParallelPort">parallel ports</link> + changes. Interested callees should use ISerialPort methods and + attributes to find out what has changed. + </desc> + <attribute name="parallelPort" type="IParallelPort" readonly="yes"> + <desc> + Parallel port that is subject to change. + </desc> + </attribute> + </interface> + + <interface + name="IStorageControllerChangedEvent" extends="IEvent" + uuid="6BB335CC-1C58-440C-BB7B-3A1397284C7B" + wsmap="managed" autogen="VBoxEvent" id="OnStorageControllerChanged" + > + <desc> + Notification when a + <link to="IMachine::storageControllers">storage controllers</link> + changes. + </desc> + <attribute name="machinId" type="uuid" mod="string" readonly="yes"> + <desc> + The id of the machine containing the storage controller. + </desc> + </attribute> + <attribute name="controllerName" type="wstring" readonly="yes"> + <desc> + The name of the storage controller. + </desc> + </attribute> + </interface> + + <interface + name="IMediumChangedEvent" extends="IEvent" + uuid="0FE2DA40-5637-472A-9736-72019EABD7DE" + wsmap="managed" autogen="VBoxEvent" id="OnMediumChanged" + > + <desc> + Notification when a + <link to="IMachine::mediumAttachments">medium attachment</link> + changes. + </desc> + <attribute name="mediumAttachment" type="IMediumAttachment" readonly="yes"> + <desc> + Medium attachment that is subject to change. + </desc> + </attribute> + </interface> + + <interface + name="IClipboardModeChangedEvent" extends="IEvent" + uuid="cac21692-7997-4595-a731-3a509db604e5" + wsmap="managed" autogen="VBoxEvent" id="OnClipboardModeChanged" + > + <desc> + Notification when the shared clipboard mode changes. + </desc> + <attribute name="clipboardMode" type="ClipboardMode" readonly="yes"> + <desc> + The new clipboard mode. + </desc> + </attribute> + </interface> + + <interface + name="IClipboardFileTransferModeChangedEvent" extends="IEvent" + uuid="00391758-00B1-4E9D-0000-11FA00F9D583" + wsmap="managed" autogen="VBoxEvent" id="OnClipboardFileTransferModeChanged" + > + <desc> + Notification when the shared clipboard file transfer mode changes. + </desc> + <attribute name="enabled" type="boolean" readonly="yes"> + <desc> + Whether file transfers are allowed or not. + </desc> + </attribute> + </interface> + + <interface + name="IDnDModeChangedEvent" extends="IEvent" + uuid="b55cf856-1f8b-4692-abb4-462429fae5e9" + wsmap="managed" autogen="VBoxEvent" id="OnDnDModeChanged" + > + <desc> + Notification when the drag'n drop mode changes. + </desc> + <attribute name="dndMode" type="DnDMode" readonly="yes"> + <desc> + The new drag'n drop mode. + </desc> + </attribute> + </interface> + + <interface + name="ICPUChangedEvent" extends="IEvent" + uuid="4da2dec7-71b2-4817-9a64-4ed12c17388e" + wsmap="managed" autogen="VBoxEvent" id="OnCPUChanged" + > + <desc> + Notification when a CPU changes. + </desc> + <attribute name="CPU" type="unsigned long" readonly="yes"> + <desc> + The CPU which changed. + </desc> + </attribute> + <attribute name="add" type="boolean" readonly="yes"> + <desc> + Flag whether the CPU was added or removed. + </desc> + </attribute> + </interface> + + <interface + name="ICPUExecutionCapChangedEvent" extends="IEvent" + uuid="dfa7e4f5-b4a4-44ce-85a8-127ac5eb59dc" + wsmap="managed" autogen="VBoxEvent" id="OnCPUExecutionCapChanged" + > + <desc> + Notification when the CPU execution cap changes. + </desc> + <attribute name="executionCap" type="unsigned long" readonly="yes"> + <desc> + The new CPU execution cap value. (1-100) + </desc> + </attribute> + </interface> + + <interface + name="IGuestKeyboardEvent" extends="IEvent" + uuid="88394258-7006-40d4-b339-472ee3801844" + wsmap="managed" autogen="VBoxEvent" id="OnGuestKeyboard" + > + <desc> + Notification when guest keyboard event happens. + </desc> + <attribute name="scancodes" type="long" safearray="yes" readonly="yes"> + <desc> + Array of scancodes. + </desc> + </attribute> + </interface> + + <enum + name="GuestMouseEventMode" + uuid="4b500146-ebba-4b7c-bc29-69c2d57a5caf" + > + + <desc> + The mode (relative, absolute, multi-touch) of a pointer event. + + @todo A clear pattern seems to be emerging that we should usually have + multiple input devices active for different types of reporting, so we + should really have different event types for relative (including wheel), + absolute (not including wheel) and multi-touch events. + </desc> + + <const name="Relative" value="0"> + <desc> + Relative event. + </desc> + </const> + + <const name="Absolute" value="1"> + <desc> + Absolute event. + </desc> + </const> + </enum> + + <interface + name="IGuestMouseEvent" extends="IReusableEvent" + uuid="179f8647-319c-4e7e-8150-c5837bd265f6" + wsmap="managed" autogen="VBoxEvent" id="OnGuestMouse" + > + <desc> + Notification when guest mouse event happens. + </desc> + + <attribute name="mode" type="GuestMouseEventMode" readonly="yes"> + <desc> + If this event is relative, absolute or multi-touch. + </desc> + </attribute> + + <attribute name="x" type="long" readonly="yes"> + <desc> + New X position, or X delta. + </desc> + </attribute> + + <attribute name="y" type="long" readonly="yes"> + <desc> + New Y position, or Y delta. + </desc> + </attribute> + + <attribute name="z" type="long" readonly="yes"> + <desc> + Z delta. + </desc> + </attribute> + + <attribute name="w" type="long" readonly="yes"> + <desc> + W delta. + </desc> + </attribute> + + <attribute name="buttons" type="long" readonly="yes"> + <desc> + Button state bitmask. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestMultiTouchEvent" extends="IEvent" + uuid="1f99d9dc-c144-4c28-9f88-e6f488db5441" + wsmap="managed" autogen="VBoxEvent" id="OnGuestMultiTouch" + > + <desc> + Notification when guest touch screen event happens. + </desc> + <attribute name="contactCount" type="long" readonly="yes"> + <desc> + Number of contacts in the event. + </desc> + </attribute> + <attribute name="xPositions" type="short" safearray="yes" readonly="yes"> + <desc> + X positions. + </desc> + </attribute> + <attribute name="yPositions" type="short" safearray="yes" readonly="yes"> + <desc> + Y positions. + </desc> + </attribute> + <attribute name="contactIds" type="unsigned short" safearray="yes" readonly="yes"> + <desc> + Contact identifiers. + </desc> + </attribute> + <attribute name="contactFlags" type="unsigned short" safearray="yes" readonly="yes"> + <desc> + Contact state. + Bit 0: in contact. + Bit 1: in range. + </desc> + </attribute> + <attribute name="isTouchScreen" type="boolean" readonly="yes"> + <desc> + Distinguishes between touchscreen and touchpad events. + </desc> + </attribute> + <attribute name="scanTime" type="unsigned long" readonly="yes"> + <desc> + Timestamp of the event in milliseconds. Only relative time between events is important. + </desc> + </attribute> + </interface> + + <interface + name="IGuestSessionEvent" extends="IEvent" + uuid="b9acd33f-647d-45ac-8fe9-f49b3183ba37" + wsmap="managed" + > + <desc>Base abstract interface for all guest session events.</desc> + + <attribute name="session" type="IGuestSession" readonly="yes"> + <desc>Guest session that is subject to change.</desc> + </attribute> + + </interface> + + <interface + name="IGuestSessionStateChangedEvent" extends="IGuestSessionEvent" + uuid="327e3c00-ee61-462f-aed3-0dff6cbf9904" + wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionStateChanged" + > + <desc> + Notification when a guest session changed its state. + </desc> + + <attribute name="id" type="unsigned long" readonly="yes"> + <desc> + Session ID of guest session which was changed. + </desc> + </attribute> + <attribute name="status" type="GuestSessionStatus" readonly="yes"> + <desc> + New session status. + </desc> + </attribute> + <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + Error information in case of new session status is indicating an error. + + The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain + the runtime (IPRT) error code from the guest. See include/iprt/err.h and + include/VBox/err.h for details. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestSessionRegisteredEvent" extends="IGuestSessionEvent" + uuid="b79de686-eabd-4fa6-960a-f1756c99ea1c" + wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionRegistered" + > + <desc> + Notification when a guest session was registered or unregistered. + </desc> + + <attribute name="registered" type="boolean" readonly="yes"> + <desc> + If @c true, the guest session was registered, otherwise it was + unregistered. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessEvent" extends="IGuestSessionEvent" + uuid="2405f0e5-6588-40a3-9b0a-68c05ba52c4b" + wsmap="managed" + > + <desc>Base abstract interface for all guest process events.</desc> + + <attribute name="process" type="IGuestProcess" readonly="yes"> + <desc> + Guest process object which is related to this event. + </desc> + </attribute> + <attribute name="pid" type="unsigned long" readonly="yes"> + <desc> + Guest process ID (PID). + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessRegisteredEvent" extends="IGuestProcessEvent" + uuid="1d89e2b3-c6ea-45b6-9d43-dc6f70cc9f02" + wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessRegistered" + > + <desc> + Notification when a guest process was registered or unregistered. + </desc> + + <attribute name="registered" type="boolean" readonly="yes"> + <desc> + If @c true, the guest process was registered, otherwise it was + unregistered. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessStateChangedEvent" extends="IGuestProcessEvent" + uuid="c365fb7b-4430-499f-92c8-8bed814a567a" + wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessStateChanged" + > + <desc> + Notification when a guest process changed its state. + </desc> + + <attribute name="status" type="ProcessStatus" readonly="yes"> + <desc> + New guest process status. + </desc> + </attribute> + <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + Error information in case of new session status is indicating an error. + + The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain + the runtime (IPRT) error code from the guest. See include/iprt/err.h and + include/VBox/err.h for details. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessIOEvent" extends="IGuestProcessEvent" + uuid="9ea9227c-e9bb-49b3-bfc7-c5171e93ef38" + wsmap="managed" + > + <desc> + Base abstract interface for all guest process input/output (IO) events. + </desc> + + <attribute name="handle" type="unsigned long" readonly="yes"> + <desc> + Input/output (IO) handle involved in this event. Usually 0 is stdin, + 1 is stdout and 2 is stderr. + </desc> + </attribute> + + <attribute name="processed" type="unsigned long" readonly="yes"> + <desc> + Processed input or output (in bytes). + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessInputNotifyEvent" extends="IGuestProcessIOEvent" + uuid="0de887f2-b7db-4616-aac6-cfb94d89ba78" + wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessInputNotify" + > + <desc> + Notification when a guest process' stdin became available. + <note>This event is right now not implemented!</note> + </desc> + + <attribute name="status" type="ProcessInputStatus" readonly="yes"> + <desc> + Current process input status. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessOutputEvent" extends="IGuestProcessIOEvent" + uuid="d3d5f1ee-bcb2-4905-a7ab-cc85448a742b" + wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessOutput" + > + <desc> + Notification when there is guest process output available for reading. + </desc> + + <attribute name="data" type="octet" safearray="yes" readonly="yes"> + <desc> + Actual output data. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileEvent" extends="IGuestSessionEvent" + uuid="c8adb7b0-057d-4391-b928-f14b06b710c5" + wsmap="managed" + > + <desc>Base abstract interface for all guest file events.</desc> + + <attribute name="file" type="IGuestFile" readonly="yes"> + <desc> + Guest file object which is related to this event. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileRegisteredEvent" extends="IGuestFileEvent" + uuid="d0d93830-70a2-487e-895e-d3fc9679f7b3" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRegistered" + > + <desc> + Notification when a guest file was registered or unregistered. + </desc> + + <attribute name="registered" type="boolean" readonly="yes"> + <desc> + If @c true, the guest file was registered, otherwise it was + unregistered. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileStateChangedEvent" extends="IGuestFileEvent" + uuid="d37fe88f-0979-486c-baa1-3abb144dc82d" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileStateChanged" + > + <desc> + Notification when a guest file changed its state. + </desc> + + <attribute name="status" type="FileStatus" readonly="yes"> + <desc> + New guest file status. + </desc> + </attribute> + <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + Error information in case of new session status is indicating an error. + + The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain + the runtime (IPRT) error code from the guest. See include/iprt/err.h and + include/VBox/err.h for details. + </desc> + </attribute> + <!-- Note: No events for reads/writes for performance reasons. + See dedicated events IGuestFileReadEvent and + IGuestFileWriteEvent. --> + + </interface> + + <interface + name="IGuestFileIOEvent" extends="IGuestFileEvent" + uuid="b5191a7c-9536-4ef8-820e-3b0e17e5bbc8" + wsmap="managed" + > + <desc> + Base abstract interface for all guest file input/output (IO) events. + </desc> + + <attribute name="offset" type="long long" readonly="yes"> + <desc> + Current offset (in bytes). + </desc> + </attribute> + <attribute name="processed" type="unsigned long" readonly="yes"> + <desc> + Processed input or output (in bytes). + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileOffsetChangedEvent" extends="IGuestFileIOEvent" + uuid="e8f79a21-1207-4179-94cf-ca250036308f" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileOffsetChanged" + > + <desc> + Notification when a guest file changed its current offset via <link to="IFile::seek" />. + </desc> + + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IGuestFileSizeChangedEvent" extends="IGuestFileEvent" + uuid="d78374e9-486e-472f-481b-969746af2480" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileSizeChanged" + > + <desc> + Notification when a guest file changed its size via <link to="IFile::setSize" />. + </desc> + + <attribute name="newSize" readonly="yes" type="long long"/> + </interface> + + + <interface + name="IGuestFileReadEvent" extends="IGuestFileIOEvent" + uuid="4ee3cbcb-486f-40db-9150-deee3fd24189" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRead" + > + <desc> + Notification when data has been read from a guest file. + </desc> + + <attribute name="data" type="octet" safearray="yes" readonly="yes"> + <desc> + Actual data read. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileWriteEvent" extends="IGuestFileIOEvent" + uuid="e062a915-3cf5-4c0a-bc90-9b8d4cc94d89" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileWrite" + > + <desc> + Notification when data has been written to a guest file. + </desc> + + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IVRDEServerChangedEvent" extends="IEvent" + uuid="a06fd66a-3188-4c8c-8756-1395e8cb691c" + wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerChanged" + > + <desc> + Notification when a property of the + <link to="IMachine::VRDEServer">VRDE server</link> changes. + Interested callees should use IVRDEServer methods and attributes to + find out what has changed. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IVRDEServerInfoChangedEvent" extends="IEvent" + uuid="dd6a1080-e1b7-4339-a549-f0878115596e" + wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerInfoChanged" + > + <desc> + Notification when the status of the VRDE server changes. Interested callees + should use <link to="IConsole::VRDEServerInfo">IVRDEServerInfo</link> + attributes to find out what is the current status. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IRecordingChangedEvent" extends="IEvent" + uuid="B5DDB370-08A7-4C8F-910D-47AABD67253A" + wsmap="managed" autogen="VBoxEvent" id="OnRecordingChanged" + > + <desc> + Notification when recording settings have changed. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IUSBControllerChangedEvent" extends="IEvent" + uuid="93BADC0C-61D9-4940-A084-E6BB29AF3D83" + wsmap="managed" autogen="VBoxEvent" id="OnUSBControllerChanged" + > + <desc> + Notification when a property of the virtual + <link to="IMachine::USBControllers">USB controllers</link> changes. + Interested callees should use IUSBController methods and attributes to + find out what has changed. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IUSBDeviceStateChangedEvent" extends="IEvent" + uuid="806da61b-6679-422a-b629-51b06b0c6d93" + wsmap="managed" autogen="VBoxEvent" id="OnUSBDeviceStateChanged" + > + <desc> + Notification when a USB device is attached to or detached from + the virtual USB controller. + + This notification is sent as a result of the indirect + request to attach the device because it matches one of the + machine USB filters, or as a result of the direct request + issued by <link to="IConsole::attachUSBDevice"/> or + <link to="IConsole::detachUSBDevice"/>. + + This notification is sent in case of both a succeeded and a + failed request completion. When the request succeeds, the + @a error parameter is @c null, and the given device has been + already added to (when @a attached is @c true) or removed from + (when @a attached is @c false) the collection represented by + <link to="IConsole::USBDevices"/>. On failure, the collection + doesn't change and the @a error parameter represents the error + message describing the failure. + </desc> + <attribute name="device" type="IUSBDevice" readonly="yes"> + <desc> + Device that is subject to state change. + </desc> + </attribute> + <attribute name="attached" type="boolean" readonly="yes"> + <desc> + @c true if the device was attached and @c false otherwise. + </desc> + </attribute> + <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + @c null on success or an error message object on failure. + </desc> + </attribute> + </interface> + + <interface + name="ISharedFolderChangedEvent" extends="IEvent" + uuid="B66349B5-3534-4239-B2DE-8E1535D94C0B" + wsmap="managed" autogen="VBoxEvent" id="OnSharedFolderChanged" + > + <desc> + Notification when a shared folder is added or removed. + The @a scope argument defines one of three scopes: + <link to="IVirtualBox::sharedFolders">global shared folders</link> + (<link to="Scope_Global">Global</link>), + <link to="IMachine::sharedFolders">permanent shared folders</link> of + the machine (<link to="Scope_Machine">Machine</link>) or <link + to="IConsole::sharedFolders">transient shared folders</link> of the + machine (<link to="Scope_Session">Session</link>). Interested callees + should use query the corresponding collections to find out what has + changed. + </desc> + <attribute name="scope" type="Scope" readonly="yes"> + <desc> + Scope of the notification. + </desc> + </attribute> + </interface> + + <interface + name="IRuntimeErrorEvent" extends="IEvent" + uuid="883DD18B-0721-4CDE-867C-1A82ABAF914C" + wsmap="managed" autogen="VBoxEvent" autogenflags="BSTR" id="OnRuntimeError" + > + <desc> + Notification when an error happens during the virtual + machine execution. + + There are three kinds of runtime errors: + <ul> + <li><i>fatal</i></li> + <li><i>non-fatal with retry</i></li> + <li><i>non-fatal warnings</i></li> + </ul> + + <b>Fatal</b> errors are indicated by the @a fatal parameter set + to @c true. In case of fatal errors, the virtual machine + execution is always paused before calling this notification, and + the notification handler is supposed either to immediately save + the virtual machine state using <link to="IMachine::saveState"/> + or power it off using <link to="IConsole::powerDown"/>. + Resuming the execution can lead to unpredictable results. + + <b>Non-fatal</b> errors and warnings are indicated by the + @a fatal parameter set to @c false. If the virtual machine + is in the Paused state by the time the error notification is + received, it means that the user can <i>try to resume</i> the machine + execution after attempting to solve the problem that caused the + error. In this case, the notification handler is supposed + to show an appropriate message to the user (depending on the + value of the @a id parameter) that offers several actions such + as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user + wants to retry, the notification handler should continue + the machine execution using the <link to="IConsole::resume"/> + call. If the machine execution is not Paused during this + notification, then it means this notification is a <i>warning</i> + (for example, about a fatal condition that can happen very soon); + no immediate action is required from the user, the machine + continues its normal execution. + + Note that in either case the notification handler + <b>must not</b> perform any action directly on a thread + where this notification is called. Everything it is allowed to + do is to post a message to another thread that will then talk + to the user and take the corresponding action. + + Currently, the following error identifiers are known: + <ul> + <li><tt>"HostMemoryLow"</tt></li> + <li><tt>"HostAudioNotResponding"</tt></li> + <li><tt>"VDIStorageFull"</tt></li> + <li><tt>"3DSupportIncompatibleAdditions"</tt></li> + </ul> + </desc> + <attribute name="fatal" type="boolean" readonly="yes"> + <desc> + Whether the error is fatal or not. + </desc> + </attribute> + <attribute name="id" type="wstring" readonly="yes"> + <desc> + Error identifier. + </desc> + </attribute> + <attribute name="message" type="wstring" readonly="yes"> + <desc> + Optional error message. + </desc> + </attribute> + </interface> + + + <interface + name="IEventSourceChangedEvent" extends="IEvent" + uuid="e7932cb8-f6d4-4ab6-9cbf-558eb8959a6a" + waitable="yes" + wsmap="managed" autogen="VBoxEvent" id="OnEventSourceChanged" + > + <desc> + Notification when an event source state changes (listener added or removed). + </desc> + + <attribute name="listener" type="IEventListener" readonly="yes"> + <desc> + Event listener which has changed. + </desc> + </attribute> + + <attribute name="add" type="boolean" readonly="yes"> + <desc> + Flag whether listener was added or removed. + </desc> + </attribute> + </interface> + + <interface + name="IExtraDataChangedEvent" extends="IEvent" + uuid="024F00CE-6E0B-492A-A8D0-968472A94DC7" + wsmap="managed" autogen="VBoxEvent" autogenflags="BSTR" id="OnExtraDataChanged" + > + <desc> + Notification when machine specific or global extra data + has changed. + </desc> + <attribute name="machineId" type="uuid" mod="string" readonly="yes"> + <desc> + ID of the machine this event relates to. + Null for global extra data changes. + </desc> + </attribute> + <attribute name="key" type="wstring" readonly="yes"> + <desc> + Extra data key that has changed. + </desc> + </attribute> + <attribute name="value" type="wstring" readonly="yes"> + <desc> + Extra data value for the given key. + </desc> + </attribute> + </interface> + + <interface + name="IVetoEvent" extends="IEvent" + uuid="7c5e945f-2354-4267-883f-2f417d216519" + wsmap="managed" + > + <desc>Base abstract interface for veto events.</desc> + + <method name="addVeto"> + <desc> + Adds a veto on this event. + </desc> + <param name="reason" type="wstring" dir="in"> + <desc> + Reason for veto, could be null or empty string. + </desc> + </param> + </method> + + <method name="isVetoed"> + <desc> + If this event was vetoed. + </desc> + <param name="result" type="boolean" dir="return"> + <desc> + Reason for veto. + </desc> + </param> + </method> + + <method name="getVetos"> + <desc> + Current veto reason list, if size is 0 - no veto. + </desc> + <param name="result" type="wstring" dir="return" safearray="yes"> + <desc> + Array of reasons for veto provided by different event handlers. + </desc> + </param> + </method> + + <method name="addApproval"> + <desc> + Adds an approval on this event. + </desc> + <param name="reason" type="wstring" dir="in"> + <desc> + Reason for approval, could be null or empty string. + </desc> + </param> + </method> + + <method name="isApproved"> + <desc> + If this event was approved. + </desc> + <param name="result" type="boolean" dir="return" /> + </method> + + <method name="getApprovals"> + <desc> + Current approval reason list, if size is 0 - no approvals. + </desc> + <param name="result" type="wstring" dir="return" safearray="yes"> + <desc> + Array of reasons for approval provided by different event handlers. + </desc> + </param> + </method> + + </interface> + + <interface + name="IExtraDataCanChangeEvent" extends="IVetoEvent" + uuid="245d88bd-800a-40f8-87a6-170d02249a55" + wsmap="managed" autogen="VBoxEvent" id="OnExtraDataCanChange" + waitable="yes" + > + <desc> + Notification when someone tries to change extra data for + either the given machine or (if @c null) global extra data. + This gives the chance to veto against changes. + </desc> + <attribute name="machineId" type="uuid" mod="string" readonly="yes"> + <desc> + ID of the machine this event relates to. + Null for global extra data changes. + </desc> + </attribute> + <attribute name="key" type="wstring" readonly="yes"> + <desc> + Extra data key that has changed. + </desc> + </attribute> + <attribute name="value" type="wstring" readonly="yes"> + <desc> + Extra data value for the given key. + </desc> + </attribute> + </interface> + + <interface + name="ICanShowWindowEvent" extends="IVetoEvent" + uuid="adf292b0-92c9-4a77-9d35-e058b39fe0b9" + wsmap="managed" autogen="VBoxEvent" id="OnCanShowWindow" + waitable="yes" + > + <desc> + Notification when a call to + <link to="IMachine::canShowConsoleWindow"/> is made by a + front-end to check if a subsequent call to + <link to="IMachine::showConsoleWindow"/> can succeed. + + The callee should give an answer appropriate to the current + machine state using event veto. This answer must + remain valid at least until the next + <link to="IConsole::state">machine state</link> change. + </desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IShowWindowEvent" extends="IEvent" + uuid="B0A0904D-2F05-4D28-855F-488F96BAD2B2" + wsmap="managed" autogen="VBoxEvent" id="OnShowWindow" + waitable="yes" + > + <desc> + Notification when a call to + <link to="IMachine::showConsoleWindow"/> + requests the console window to be activated and brought to + foreground on the desktop of the host PC. + + This notification should cause the VM console process to + perform the requested action as described above. If it is + impossible to do it at a time of this notification, this + method should return a failure. + + Note that many modern window managers on many platforms + implement some sort of focus stealing prevention logic, so + that it may be impossible to activate a window without the + help of the currently active application (which is supposedly + an initiator of this notification). In this case, this method + must return a non-zero identifier that represents the + top-level window of the VM console process. The caller, if it + represents a currently active process, is responsible to use + this identifier (in a platform-dependent manner) to perform + actual window activation. + + This method must set @a winId to zero if it has performed all + actions necessary to complete the request and the console + window is now active and in foreground, to indicate that no + further action is required on the caller's side. + </desc> + <attribute name="winId" type="long long"> + <desc> + Platform-dependent identifier of the top-level VM console + window, or zero if this method has performed all actions + necessary to implement the <i>show window</i> semantics for + the given platform and/or this VirtualBox front-end. + </desc> + </attribute> + </interface> + + <interface + name="INATRedirectEvent" extends="IMachineEvent" + uuid="24eef068-c380-4510-bc7c-19314a7352f1" + wsmap="managed" autogen="VBoxEvent" id="OnNATRedirect" + > + <desc> + Notification when NAT redirect rule added or removed. + </desc> + <attribute name="slot" type="unsigned long" readonly="yes"> + <desc> + Adapter which NAT attached to. + </desc> + </attribute> + <attribute name="remove" type="boolean" readonly="yes"> + <desc> + Whether rule remove or add. + </desc> + </attribute> + <attribute name="name" type="wstring" readonly="yes"> + <desc> + Name of the rule. + </desc> + </attribute> + <attribute name="proto" type="NATProtocol" readonly="yes"> + <desc> + Protocol (TCP or UDP) of the redirect rule. + </desc> + </attribute> + <attribute name="hostIP" type="wstring" readonly="yes"> + <desc> + Host ip address to bind socket on. + </desc> + </attribute> + <attribute name="hostPort" type="long" readonly="yes"> + <desc> + Host port to bind socket on. + </desc> + </attribute> + <attribute name="guestIP" type="wstring" readonly="yes"> + <desc> + Guest ip address to redirect to. + </desc> + </attribute> + <attribute name="guestPort" type="long" readonly="yes"> + <desc> + Guest port to redirect to. + </desc> + </attribute> + </interface> + + <interface + name="IHostAudioDeviceChangedEvent" extends="IEvent" + waitable="yes" + uuid="8dcc633f-7b03-4f0a-9f40-7a784dd0835a" + wsmap="managed" autogen="VBoxEvent" id="OnHostAudioDeviceChangedEvent" + > + <desc> + Notification when a host audio device state has changed. + </desc> + + <attribute name="device" type="IHostAudioDevice" readonly="yes"> + <desc> + Host audio device that has changed. + </desc> + </attribute> + + <attribute name="new" type="boolean" readonly="yes"> + <desc> + @c true if the host device is a newly detected device, @c false if not. + </desc> + </attribute> + + <attribute name="state" type="AudioDeviceState" readonly="yes"> + <desc> + New audio device state. + </desc> + </attribute> + + <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + @c null on success or an error message object on failure. + </desc> + </attribute> + + </interface> + + <interface + name="IHostPCIDevicePlugEvent" extends="IMachineEvent" + waitable="yes" + uuid="a0bad6df-d612-47d3-89d4-db3992533948" + wsmap="managed" autogen="VBoxEvent" autogenflags="BSTR" id="OnHostPCIDevicePlug" + > + <desc> + Notification when host PCI device is plugged/unplugged. Plugging + usually takes place on VM startup, unplug - when + <link to="IMachine::detachHostPCIDevice"/> is called. + + <see><link to="IMachine::detachHostPCIDevice"/></see> + + </desc> + + <attribute name="plugged" type="boolean" readonly="yes"> + <desc> + If device successfully plugged or unplugged. + </desc> + </attribute> + + <attribute name="success" type="boolean" readonly="yes"> + <desc> + If operation was successful, if false - 'message' attribute + may be of interest. + </desc> + </attribute> + + <attribute name="attachment" type="IPCIDeviceAttachment" readonly="yes"> + <desc> + Attachment info for this device. + </desc> + </attribute> + + <attribute name="message" type="wstring" readonly="yes"> + <desc> + Optional error message. + </desc> + </attribute> + + </interface> + + <interface + name="IVBoxSVCAvailabilityChangedEvent" extends="IEvent" + uuid="97c78fcd-d4fc-485f-8613-5af88bfcfcdc" + wsmap="managed" autogen="VBoxEvent" id="OnVBoxSVCAvailabilityChanged" + > + <desc> + Notification when VBoxSVC becomes unavailable (due to a crash or similar + unexpected circumstances) or available again. + </desc> + + <attribute name="available" type="boolean" readonly="yes"> + <desc> + Whether VBoxSVC is available now. + </desc> + </attribute> + </interface> + + <interface + name="IBandwidthGroupChangedEvent" extends="IEvent" + uuid="334df94a-7556-4cbc-8c04-043096b02d82" + wsmap="managed" autogen="VBoxEvent" id="OnBandwidthGroupChanged" + > + <desc> + Notification when one of the bandwidth groups changed + </desc> + <attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes"> + <desc> + The changed bandwidth group. + </desc> + </attribute> + </interface> + + <enum + name="GuestMonitorChangedEventType" + uuid="ef172985-7e36-4297-95be-e46396968d66" + > + + <desc> + How the guest monitor has been changed. + </desc> + + <const name="Enabled" value="0"> + <desc> + The guest monitor has been enabled by the guest. + </desc> + </const> + + <const name="Disabled" value="1"> + <desc> + The guest monitor has been disabled by the guest. + </desc> + </const> + + <const name="NewOrigin" value="2"> + <desc> + The guest monitor origin has changed in the guest. + </desc> + </const> + </enum> + + <interface + name="IGuestMonitorChangedEvent" extends="IEvent" + uuid="0f7b8a22-c71f-4a36-8e5f-a77d01d76090" + wsmap="managed" autogen="VBoxEvent" id="OnGuestMonitorChanged" + > + <desc> + Notification when the guest enables one of its monitors. + </desc> + + <attribute name="changeType" type="GuestMonitorChangedEventType" readonly="yes"> + <desc> + What was changed for this guest monitor. + </desc> + </attribute> + + <attribute name="screenId" type="unsigned long" readonly="yes"> + <desc> + The monitor which was changed. + </desc> + </attribute> + + <attribute name="originX" type="unsigned long" readonly="yes"> + <desc> + Physical X origin relative to the primary screen. + Valid for Enabled and NewOrigin. + </desc> + </attribute> + + <attribute name="originY" type="unsigned long" readonly="yes"> + <desc> + Physical Y origin relative to the primary screen. + Valid for Enabled and NewOrigin. + </desc> + </attribute> + + <attribute name="width" type="unsigned long" readonly="yes"> + <desc> + Width of the screen. + Valid for Enabled. + </desc> + </attribute> + + <attribute name="height" type="unsigned long" readonly="yes"> + <desc> + Height of the screen. + Valid for Enabled. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestUserStateChangedEvent" extends="IEvent" + uuid="39b4e759-1ec0-4c0f-857f-fbe2a737a256" + wsmap="managed" autogen="VBoxEvent" id="OnGuestUserStateChanged" + > + <desc> + Notification when a guest user changed its state. + </desc> + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + Name of the guest user whose state changed. + </desc> + </attribute> + <attribute name="domain" type="wstring" readonly="yes"> + <desc> + Name of the FQDN (fully qualified domain name) this user is bound + to. Optional. + </desc> + </attribute> + <attribute name="state" type="GuestUserState" readonly="yes"> + <desc> + What was changed for this guest user. See <link to="GuestUserState"/> for + more information. + </desc> + </attribute> + <attribute name="stateDetails" type="wstring" readonly="yes"> + <desc> + Optional state details, depending on the <link to="#state"/> attribute. + </desc> + </attribute> + + </interface> + + <interface + name="IStorageDeviceChangedEvent" extends="IEvent" + uuid="232e9151-ae84-4b8e-b0f3-5c20c35caac9" + wsmap="managed" autogen="VBoxEvent" id="OnStorageDeviceChanged" + > + <desc> + Notification when a + <link to="IMachine::mediumAttachments">storage device</link> + is attached or removed. + </desc> + <attribute name="storageDevice" type="IMediumAttachment" readonly="yes"> + <desc> + Storage device that is subject to change. + </desc> + </attribute> + <attribute name="removed" type="boolean" readonly="yes"> + <desc> + Flag whether the device was removed or added to the VM. + </desc> + </attribute> + <attribute name="silent" type="boolean" readonly="yes"> + <desc> + Flag whether the guest should be notified about the change. + </desc> + </attribute> + </interface> + + <interface + name="INATNetworkChangedEvent" extends="IEvent" + uuid="101ae042-1a29-4a19-92cf-02285773f3b5" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkChanged" + > + <!-- network name is common setting for all event types --> + <attribute name="networkName" type="wstring" readonly="yes"/> + </interface> + + <!-- base class for start/stop events --> + <interface name="INATNetworkStartStopEvent" extends="INATNetworkChangedEvent" + uuid="269d8f6b-fa1e-4cee-91c7-6d8496bea3c1" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkStartStop"> + <attribute name="startEvent" type="boolean" readonly="yes"> + <desc> + IsStartEvent is true when NAT network is started and false on stopping. + </desc> + </attribute> + </interface> + + <!-- base class for modification events --> + <interface + name="INATNetworkAlterEvent" extends="INATNetworkChangedEvent" + uuid="d947adf5-4022-dc80-5535-6fb116815604" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkAlter" + > + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface name="INATNetworkCreationDeletionEvent" extends="INATNetworkAlterEvent" + uuid="8d984a7e-b855-40b8-ab0c-44d3515b4528" + wsmap="managed" autogen="VBoxEvent" autogenflags="BSTR" id="OnNATNetworkCreationDeletion"> + <attribute name="creationEvent" type="boolean" readonly="yes"/> + </interface> + + <interface name="INATNetworkSettingEvent" extends="INATNetworkAlterEvent" + uuid="9db3a9e6-7f29-4aae-a627-5a282c83092c" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkSetting"> + <attribute name="enabled" type="boolean" readonly="yes"/> + <attribute name="network" type="wstring" readonly="yes"/> + <attribute name="gateway" type="wstring" readonly="yes"/> + <attribute name="advertiseDefaultIPv6RouteEnabled" type="boolean" readonly="yes" dtracename="advertiseDefIPv6Route"/> + <attribute name="needDhcpServer" type="boolean" readonly="yes"/> + </interface> + + <interface name="INATNetworkPortForwardEvent" extends="INATNetworkAlterEvent" + uuid="2514881b-23d0-430a-a7ff-7ed7f05534bc" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkPortForward"> + <attribute name="create" type="boolean" readonly="yes"/> + <attribute name="ipv6" type="boolean" readonly="yes"/> + <attribute name="name" type="wstring" readonly="yes"/> + <attribute name="proto" type="NATProtocol" readonly="yes"/> + <attribute name="hostIp" type="wstring" readonly="yes"/> + <attribute name="hostPort" type="long" readonly="yes"/> + <attribute name="guestIp" type="wstring" readonly="yes"/> + <attribute name="guestPort" type="long" readonly="yes"/> + </interface> + + <interface + name="IHostNameResolutionConfigurationChangeEvent" extends="IEvent" + uuid="f9b9e1cf-cb63-47a1-84fb-02c4894b89a9" + wsmap="managed" autogen="VBoxEvent" id="OnHostNameResolutionConfigurationChange" + dtracename="HostNameResCfgChangeEvent" + > + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="IProgressEvent" extends="IEvent" + uuid="daaf9016-1f04-4191-aa2f-1fac9646ae4c" + wsmap="managed" id="ProgressEvent"> + <desc>Base abstract interface for all progress events.</desc> + + <attribute name="progressId" readonly="yes" type="uuid" mod="string"> + <desc>GUID of the progress this event relates to.</desc> + </attribute> + + </interface> + + <interface + name="IProgressCreatedEvent" extends="IProgressEvent" + uuid="a85bba40-1b93-47bb-b125-dec708c30fc0" + wsmap="managed" autogen="VBoxEvent" id="OnProgressCreated"> + <desc>Notification of a new progress object creation/deletion. + Covers purely projess objects in VBoxSVC. This + event is signaled on the event source of IVirtualBox, unlike + the other progress events.</desc> + + <attribute name="create" readonly="yes" type="boolean"> + <desc>If @c true, the progress object was created, otherwise it + was deleted.</desc> + </attribute> + + </interface> + + <interface + name="IProgressPercentageChangedEvent" extends="IProgressEvent" + uuid="f05d7e60-1bcf-4218-9807-04e036cc70f1" + wsmap="managed" autogen="VBoxEvent" id="OnProgressPercentageChanged"> + <desc>Progress state change event.</desc> + + <attribute name="percent" readonly="yes" type="long"> + <desc>New percent</desc> + </attribute> + </interface> + + <interface + name="IProgressTaskCompletedEvent" extends="IProgressEvent" + uuid="a5bbdb7d-8ce7-469f-a4c2-6476f581ff72" + wsmap="managed" autogen="VBoxEvent" id="OnProgressTaskCompleted"> + <desc>Progress task completion event.</desc> + <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/> + </interface> + + <interface + name="ICursorPositionChangedEvent" extends="IEvent" + uuid="6f302674-c927-11e7-b788-33c248e71fc7" + wsmap="managed" autogen="VBoxEvent" id="OnCursorPositionChanged"> + <desc>The guest reports cursor position data.</desc> + + <attribute name="hasData" readonly="yes" type="boolean"> + <desc>Event contains valid data. If not set, switch back to using the host cursor.</desc> + </attribute> + <attribute name="x" readonly="yes" type="unsigned long"> + <desc>Reported X position</desc> + </attribute> + <attribute name="y" readonly="yes" type="unsigned long"> + <desc>Reported Y position</desc> + </attribute> + </interface> + + <interface + name="IGuestAdditionsStatusChangedEvent" extends="IEvent" + uuid="a443da5b-aa82-4720-bc84-bd097b2b13b8" + wsmap="managed" autogen="VBoxEvent" id="OnGuestAdditionsStatusChanged"> + <desc>The guest addition status changed.</desc> + + <attribute name="facility" type="AdditionsFacilityType" readonly="yes"> + <desc>Facility this event relates to.</desc> + </attribute> + <attribute name="status" type="AdditionsFacilityStatus" readonly="yes"> + <desc>The new facility status.</desc> + </attribute> + <attribute name="runLevel" type="AdditionsRunLevelType" readonly="yes"> + <desc>The new run level.</desc> + </attribute> + <attribute name="timestamp" type="long long" readonly="yes"> + <desc>The millisecond timestamp associated with the event.</desc> + </attribute> + </interface> + + <interface + name="IGuestMonitorInfoChangedEvent" extends="IEvent" + uuid="0b3cdeb2-808e-11e9-b773-133d9330f849" + wsmap="managed" autogen="VBoxEvent" id="OnGuestMonitorInfoChanged"> + <desc>The guest reports cursor position data.</desc> + + <attribute name="output" readonly="yes" type="unsigned long"> + <desc>The virtual display output on which the monitor has changed.</desc> + </attribute> + </interface> + + <interface + name="IUpdateAgentEvent" extends="IEvent" + uuid="ff58a51d-54a1-411c-93e9-3047eb4dcd21" + wsmap="managed"> + <desc> + Abstract base interface for update agent events. + </desc> + <attribute name="agent" readonly="yes" type="IUpdateAgent"> + <desc>Update agent this event belongs to.</desc> + </attribute> + </interface> + + <interface + name="IUpdateAgentSettingsChangedEvent" extends="IUpdateAgentEvent" + uuid="abef51ae-1493-49f4-aa03-efaf106bf086" + wsmap="managed" autogen="VBoxEvent" id="OnUpdateAgentSettingsChanged" + > + <desc> + Notification when update agent settings have been changed. + </desc> + <attribute name="attributeHint" readonly="yes" type="wstring"/> + </interface> + + <interface + name="IUpdateAgentErrorEvent" extends="IUpdateAgentEvent" + uuid="2a88033d-82db-4ac2-97b5-e786c839420e" + wsmap="managed" autogen="VBoxEvent" id="OnUpdateAgentError" + > + <desc> + Notification when an update agent error occurred. + </desc> + + <attribute name="msg" type="wstring" readonly="yes"> + <desc> + Error message in human readable format. + </desc> + </attribute> + + <attribute name="rcError" type="long" readonly="yes"> + <desc> + IPRT-style error code. + </desc> + </attribute> + + </interface> + + <interface + name="IUpdateAgentAvailableEvent" extends="IUpdateAgentEvent" + uuid="243829cb-15b7-42a4-8664-7aa4e34993da" + wsmap="managed" autogen="VBoxEvent" id="OnUpdateAgentAvailable" + > + <desc> + Notification when an update is available. + </desc> + + <attribute name="version" type="wstring" readonly="yes"> + <desc> + Version of the update. + </desc> + </attribute> + + <attribute name="channel" type="UpdateChannel" readonly="yes"> + <desc> + Channel containing the update. + </desc> + </attribute> + + <attribute name="severity" type="UpdateSeverity" readonly="yes"> + <desc> + Severity of the update. + </desc> + </attribute> + + <attribute name="downloadURL" type="wstring" readonly="yes"> + <desc> + Download URL of the update. + </desc> + </attribute> + + <attribute name="webURL" type="wstring" readonly="yes"> + <desc> + Web URL of the update. + </desc> + </attribute> + + <attribute name="releaseNotes" type="wstring" readonly="yes"> + <desc> + Release notes of the update. + </desc> + </attribute> + + </interface> + + <interface + name="IUpdateAgentStateChangedEvent" extends="IUpdateAgentEvent" + uuid="eb000a0e-2079-4f47-bbcc-c6b28a4e50df" + wsmap="managed" autogen="VBoxEvent" id="OnUpdateAgentStateChanged" + > + <desc> + Notification when an update agent state has been changed. + </desc> + + <attribute name="state" type="UpdateState" readonly="yes"> + <desc> + New update agent state. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestDebugControlChangedEvent" extends="IEvent" + uuid="a3d2799e-d3ad-4f73-91ef-7d839689f6d6" + wsmap="managed" autogen="VBoxEvent" id="OnGuestDebugControlChanged" + > + <desc> + Notification when a property of the <link to="IMachine::guestDebugControl">guest debug</link> + settings changes. Interested callees should use IGuestDebugControl methods and attributes + to find out what has changed. + </desc> + <attribute name="guestDebugControl" type="IGuestDebugControl" readonly="yes"> + <desc> + Guest debug control object that is subject to change. + </desc> + </attribute> + </interface> + + <interface + name="IMachineGroupsChangedEvent" extends="IMachineEvent" + uuid="ee37afb5-7002-4786-a5c4-a9c29e1cce75" + wsmap="managed" autogen="VBoxEvent" id="OnMachineGroupsChanged" + > + <desc> + The groups of the machine have changed. + </desc> + + <attribute name="dummy" type="boolean" readonly="yes"> + <desc> + Dummy state because you can't have an event without attributes apparently. + </desc> + </attribute> + </interface> + + <!-- + // Auxiliary containers + ////////////////////////////////////////////////////////////////////////// + --> + + <interface name="IStringArray" extends="$unknown" + uuid="3890b2c8-604d-11e9-92d3-53cb473db9fb" + wsmap="managed" + reservedMethods="4"> + <desc> + When you need to return an array of strings asynchronously + (under a progress) you cannot use by-value out parameter + <tt>type="wstring" safearray="yes" + dir="out"</tt>, hence this wrapper. + </desc> + <attribute name="values" type="wstring" safearray="yes" readonly="yes"/> + </interface> + + + <!-- + // IForm + ////////////////////////////////////////////////////////////////////////// + --> + <enum name="FormValueType" + uuid="43d794a0-7c98-11e9-a346-a36d5fa858a5"> + <const name="Boolean" value="0"/> + <const name="String" value="1"/> + <const name="Choice" value="2"/> + <const name="RangedInteger" value="3"/> + </enum> + + <interface name="IFormValue" extends="$unknown" + uuid="67c50afe-3e78-11e9-b25e-7768f80c0e07" + wsmap="managed" + reservedMethods="4" reservedAttributes="8"> + <attribute name="type" type="FormValueType" readonly="yes"/> + <attribute name="generation" type="long" readonly="yes"/> + <attribute name="enabled" type="boolean" readonly="yes"/> + <attribute name="visible" type="boolean" readonly="yes"/> + <attribute name="label" type="wstring" readonly="yes"/> + <attribute name="description" type="wstring" readonly="yes"/> + <attribute name="help" type="wstring" readonly="yes"/> + </interface> + + <interface name="IBooleanFormValue" extends="IFormValue" + uuid="4f4adcf6-3e87-11e9-8af2-576e84223953" + wsmap="managed" + reservedMethods="4" reservedAttributes="4"> + <method name="getSelected"> + <param name="selected" type="boolean" dir="return"/> + </method> + <method name="setSelected"> + <param name="selected" type="boolean" dir="in"/> + <param name="progress" type="IProgress" dir="return"/> + </method> + </interface> + + <interface name="IRangedIntegerFormValue" extends="IFormValue" + uuid="b31c4052-7bdc-11e9-8bc2-8ffdb8b19219" + wsmap="managed" + reservedMethods="4" reservedAttributes="4"> + <attribute name="suffix" type="wstring" readonly="yes"> + <desc> + Counterpart of the <link to="IFormValue::label"/> attribute. + May be null or empty. Usually used for units. + </desc> + </attribute> + <attribute name="minimum" type="long" readonly="yes"/> + <attribute name="maximum" type="long" readonly="yes"/> + <method name="getInteger"> + <param name="value" type="long" dir="return"/> + </method> + <method name="setInteger"> + <param name="value" type="long" dir="in"/> + <param name="progress" type="IProgress" dir="return"/> + </method> + </interface> + + <interface name="IStringFormValue" extends="IFormValue" + uuid="cb6f0f2c-8384-11e9-921d-8b984e28a686" + wsmap="managed" + reservedMethods="4" reservedAttributes="4"> + <attribute name="multiline" type="boolean" readonly="yes"/> + <method name="getString"> + <param name="text" type="wstring" dir="return"/> + </method> + <method name="setString"> + <param name="text" type="wstring" dir="in"/> + <param name="progress" type="IProgress" dir="return"/> + </method> + + <attribute name="clipboardString" type="wstring" readonly="yes"> + <desc> + Intnded for cases when a read-only string value is used to + display information and different string is to be used when + copying to the clipboard. + </desc> + </attribute> + </interface> + + <interface name="IChoiceFormValue" extends="IFormValue" + uuid="7191cf38-3e8a-11e9-825c-ab7b2cabce23" + wsmap="managed" + reservedMethods="4" reservedAttributes="4"> + <attribute name="values" type="wstring" safearray="yes" readonly="yes"/> + <method name="getSelectedIndex"> + <param name="index" type="long" dir="return"/> + </method> + <method name="setSelectedIndex"> + <param name="index" type="long" dir="in"/> + <param name="progress" type="IProgress" dir="return"/> + </method> + </interface> + + <interface name="IForm" extends="$unknown" + uuid="d05c91e2-3e8a-11e9-8082-db8ae479ef87" + wsmap="managed" + reservedMethods="4" reservedAttributes="4"> + <attribute name="values" type="IFormValue" safearray="yes" readonly="yes"/> + + <method name="getFieldGroup"> + <param name="field" type="wstring" dir="in"/> + <param name="group" type="wstring" safearray="yes" dir="return"/> + </method> + + <method name="apply"> + <param name="progress" type="IProgress" dir="return"/> + </method> + </interface> + + <interface name="IVirtualSystemDescriptionForm" extends="IForm" + uuid="14c2db8a-3ee4-11e9-b872-cb9447aad965" + wsmap="managed" + reservedMethods="4" reservedAttributes="4"> + <method name="getVirtualSystemDescription"> + <param name="description" type="IVirtualSystemDescription" dir="return"/> + </method> + </interface> + + <enum + name="CloudMachineState" + uuid="67b6d054-0154-4f5d-b71b-6ac406e1ff78" + > + <desc>Cloud instance execution state</desc> + <const name="Invalid" value="0"> + <desc>Invalid state</desc> + </const> + <const name="Provisioning" value="1"> + <desc>The machine is in the process of provisioning</desc> + </const> + <const name="Running" value="2"> + <desc>The machine runs</desc> + </const> + <const name="Starting" value="3"> + <desc>The machine is in the process of starting</desc> + </const> + <const name="Stopping" value="4"> + <desc>The machine is in the process of stopping</desc> + </const> + <const name="Stopped" value="5"> + <desc>The machine was stopped</desc> + </const> + <const name="CreatingImage" value="6"> + <desc>The machine is in the process of creating image</desc> + </const> + <const name="Terminating" value="7"> + <desc>The machine is in the process of terminating</desc> + </const> + <const name="Terminated" value="8"> + <desc>The machine was terminated</desc> + </const> +</enum> + + <enum + name="CloudImageState" + uuid="6e5d6762-eea2-4f2c-b104-2952d0aa8a0a" + > + <desc>Cloud image state</desc> + <const name="Invalid" value="0"> + <desc>Invalid state</desc> + </const> + <const name="Provisioning" value="1"> + <desc>The image is in the process of provisioning</desc> + </const> + <const name="Importing" value="2"> + <desc>The image is in the process of importing</desc> + </const> + <const name="Available" value="3"> + <desc>The image is avalable</desc> + </const> + <const name="Exporting" value="4"> + <desc>The image is in the process of exporting</desc> + </const> + <const name="Disabled" value="5"> + <desc>The image is disabled</desc> + </const> + <const name="Deleted" value="6"> + <desc>The image was deleted</desc> + </const> +</enum> + + <interface name="ICloudNetworkGatewayInfo" extends="$unknown" + uuid="89a63ace-0c65-11ea-ad23-0ff257c71a7f" + wsmap="managed" + reservedAttributes="5"> + <attribute name="publicIP" type="wstring" readonly="yes"/> + <attribute name="secondaryPublicIP" type="wstring" readonly="yes"/> + <attribute name="macAddress" type="wstring" readonly="yes"/> + <attribute name="instanceId" type="wstring" readonly="yes"/> + </interface> + + + <interface name="ICloudNetworkEnvironmentInfo" extends="$unknown" + uuid="181dfb55-394d-44d3-9edb-af2c4472c40a" + wsmap="managed" + reservedAttributes="7"> + <attribute name="tunnelNetworkId" type="wstring" readonly="yes"/> + </interface> + + + <interface name="ICloudMachine" extends="$unknown" + uuid="147816c8-17e0-11eb-81fa-87cea6263e1a" + wsmap="managed" + rest="managed" + reservedMethods="16" reservedAttributes="8" + > + <desc> + Virtual virtual machine (sic) in the cloud. + + Reading object attributes returns cached values, use + <link to="#refresh"/> to refresh them. + </desc> + + <attribute name="id" type="uuid" mod="string" readonly="yes"> + <desc>UUID of the cloud machine.</desc> + </attribute> + + <attribute name="accessible" type="boolean" readonly="yes" + wrap-hint-server="limitedcaller"> + <desc> + Whether this virtual machine is currently accessible or not. + TBD... + </desc> + </attribute> + + <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes" + wrap-hint-server="limitedcaller"> + <desc> + Error information describing the reason of machine + inaccessibility. + + Reading this property is only valid after the last call to + <link to="#accessible"/> returned @c false (i.e. the + machine is currently inaccessible). Otherwise, a @c null + IVirtualBoxErrorInfo object will be returned. + </desc> + </attribute> + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + Convenience shortcut to retrieve the name of the cloud + machine. The name is part of the machine settings that are + hidden behind the settings form (see <link to="#getSettingsForm"/>). + </desc> + </attribute> + + <attribute name="OSTypeId" type="wstring" readonly="yes"> + <desc> + Convenience shortcut to retrieve the OS Type id of the cloud + machine. It is part of the machine settings that are hidden + behind the settings form (see <link to="#getSettingsForm"/>). + </desc> + </attribute> + + <attribute name="state" type="CloudMachineState" readonly="yes"> + <desc> + Machine state. + </desc> + </attribute> + + <method name="refresh"> + <desc> + Refresh information by reading it from the cloud. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="getDetailsForm" const="yes"> + <desc> + Obtain a form with the current settings for this cloud + machine. The form is not editable. + </desc> + <param name="form" type="IForm" dir="return"> + <desc> + A form with the cloud machine settings. + </desc> + </param> + </method> + + <method name="getSettingsForm"> + <desc> + Obtain a form with settings for this cloud machine. + The form is editable. + </desc> + <param name="form" type="IForm" dir="out"> + <desc> + A form with the cloud machine settings. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="powerUp"> + <desc> + Start cloud virtual machine execution. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="reboot"> + <desc> + Reboot cloud virtual machine. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="shutdown"> + <desc> + Shutdown cloud virtual machine. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="powerDown"> + <desc> + Initiates the power down procedure to stop the virtual machine + execution. + + The completion of the power down procedure is tracked using the returned + IProgress object. After the operation is complete, the machine will go + to the PoweredOff state. + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine must be Running, to be powered down. + </result> + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="terminate"> + <desc> + Terminate cloud virtual machine. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="unregister" wrap-hint-server="limitedcaller,passcaller"> + <desc> + Unregister this cloud machine, but leave the cloud artifacts + intact. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="remove" wrap-hint-server="limitedcaller,passcaller"> + <desc> + Unregister this cloud machine and delete all its cloud artifacts. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="getConsoleHistory"> + <desc> + Get the backlog of the machine's console. If you have ever + seen console teletypes, this is like looking at the last few + meters of the paper it spewed. + </desc> + <param name="stream" type="IDataStream" dir="out"> + <desc> + Data stream object for reading the console history. For now + we are abusing/repurposing this interface from the media + convertion API to avoid marshalling a huge string through + xpcom. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"><desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="createConsoleConnection"> + <param name="sshPublicKey" type="wstring" dir="in"> + <desc> + SSH public key authorized to connect to the console. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="deleteConsoleConnection"> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <attribute name="consoleConnectionFingerprint" type="wstring" readonly="yes"> + <desc> + The fingerprint of the ssh key that is authorized to access + the machine's console connection. + </desc> + </attribute> + + <attribute name="serialConsoleCommand" type="wstring" readonly="yes"> + <desc> + The shell command to establish ssh connection to the cloud + machine serial console. + </desc> + </attribute> + + <attribute name="serialConsoleCommandWindows" type="wstring" readonly="yes"> + <desc> + The PowerShell command to establish ssh connection to the + cloud machine serial console using PuTTY's plink. + </desc> + </attribute> + + <attribute name="VNCConsoleCommand" type="wstring" readonly="yes"> + <desc> + The shell command to establish ssh port forwarding for the + VNC connection to the cloud machine console. + </desc> + </attribute> + + <attribute name="VNCConsoleCommandWindows" type="wstring" readonly="yes"> + <desc> + The PowerShell command to establish ssh port forwarding for the + VNC connection to the cloud machine console using PuTTY's plink. + </desc> + </attribute> + + </interface> + + <!-- + // ICloudClient + ////////////////////////////////////////////////////////////////////////// + --> + <interface + name="ICloudClient" extends="$unknown" + uuid="c2db178a-7485-11ec-aec4-2fbf90681a84" + wsmap="managed" + reservedMethods="16" reservedAttributes="8" + > + + <method name="getExportDescriptionForm"> + <desc> + Returns a form for editing the virtual system description for + exporting a local VM into a cloud custom image. + </desc> + <param name="description" type="IVirtualSystemDescription" dir="in"> + <desc> + Virtual system description to be edited. + </desc> + </param> + <param name="form" type="IVirtualSystemDescriptionForm" dir="out"> + <desc> + An IForm instance for editing the virtual system description. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="exportVM"> + <desc> + Export local VM into the cloud, creating a custom image. + </desc> + <param name="description" type="IVirtualSystemDescription" dir="in"> + <desc> + Virtual system description object which describes the + machine and all required parameters. + </desc> + </param> + <param name="progress" type="IProgress" dir="in"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="getLaunchDescriptionForm"> + <param name="description" type="IVirtualSystemDescription" dir="in"> + <desc> + Virtual system description to be edited. + </desc> + </param> + <param name="form" type="IVirtualSystemDescriptionForm" dir="out"> + <desc> + An IForm instance for editing the virtual system description. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="launchVM"> + <param name="description" type="IVirtualSystemDescription" dir="in"> + <desc> + Virtual system description object which describes the + machine and all required parameters. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="getImportDescriptionForm"> + <desc> + Returns a form for editing the virtual system description for + import from cloud. + </desc> + <param name="description" type="IVirtualSystemDescription" dir="in"> + <desc> + Virtual system description to be edited. + </desc> + </param> + <param name="form" type="IVirtualSystemDescriptionForm" dir="out"> + <desc> + An IForm instance for editing the virtual system description. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="importInstance"> + <desc> + Import an existing cloud instance to the local host. + All needed parameters are passed in the description (VSD). + </desc> + <param name="description" type="IVirtualSystemDescription" dir="in"> + <desc>VirtualSystemDescription object which is describing a machine and all required parameters.</desc> + </param> + <param name="progress" type="IProgress" dir="in"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="getCloudMachine"> + <desc> + Create an object that represents a cloud machine with the + specified UUID. Note that the operation is synchronous. The + returned machine is initiatally in inaccessible state and + requires a refresh to get its data from the cloud. + </desc> + <param name="id" type="uuid" mod="string" dir="in"> + <desc> + UUID of a cloud machine. + </desc> + </param> + <param name="machine" type="ICloudMachine" dir="return"> + <desc> + Object that represents the cloud machine with the specified UUID. + </desc> + </param> + </method> + + <method name="readCloudMachineList"> + <desc> + Make the list of cloud machines available via + <link to="#cloudMachineList"/> attribute. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + <attribute name="cloudMachineList" type="ICloudMachine" safearray="yes" readonly="yes"> + <desc> + See <link to="#readCloudMachineList"/>. + </desc> + </attribute> + + <method name="readCloudMachineStubList"> + <desc> + Make the list of cloud machine stubs available via + <link to="#cloudMachineStubList"/> attribute. + Like with <link to="#getCloudMachine"/>, the returned machines + are initiatally inaccessible and require a refresh to get + their data from the cloud. + </desc> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + <attribute name="cloudMachineStubList" type="ICloudMachine" safearray="yes" readonly="yes"> + <desc> + See <link to="#readCloudMachineStubList"/>. + </desc> + </attribute> + + <method name="addCloudMachine"> + <desc> + Adopt a running instance and register it as cloud machine. + This is kinda like adding a local .vbox file as a local VM. + </desc> + <param name="instanceId" type="wstring" dir="in"> + <desc> + ID of an instance to be added as a cloud machine. + </desc> + </param> + <param name="machine" type="ICloudMachine" dir="out"> + <desc> + Object that represents the newly registered cloud machine. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="createCloudMachine"> + <desc> + This is transitional method that combines + <link to="#launchVM"/> and <link to="#addCloudMachine"/>. + </desc> + <param name="description" type="IVirtualSystemDescription" dir="in"> + <desc> + Virtual system description object which describes the + machine and all required parameters. + </desc> + </param> + <param name="machine" type="ICloudMachine" dir="out"> + <desc> + Object that represents the newly created cloud machine. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="listInstances" const="yes"> + <desc> + Returns the list of the instances in the Cloud. + </desc> + <param name="machineState" type="CloudMachineState" dir="in" safearray="yes"> + <desc>State of each VM.</desc> + </param> + <param name="returnNames" type="IStringArray" dir="out"> + <desc>VM names.</desc> + </param> + <param name="returnIds" type="IStringArray" dir="out"> + <desc>VM ids.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="listSourceInstances" const="yes"> + <desc> + Returns the list of instances in the cloud that can be + added/adopted as VirtualBox cloud machines. + </desc> + <param name="returnNames" type="IStringArray" dir="out"> + <desc>Instance names.</desc> + </param> + <param name="returnIds" type="IStringArray" dir="out"> + <desc>Instance idss.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="listImages" const="yes"> + <desc> + Returns the list of the images in the Cloud. + </desc> + <param name="imageState" type="CloudImageState" dir="in" safearray="yes"> + <desc>State of each image.</desc> + </param> + <param name="returnNames" type="IStringArray" dir="out"> + <desc>Images names.</desc> + </param> + <param name="returnIds" type="IStringArray" dir="out"> + <desc>Images ids.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <!-- quick hack --> + <method name="listBootVolumes" const="yes"> + <desc> + Returns the list of boot volumes in the Cloud. + </desc> + <param name="returnNames" type="IStringArray" dir="out"> + <desc>Boot volume names.</desc> + </param> + <param name="returnIds" type="IStringArray" dir="out"> + <desc>Boot volume ids.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="listSourceBootVolumes" const="yes"> + <desc> + Returns the list of boot volumes in the cloud that can be + added/adopted as VirtualBox cloud machines. + </desc> + <param name="returnNames" type="IStringArray" dir="out"> + <desc>Boot volume names.</desc> + </param> + <param name="returnIds" type="IStringArray" dir="out"> + <desc>Boot volume ids.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="listVnicAttachments" const="yes"> + <desc> + Returns the list of the Vnic attachements in the Cloud. + </desc> + <param name="parameters" type="wstring" dir="in" safearray="yes"> + <desc>Each parameter in the array must be in the form "name=value".</desc> + </param> + <param name="returnVnicAttachmentIds" type="IStringArray" dir="out"> + <desc>VM ids.</desc> + </param> + <param name="returnVnicIds" type="IStringArray" dir="out"> + <desc>VM ids.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="getInstanceInfo" const="yes"> + <desc> + Returns the information about an instance in the Cloud. + </desc> + <param name="uid" type="wstring" dir="in"> + <desc>The id of instance in the Cloud.</desc> + </param> + <param name="description" type="IVirtualSystemDescription" dir="in"> + <desc>VirtualSystemDescription object which is describing a machine</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="startInstance"> + <desc> + Start an existing instance with passed id. + </desc> + <param name="uid" type="wstring" dir="in"> + <desc>The id of instance in the Cloud.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="pauseInstance"> + <desc> + Pause an existing instance with passed id. + </desc> + <param name="uid" type="wstring" dir="in"> + <desc>The id of instance in the Cloud.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="terminateInstance"> + <desc> + Terminate an existing instance with passed id. + </desc> + <param name="uid" type="wstring" dir="in"> + <desc>the id of instance in the Cloud.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="createImage"> + <desc> + Create an image in the Cloud. + </desc> + <param name="parameters" type="wstring" dir="in" safearray="yes"> + <desc>Each parameter in the array must be in the form "name=value".</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="exportImage"> + <desc> + Export an existing VBox image in the Cloud. + </desc> + <param name="image" type="IMedium" dir="in"> + <desc>Reference to the existing VBox image.</desc> + </param> + <param name="parameters" type="wstring" dir="in" safearray="yes"> + <desc>Each parameter in the array must be in the form "name=value".</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="importImage"> + <desc> + Import an existing image in the Cloud to the local host. + </desc> + <param name="uid" type="wstring" dir="in"> + <desc>the id of image in the Cloud.</desc> + </param> + <param name="parameters" type="wstring" dir="in" safearray="yes"> + <desc>Each parameter in the array must be in the form "name=value".</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="deleteImage"> + <desc> + Delete an existing image with passed id from the Cloud. + </desc> + <param name="uid" type="wstring" dir="in"> + <desc>The id of image in the Cloud.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="getImageInfo" const="yes"> + <desc> + Returns the information about an image in the Cloud. + </desc> + <param name="uid" type="wstring" dir="in"> + <desc>The id of image in the Cloud.</desc> + </param> + <param name="infoArray" type="IStringArray" dir="out"> + <desc> + An array where the image settings or properties is returned. + Each parameter in the array must be in the form "name=value". + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="startCloudNetworkGateway"> + <param name="network" type="ICloudNetwork" dir="in"> + <desc>The id of image in the Cloud.</desc> + </param> + <param name="sshPublicKey" type="wstring" dir="in"> + <desc>The id of image in the Cloud.</desc> + </param> + <param name="gatewayInfo" type="ICloudNetworkGatewayInfo" dir="out"> + <desc>Information about the started gateway.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="setupCloudNetworkEnvironment"> + <param name="tunnelNetworkName" type="wstring" dir="in"> + <desc>The name of tunnelling network to be created in the Cloud. If this parameter + is empty the default value "VirtualBox Tunneling Network" is assumed.</desc> + </param> + <param name="tunnelNetworkRange" type="wstring" dir="in"> + <desc>The IP address range of tunnelling network to be created in the Cloud. If this + parameter is empty the default value "10.0.0.0/16" is assumed.</desc> + </param> + <param name="gatewayOsName" type="wstring" dir="in"> + <desc>The name of the operating system to be used for cloud gateway instances. + The default value is "Oracle Linux".</desc> + </param> + <param name="gatewayOsVersion" type="wstring" dir="in"> + <desc>The version of the operating system to be used for cloud gateway instances. + The default value is "7.8".</desc> + </param> + <param name="gatewayShape" type="wstring" dir="in"> + <desc>The shape of cloud gateway instance. The default value is "VM.Standard2.1".</desc> + </param> + <param name="networkEnvironmentInfo" type="ICloudNetworkEnvironmentInfo" dir="out"> + <desc>Information about the created network environment.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + + <method name="getVnicInfo" const="yes"> + <desc> + Returns the information about Vnic in the Cloud. + </desc> + <param name="uid" type="wstring" dir="in"> + <desc>The id of vnic in the Cloud.</desc> + </param> + <param name="infoArray" type="IStringArray" dir="out"> + <desc> + An array where the Vnic settings/properties is returned. + Each parameter in the array must be in the form "name=value". + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + <method name="getSubnetSelectionForm"> + <param name="description" type="IVirtualSystemDescription" dir="in"> + <desc> + Virtual system description to be edited. + </desc> + </param> + <param name="form" type="IVirtualSystemDescriptionForm" dir="out"> + <desc> + An IForm instance for editing the virtual system description. + </desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc> + Progress object to track the operation completion. + </desc> + </param> + </method> + + + </interface> + + <!-- + // ICloudProfile + ////////////////////////////////////////////////////////////////////////// + --> + + <interface + name="ICloudProfile" extends="$unknown" + uuid="b1d978b8-f7b7-4b05-900e-2a9253c00f51" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + + <attribute name="name" type="wstring"> + <desc> + Returns the profile name. + </desc> + </attribute> + + <attribute name="providerId" type="uuid" mod="string" readonly="yes"> + <desc> + Returns provider identifier tied with this profile. + </desc> + </attribute> + + <method name="getProperty" const="yes"> + <desc> + Returns the value of the cloud profile property with the given name. + + If the requested data @a name does not exist, this function will + succeed and return an empty string in the @a value argument. + + <result name="E_INVALIDARG">@a name is @c null or empty.</result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the property to get.</desc> + </param> + <param name="value" type="wstring" dir="return"> + <desc>Current property value.</desc> + </param> + </method> + + <method name="setProperty" const="yes"> + <desc> + Sets the value of the cloud profile property with the given name. + + Setting the property value to @c null or an empty string is equivalent + to deleting the existing value. + + <result name="E_INVALIDARG">@a name is @c null or empty.</result> + </desc> + <param name="name" type="wstring" dir="in"> + <desc>Name of the property to set.</desc> + </param> + <param name="value" type="wstring" dir="in"> + <desc>Property value to set.</desc> + </param> + </method> + + <method name="getProperties" const="yes"> + <desc> + Returns values for a group of properties in one call. + + The names of the properties to get are specified using the @a names + argument which is a list of comma-separated property names or + an empty string if all properties are to be returned. + <note>Currently the value of this argument is ignored and the method + always returns all existing properties.</note> + + The method returns two arrays, the array of property names corresponding + to the @a names argument and the current values of these properties. + Both arrays have the same number of elements with each element at the + given index in the first array corresponds to an element at the same + index in the second array. + </desc> + <param name="names" type="wstring" dir="in"> + <desc> + Names of properties to get. + </desc> + </param> + <param name="returnNames" type="wstring" safearray="yes" dir="out"> + <desc>Names of returned properties.</desc> + </param> + <param name="returnValues" type="wstring" safearray="yes" dir="return"> + <desc>Values of returned properties.</desc> + </param> + </method> + + <method name="setProperties"> + <desc> + Updates profile, changing/adding/removing properties. + + The names of the properties to set are passed in the @a names + array along with the new values for them in the @a values array. Both + arrays have the same number of elements with each element at the given + index in the first array corresponding to an element at the same index + in the second array. + + If there is at least one property name in @a names that is not valid, + the method will fail before changing the values of any other properties + from the @a names array. + + Using this method over <link to="#setProperty"/> is preferred if you + need to set several properties at once since it is more efficient. + + Setting the property value to @c null or an empty string is equivalent + to deleting the existing value. + </desc> + <param name="names" type="wstring" safearray="yes" dir="in"> + <desc>Names of properties.</desc> + </param> + <param name="values" type="wstring" safearray="yes" dir="in"> + <desc>Values of set properties.</desc> + </param> + </method> + + <method name="remove"> + <desc> + Deletes a profile. + </desc> + </method> + + <method name="createCloudClient"> + <desc> + Creates a cloud client for this cloud profile. + </desc> + <param name="cloudClient" type="ICloudClient" dir="return"> + <desc> + The cloud client object reference. + </desc> + </param> + </method> + + </interface> + + <!-- + // ICloudProvider + ////////////////////////////////////////////////////////////////////////// + --> + + <interface + name="ICloudProvider" extends="$unknown" + uuid="22363cfc-07da-41ec-ac4a-3dd99db35594" + wsmap="managed" + rest="managed" + reservedMethods="8" reservedAttributes="16" + > + + <attribute name="name" type="wstring" readonly="yes"> + <desc>Returns the long name of the provider. Includes vendor and precise + product name spelled out in the preferred way.</desc> + </attribute> + + <attribute name="shortName" type="wstring" readonly="yes"> + <desc>Returns the short name of the provider. Less than 8 ASCII chars, + using acronyms. No vendor name, but can contain a hint if it's a 3rd + party implementation for this cloud provider, to keep it unique.</desc> + </attribute> + + <attribute name="id" type="uuid" mod="string" readonly="yes"> + <desc>Returns the UUID of this cloud provider.</desc> + </attribute> + + <!-- if there are any generally useful, static pieces of information about + a particular cloud provider, please add them here. Maybe a description + of the functionality of the cloud provider implementation?--> + + <attribute name="profiles" type="ICloudProfile" safearray="yes" readonly="yes"> + <desc>Returns all profiles for this cloud provider.</desc> + </attribute> + + <attribute name="profileNames" type="wstring" safearray="yes" readonly="yes"> + <desc>Returns all profile names for this cloud provider.</desc> + </attribute> + + <attribute name="supportedPropertyNames" type="wstring" safearray="yes" readonly="yes"> + <desc> + Returns the supported property names. + </desc> + </attribute> + + <method name="getPropertyDescription" const="yes"> + <param name="name" type="wstring" dir="in"> + <desc>Property name.</desc> + </param> + <param name="description" type="wstring" dir="return"> + <desc>Property description.</desc> + </param> + </method> + + <method name="createProfile"> + <desc> + Creates a new profile. + </desc> + <param name="profileName" type="wstring" dir="in"> + <desc> + The profile name. Must not exist, otherwise an error is raised. + </desc> + </param> + <param name="names" type="wstring" safearray="yes" dir="in"> + <desc>Names of properties.</desc> + </param> + <param name="values" type="wstring" safearray="yes" dir="in"> + <desc>Values of set properties.</desc> + </param> + </method> + + <method name="importProfiles"> + <desc> + Import the profiles from the original source + </desc> + </method> + + <method name="restoreProfiles"> + <desc> + Restores the old local profiles if they exist + </desc> + </method> + + <method name="saveProfiles"> + <desc> + Saves the local profiles + </desc> + </method> + + <method name="getProfileByName"> + <param name="profileName" type="wstring" dir="in"/> + <param name="profile" type="ICloudProfile" dir="return"/> + </method> + + <method name="prepareUninstall" wrap-hint-server="passcaller"> + <desc> + The caller requests the cloud provider to cease operation. Should + return an error if this is currently not possible (due to ongoing + cloud activity, possibly by a different API client). However, this + must not wait for the completion for a larger amount of time (ideally + stays below a second of execution time). If this succeeds it should + leave the cloud provider in a state which does not allow starting new + operations. + </desc> + </method> + + </interface> + + <!-- + // ICloudProviderManager + ////////////////////////////////////////////////////////////////////////// + --> + <interface + name="ICloudProviderManager" extends="$unknown" + uuid="9128800f-762e-4120-871c-a2014234a607" + wsmap="managed" + rest="managed" + reservedMethods="4" reservedAttributes="8" + > + + <attribute name="providers" type="ICloudProvider" safearray="yes" readonly="yes"> + <desc>Returns all supported cloud providers.</desc> + </attribute> + + <method name="getProviderById"> + <param name="providerId" type="uuid" mod="string" dir="in"/> + <param name="provider" type="ICloudProvider" dir="return"/> + </method> + + <method name="getProviderByShortName"> + <param name="providerName" type="wstring" dir="in"/> + <param name="provider" type="ICloudProvider" dir="return"/> + </method> + + <method name="getProviderByName"> + <param name="providerName" type="wstring" dir="in"/> + <param name="provider" type="ICloudProvider" dir="return"/> + </method> + + </interface> + + <interface name="ICloudProviderListChangedEvent" extends="IEvent" + uuid="a54d9cca-f23f-11ea-9755-efd0f1f792d9" + wsmap="managed" autogen="VBoxEvent" + id="OnCloudProviderListChanged" + > + <desc> + Each individual provider that is installed or uninstalled is + reported as an <link to="ICloudProviderRegisteredEvent"/>. When + the batch is done this event is sent and listerns can get the + new list. + </desc> + <attribute name="registered" type="boolean" readonly="yes"/> + </interface> + + <interface name="ICloudProviderRegisteredEvent" extends="IEvent" + uuid="e28e227a-f231-11ea-9641-9b500c6d5365" + wsmap="managed" autogen="VBoxEvent" + id="OnCloudProviderRegistered" + > + <desc> + A cloud provider was installed or uninstalled. + See also <link to="ICloudProviderListChangedEvent"/>. + </desc> + <attribute name="id" type="uuid" mod="string" readonly="yes"/> + <attribute name="registered" type="boolean" readonly="yes"/> + </interface> + + <interface name="ICloudProviderUninstallEvent" extends="IEvent" + uuid="f01f1066-f231-11ea-8eee-33bb2afb0b6e" + wsmap="managed" autogen="VBoxEvent" + id="OnCloudProviderCanUninstall" waitable="yes" + > + <desc> + A cloud provider is about to be uninstalled. + Unlike <link to="ICloudProviderRegisteredEvent"/> this one is + waitable and is sent <i>before</i> an attempt is made to + uninstall a provider. Listerns should release references to the + provider and related objects if they have any, or the + uninstallation of the provider is going to fail because it's + still in use. + </desc> + <attribute name="id" type="uuid" mod="string" readonly="yes"/> + </interface> + + <!-- not autogenerated, @id is just for reference --> + <interface name="ICloudProfileRegisteredEvent" extends="IEvent" + uuid="6a5e65ba-eeb9-11ea-ae38-73242bc0f172" + wsmap="managed" + id="OnCloudProfileRegistered" + > + <attribute name="providerId" type="uuid" mod="string" readonly="yes"/> + <attribute name="name" type="wstring" readonly="yes"/> + <attribute name="registered" type="boolean" readonly="yes"/> + </interface> + + <!-- not autogenerated, @id is just for reference --> + <interface name="ICloudProfileChangedEvent" extends="IEvent" + uuid="83795a4c-fce1-11ea-8a17-636028ae0be2" + wsmap="managed" + id="OnCloudProfileChanged" + > + <attribute name="providerId" type="uuid" mod="string" readonly="yes"/> + <attribute name="name" type="wstring" readonly="yes"/> + </interface> + + <interface name="ILanguageChangedEvent" extends="IEvent" + uuid="28935887-782b-4c94-8410-ce557b9cfe44" + wsmap="managed" autogen="VBoxEvent" + id="OnLanguageChanged" + > + <attribute name="languageId" type="wstring" readonly="yes"/> + </interface> + + <module name="VBoxSVC" context="LocalServer"> + <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F" + namespace="virtualbox.org"> + <interface name="IVirtualBox" default="yes"/> + </class> + </module> + + <module name="VBoxC" context="InprocServer" threadingModel="Free"> + <class name="VirtualBoxClient" uuid="dd3fc71d-26c0-4fe1-bf6f-67f633265bba" + namespace="virtualbox.org"> + <interface name="IVirtualBoxClient" default="yes"/> + </class> + + <class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214" + namespace="virtualbox.org"> + <interface name="ISession" default="yes"/> + </class> + </module> + +</application> + +<if target="midl"> +<!-- Pay attention! Application uuid of this application is used in midl.xsl + So if you change it then change filter in "interface" and "class" template in midl.xsl too +--> +<application + name="VirtualBox System Service" + uuid="ec0e78e8-fa43-43e8-ac0a-02c784c4a4fa" + supportsErrorInfo="yes" +> + + <!-- + // IVBoxSVC + // Note! This actually extends IUnknown rather than IDispatch, notdual=yes + // sees to that. + ////////////////////////////////////////////////////////////////////////// + --> + <interface + name="IVBoxSVCRegistration" extends="$unknown" notdual="yes" + uuid="9e106366-4521-44cc-df95-186e4d057c83" + wsmap="suppress" internal="yes" + reservedMethods="0" reservedAttributes="0" + > + <desc> + Implemented by the VirtualBox class factory and registered with VBoxSDS + so it can retrieve IVirtualBox on behalf of other VBoxSVCs. + </desc> + + <method name="getVirtualBox" > + <desc> Gets an IUnknown interface to the VirtualBox object in the VBoxSVC process. </desc> + <param name="result" type="$unknown" dir="return" > + <desc> Where to return the IUnknown interface. </desc> + </param> + </method> + + </interface> + + <!-- + // IVirtualBoxSDS + // Note! This actually extends IUnknown rather than IDispatch, notdual=yes + // sees to that. + ////////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IVirtualBoxSDS" extends="$unknown" notdual="yes" + uuid="890ed3dc-cc19-43fa-8ebf-baecb6b9ec87" + wsmap="suppress" internal="yes" + reservedMethods="0" reservedAttributes="0" + > + <desc> + The IVirtualBoxSDS interface represents the system-wide directory service + helper. + + It exists only on Windows host, and its purpose is to work around design + flaws in Microsoft's (D)COM, in particular the local server instantiation + behavior. + </desc> + + <method name="registerVBoxSVC"> + <desc> + Registers a VBoxSVC instance with VBoxSDS. If the caller is not running + in a Windows 0 session, the method attempts to run VBoxSVC in that + session. + <result name="E_PENDING"> + The caller is not running in a Windows session 0 and no VBoxSVC + is registered. VBoxSVC registration begins in Windows session 0. + You should call this method again later. + </result> + </desc> + <param name="vboxSVC" type="IVBoxSVCRegistration" dir="in"> + <desc>Interface implemented by the VirtualBox class factory.</desc> + </param> + <param name="pid" type="long" dir="in"> + <desc>The process ID of the VBoxSVC instance.</desc> + </param> + <param name="existingVirtualBox" type="$unknown" dir="return"> + <desc>If there is already an VBoxSVC for this user, the an IUnknown + interface to its VirtualBox object is returned here, otherwise it + is set to NULL.</desc> + </param> + </method> + + <method name="deregisterVBoxSVC"> + <desc>Registers a VBoxSVC instance with the SDS.</desc> + <param name="vboxSVC" type="IVBoxSVCRegistration" dir="in"> + <desc>Same as specified during registration.</desc> + </param> + <param name="pid" type="long" dir="in"> + <desc>The process ID of the VBoxSVC instance (same as during registration).</desc> + </param> + </method> + + <method name="launchVMProcess"> + <desc> + Spawns a new process that will execute the virtual machine in the interactive + windows session of calling user. Any additional checks are performed by created + process itself + + If launching the VM succeeds, the new VM process will create its own session + and write-lock the machine for it, preventing conflicting changes from other + processes. If the machine is already locked (because it is already running or + because another session has a write lock), launching the VM process will therefore + fail. Reversely, future attempts to obtain a write lock will also fail while the + machine is running. + + Launching a VM process can take some time (a new VM is started in a new process, + for which memory and other resources need to be set up) but the method does + not wait for completion and just returns the PID of created process. + + <result name="E_INVALIDARG"> + Some of the parameters are invalid. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Launching process for machine failed. + </result> + </desc> + <param name="machine" type="wstring" dir="in"> + <desc> + The name or id of the machine the VM will start for. + </desc> + </param> + <param name="comment" type="wstring" dir="in"> + <desc> + The comment for VM. + </desc> + </param> + <param name="frontend" type="wstring" dir="in"> + <desc> + Front-end to use for the new VM process. The following are currently supported: + <ul> + <li><tt>"gui"</tt>: VirtualBox Qt GUI front-end</li> + <li><tt>"headless"</tt>: VBoxHeadless (VRDE Server) front-end</li> + <li><tt>"sdl"</tt>: VirtualBox SDL front-end</li> + <li><tt>""</tt>: use the per-VM default frontend if set, otherwise + the global default defined in the system properties. If neither + are set, the API will launch a <tt>"gui"</tt> session, which may + fail if there is no windowing environment available. See + <link to="IMachine::defaultFrontend"/> and + <link to="ISystemProperties::defaultFrontend"/>.</li> + </ul> + </desc> + </param> + <param name="environmentChanges" type="wstring" safearray="yes" dir="in"> + <desc> + The list of putenv-style changes to the VM process environment. + See <link to="IMachine::launchVMProcess" /> for details. + </desc> + </param> + <param name="cmdOptions" type="wstring" dir="in"> + <desc> + Additional command line options to pass to the VM process. + </desc> + </param> + <param name="sessionId" type="unsigned long" dir="in"> + <desc> + Windows session where the VM process should be launched. + </desc> + </param> + <param name="pid" type="unsigned long" dir="return"> + <desc>The PID of created process.</desc> + </param> + </method> + + </interface> + +<!-- Warning: the name of module should coincide with real windows service name. + VirtualBox_Typelib.xsl and VirtualBox_TypeLibWithInterfaces.xsl uses this name to make list of COM registration + actions in Wix. Installer will not able to register COM windows service properly if the name of module + differs from SCM windows service name. + The Name of windows service is referenced in different places. + Don't forget to change it in other places too If you change it here : + VBoxMergeApp.wxi (cp_VBoxSDS component), + VBoxSDS.cpp and VBoxProxyStub.cpp + --> + <module name="VBoxSDS" context="LocalService"> + <class name="VirtualBoxSDS" uuid="74ab5ffe-8726-4435-aa7e-876d705bcba5" + namespace="virtualbox.org"> + <interface name="IVirtualBoxSDS" default="yes"/> + </class> + </module> +</application> +</if> + +</library> + +</idl> + + +<!-- vim: set shiftwidth=2 tabstop=2 expandtab: --> |