VirtualBox.xidl revision 26ae7f0cac38c33d90eb69a15baef5fbdf7ca376
af062818b47340eef15700d2f0211576ba3506eevboxsync Copyright (C) 2006-2010 Oracle Corporation
af062818b47340eef15700d2f0211576ba3506eevboxsync This file is part of VirtualBox Open Source Edition (OSE), as
af062818b47340eef15700d2f0211576ba3506eevboxsync available from http://www.virtualbox.org. This file is free software;
af062818b47340eef15700d2f0211576ba3506eevboxsync you can redistribute it and/or modify it under the terms of the GNU
af062818b47340eef15700d2f0211576ba3506eevboxsync General Public License (GPL) as published by the Free Software
af062818b47340eef15700d2f0211576ba3506eevboxsync Foundation, in version 2 as it comes in the "COPYING" file of the
af062818b47340eef15700d2f0211576ba3506eevboxsync VirtualBox OSE distribution. VirtualBox OSE is distributed in the
af062818b47340eef15700d2f0211576ba3506eevboxsync hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
af062818b47340eef15700d2f0211576ba3506eevboxsync This is the master declaration for VirtualBox's Main API,
af062818b47340eef15700d2f0211576ba3506eevboxsync represented by COM/XPCOM and web service interfaces.
af062818b47340eef15700d2f0211576ba3506eevboxsync From this document, the build system generates several files
af062818b47340eef15700d2f0211576ba3506eevboxsync via XSLT that are then used during the build process.
af062818b47340eef15700d2f0211576ba3506eevboxsync Below is the list of XSL templates that operate on this file and
b955672b950093ff7416d1269dd4d3b69983bd8fvboxsync output files they generate. These XSL templates must be updated
4b9d6701570cb98fd36e209314239d104ec584d3vboxsync whenever the schema of this file changes:
b955672b950093ff7416d1269dd4d3b69983bd8fvboxsync out/<platform>/bin/sdk/idl/VirtualBox.idl
b955672b950093ff7416d1269dd4d3b69983bd8fvboxsync (MS COM interface definition file for Main API)
af062818b47340eef15700d2f0211576ba3506eevboxsync (XPCOM interface definition file for Main API)
af062818b47340eef15700d2f0211576ba3506eevboxsync out/<platform>/obj/src/VBox/Main/VirtualBox.idl
af062818b47340eef15700d2f0211576ba3506eevboxsync (pseudo-IDL for Doxygen to generate the official Main API
5112e32d7072e280613921c982a6672f2c859cf3vboxsync documentation)
af062818b47340eef15700d2f0211576ba3506eevboxsync a bunch of WSDL and C++ files
9ee431cac56f7b56e2197f78dae4d469b180be7avboxsync (VirtualBox web service sources and SOAP mappers;
af062818b47340eef15700d2f0211576ba3506eevboxsync see src/VBox/Main/webservice/Makefile.kmk for details)
af062818b47340eef15700d2f0211576ba3506eevboxsync 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
af062818b47340eef15700d2f0211576ba3506eevboxsync out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
af062818b47340eef15700d2f0211576ba3506eevboxsync (smart Qt-based C++ wrapper classes for COM interfaces
9ee431cac56f7b56e2197f78dae4d469b180be7avboxsync of the Main API)
9ee431cac56f7b56e2197f78dae4d469b180be7avboxsync 6. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
af062818b47340eef15700d2f0211576ba3506eevboxsync out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
af062818b47340eef15700d2f0211576ba3506eevboxsync (Main API TypeLib block for the WiX installer)
9ee431cac56f7b56e2197f78dae4d469b180be7avboxsync 7. src/VBox/Runtime/common/err/errmsgvboxcom.xsl =>
9ee431cac56f7b56e2197f78dae4d469b180be7avboxsync (<result> extraction for the %Rhrc format specifier)
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync describes the so-called <i>VirtualBox Main API</i> which comprises all public
e068057c82b010bc7cc663e8f57ac3ef1890a33cvboxsync COM interfaces and components provided by the VirtualBox server and by the
14e23ea879a4aad5f0beb4cadee81a25cefe6303vboxsync VirtualBox client library.
14e23ea879a4aad5f0beb4cadee81a25cefe6303vboxsync VirtualBox employs a client-server design, meaning that whenever any part of
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync interface or any virtual machine --, a dedicated server process named
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync VBoxSVC runs in the background. This allows multiple processes working with
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync VirtualBox to cooperate without conflicts. These processes communicate to each
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync other using inter-process communication facilities provided by the COM
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync implementation of the host computer.
040b4a09341f574825386333398110f4db3e1e51vboxsync On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
040b4a09341f574825386333398110f4db3e1e51vboxsync implementation. On all other platforms, Mozilla XPCOM, an open-source COM
040b4a09341f574825386333398110f4db3e1e51vboxsync implementation, is used.
040b4a09341f574825386333398110f4db3e1e51vboxsync All the parts that a typical VirtualBox user interacts with (the Qt GUI,
5112e32d7072e280613921c982a6672f2c859cf3vboxsync the VBoxManage command-line interface and the VBoxVRDP server) are technically
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync front-ends to the Main API and only use the interfaces that are documented
d7b582240fd84655df03ad70cf59ac764bf7cce7vboxsync in this Main API documentation. This ensures that, with any given release
d5a371915d691c36ee6fff283b6e9b79fc7b5db4vboxsync version of VirtualBox, all capabilities of the product that could be useful
af062818b47340eef15700d2f0211576ba3506eevboxsync to an external client program are always exposed by way of this API.
af062818b47340eef15700d2f0211576ba3506eevboxsync The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
af062818b47340eef15700d2f0211576ba3506eevboxsync contains two public component classes:
af062818b47340eef15700d2f0211576ba3506eevboxsync <tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
af062818b47340eef15700d2f0211576ba3506eevboxsync implement IVirtualBox and ISession interfaces respectively. These two classes
af062818b47340eef15700d2f0211576ba3506eevboxsync are of supreme importance and will be needed in order for any front-end
af062818b47340eef15700d2f0211576ba3506eevboxsync program to do anything useful. It is recommended to read the documentation of
af062818b47340eef15700d2f0211576ba3506eevboxsync the mentioned interfaces first.
af062818b47340eef15700d2f0211576ba3506eevboxsync The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync there can be only one object of this class on the local machine at any given
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync time. This object is a parent of many other objects in the VirtualBox COM
af062818b47340eef15700d2f0211576ba3506eevboxsync library and lives in the VBoxSVC process. In fact, when you create an instance
af062818b47340eef15700d2f0211576ba3506eevboxsync of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync process is already running, starts it if not, and returns you a reference to
af062818b47340eef15700d2f0211576ba3506eevboxsync the <tt>VirtualBox</tt> object created in this process. When the last reference
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync to this object is released, the VBoxSVC process ends (with a 5 second delay to
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync protect from too frequent restarts).
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync as many <tt>Session</tt> objects as you need but all of them will live in a
af062818b47340eef15700d2f0211576ba3506eevboxsync process which issues the object instantiation call. <tt>Session</tt> objects
af062818b47340eef15700d2f0211576ba3506eevboxsync represent virtual machine sessions which are used to configure virtual
af062818b47340eef15700d2f0211576ba3506eevboxsync machines and control their execution.
af062818b47340eef15700d2f0211576ba3506eevboxsync <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
af062818b47340eef15700d2f0211576ba3506eevboxsync/* currently, nsISupportsImpl.h lacks the below-like macros */
af062818b47340eef15700d2f0211576ba3506eevboxsync#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync#define NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI NS_IMPL_QUERY_INTERFACE4_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_ADDREF(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_RELEASE(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
af062818b47340eef15700d2f0211576ba3506eevboxsync#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync NS_IMPL_THREADSAFE_ADDREF(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_RELEASE(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_ADDREF(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_RELEASE(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
af062818b47340eef15700d2f0211576ba3506eevboxsync#ifndef NS_IMPL_THREADSAFE_ISUPPORTS4_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync# define NS_IMPL_THREADSAFE_ISUPPORTS4_CI(_class, _i1, _i2, _i3, _i4) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_ADDREF(_class) \
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync NS_IMPL_THREADSAFE_RELEASE(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI(_class, _i1, _i2, _i3, _i4) \
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync NS_IMPL_CI_INTERFACE_GETTER4(_class, _i1, _i2, _i3, _i4)
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync NS_INTERFACE_MAP_BEGIN(_class) \
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync NS_IMPL_QUERY_CLASSINFO(_class) \
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync NS_INTERFACE_MAP_END
af062818b47340eef15700d2f0211576ba3506eevboxsync#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync _i2, _ic2) \
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync NS_INTERFACE_MAP_BEGIN(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_QUERY_CLASSINFO(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_INTERFACE_MAP_END
af062818b47340eef15700d2f0211576ba3506eevboxsync#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
af062818b47340eef15700d2f0211576ba3506eevboxsync _i2, _ic2, _i3, _ic3) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_INTERFACE_MAP_BEGIN(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_QUERY_CLASSINFO(_class) \
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync NS_INTERFACE_MAP_END
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync NS_IMPL_THREADSAFE_ADDREF(_class) \
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync NS_IMPL_THREADSAFE_RELEASE(_class) \
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
af062818b47340eef15700d2f0211576ba3506eevboxsync _i2, _ic2) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_ADDREF(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_RELEASE(_class) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
af062818b47340eef15700d2f0211576ba3506eevboxsync _i2, _ic2) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
af062818b47340eef15700d2f0211576ba3506eevboxsync#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI
af062818b47340eef15700d2f0211576ba3506eevboxsync# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \
af062818b47340eef15700d2f0211576ba3506eevboxsync _i2, _ic2, _i3, _ic3) \
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync NS_IMPL_THREADSAFE_ADDREF(_class) \
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync NS_IMPL_THREADSAFE_RELEASE(_class) \
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync _i2, _ic2, _i3, _ic3) \
af062818b47340eef15700d2f0211576ba3506eevboxsync NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
040b4a09341f574825386333398110f4db3e1e51vboxsync name="VirtualBox"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
040b4a09341f574825386333398110f4db3e1e51vboxsync version="1.3"
af062818b47340eef15700d2f0211576ba3506eevboxsync desc="VirtualBox Type Library"
040b4a09341f574825386333398110f4db3e1e51vboxsync appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
040b4a09341f574825386333398110f4db3e1e51vboxsync supportsErrorInfo="yes"
040b4a09341f574825386333398110f4db3e1e51vboxsync // COM result codes for VirtualBox
040b4a09341f574825386333398110f4db3e1e51vboxsync /////////////////////////////////////////////////////////////////////////
040b4a09341f574825386333398110f4db3e1e51vboxsync <descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
040b4a09341f574825386333398110f4db3e1e51vboxsync This section describes all VirtualBox-specific COM result codes that may
040b4a09341f574825386333398110f4db3e1e51vboxsync be returned by methods of VirtualBox COM interfaces in addition to
040b4a09341f574825386333398110f4db3e1e51vboxsync standard COM result codes.
040b4a09341f574825386333398110f4db3e1e51vboxsync Note that along with the result code, every VirtualBox method returns
040b4a09341f574825386333398110f4db3e1e51vboxsync extended error information through the IVirtualBoxErrorInfo interface on
040b4a09341f574825386333398110f4db3e1e51vboxsync failure. This interface is a preferred way to present the error to the end
040b4a09341f574825386333398110f4db3e1e51vboxsync user because it contains a human readable description of the error. Raw
040b4a09341f574825386333398110f4db3e1e51vboxsync result codes, both standard and described in this section, are intended to
040b4a09341f574825386333398110f4db3e1e51vboxsync be used by programs to analyze the reason of a failure and select an
040b4a09341f574825386333398110f4db3e1e51vboxsync appropriate course of action without involving the end user (for example,
040b4a09341f574825386333398110f4db3e1e51vboxsync retry the operation later or make a different call).
040b4a09341f574825386333398110f4db3e1e51vboxsync The standard COM result codes that may originate from our methods include:
af062818b47340eef15700d2f0211576ba3506eevboxsync Returned when the value of the method's argument is not within the range
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync of valid values. This should not be confused with situations when the
af062818b47340eef15700d2f0211576ba3506eevboxsync value is within the range but simply doesn't suit the current object
af062818b47340eef15700d2f0211576ba3506eevboxsync state and there is a possibility that it will be accepted later (in such
af062818b47340eef15700d2f0211576ba3506eevboxsync cases VirtualBox-specific codes are returned, for example,
af062818b47340eef15700d2f0211576ba3506eevboxsync Returned if a memory pointer for the output argument is invalid (for
af062818b47340eef15700d2f0211576ba3506eevboxsync example, @c null). Note that when pointers representing input
af062818b47340eef15700d2f0211576ba3506eevboxsync arguments (such as strings) are invalid, E_INVALIDARG is returned.
af062818b47340eef15700d2f0211576ba3506eevboxsync Returned when the called object is not ready. Since the lifetime of a
af062818b47340eef15700d2f0211576ba3506eevboxsync public COM object cannot be fully controlled by the implementation,
af062818b47340eef15700d2f0211576ba3506eevboxsync VirtualBox maintains the readiness state for all objects it creates and
af062818b47340eef15700d2f0211576ba3506eevboxsync returns this code in response to any method call on the object that was
af062818b47340eef15700d2f0211576ba3506eevboxsync deactivated by VirtualBox and is not functioning any more.
af062818b47340eef15700d2f0211576ba3506eevboxsync Returned when a memory allocation operation fails.
af062818b47340eef15700d2f0211576ba3506eevboxsync </descGroup>
af062818b47340eef15700d2f0211576ba3506eevboxsync Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
af062818b47340eef15700d2f0211576ba3506eevboxsync everything in <result>/<desc> after (and including) the first dot, so express
af062818b47340eef15700d2f0211576ba3506eevboxsync the matter of the error code in the first sentence and keep it short.
af062818b47340eef15700d2f0211576ba3506eevboxsync <result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
af062818b47340eef15700d2f0211576ba3506eevboxsync Object corresponding to the supplied arguments does not exist.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
af062818b47340eef15700d2f0211576ba3506eevboxsync Current virtual machine state prevents the operation.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Virtual machine error occurred attempting the operation.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync File not accessible or erroneous file contents.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Runtime subsystem error.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Pluggable Device Manager error.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Current object state prohibits operation.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Host operating system related error.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Requested operation is not supported.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="VBOX_E_XML_ERROR" value="0x80BB000A">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Invalid XML found.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Current session state prohibits operation.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Object being in use prohibits operation.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync everything in <result>/<desc> after (and including) the first dot, so express
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync the matter of the error code in the first sentence and keep it short.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <descGroup/>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync // all common enums
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync /////////////////////////////////////////////////////////////////////////
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Settings version of VirtualBox settings files. This is written to
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync the "version" attribute of the root "VirtualBox" element in the settings
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync file XML and indicates which VirtualBox version wrote the file.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Null value, indicates invalid version.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Legacy settings version, not currently supported.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Legacy settings version, not currently supported.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Legacy settings version, not currently supported.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Legacy settings version, not currently supported.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Machine XML: Capitalization of Uart, Lpt elements and many attributes changed.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync (was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk)
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <!-- 2008-09-04: 2.0.0 released
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync 2008-11-20: settings version 1.5 introduced
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync 2008-12-17: 2.1.0 released
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Machine changes:
af062818b47340eef15700d2f0211576ba3506eevboxsync guest OS identifiers changed;
af062818b47340eef15700d2f0211576ba3506eevboxsync Machine/Hardware/Display/MonitorCount renamed to monitorCount;
040b4a09341f574825386333398110f4db3e1e51vboxsync Machine/Hardware/Display/Accelerate3D renamed to accelerate3D;
040b4a09341f574825386333398110f4db3e1e51vboxsync Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <!-- 2008-12-17: 2.1.0 released
040b4a09341f574825386333398110f4db3e1e51vboxsync 2008-12-19: settings version 1.6 introduced (is in 2.1 branch)
af062818b47340eef15700d2f0211576ba3506eevboxsync 2009-04-08: 2.2.0 released
af062818b47340eef15700d2f0211576ba3506eevboxsync Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done)
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <!-- 2008-12-17: 2.1.0 released
af062818b47340eef15700d2f0211576ba3506eevboxsync 2009-03-11: settings version 1.7 introduced (is in 2.2 branch)
af062818b47340eef15700d2f0211576ba3506eevboxsync 2009-04-08: 2.2.0 released
af062818b47340eef15700d2f0211576ba3506eevboxsync VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done)
af062818b47340eef15700d2f0211576ba3506eevboxsync Machine changes: HardDiskAttachments is now StorageControllers (done)
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <!-- Machine additions: Display/@accelerate2DVideo (done)
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <!-- The big storage controller / DVD / Floppy rework (done)
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <!-- Machine changes: RTC localOrUTC (done)
5112e32d7072e280613921c982a6672f2c859cf3vboxsync CPU hot-plug support
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Settings version "1.11", written by VirtualBox 3.3.x.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <!-- Machine changes: HD Audio controller, per-machine disk registries
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Settings version greater than "1.11", written by a future VirtualBox version.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync name="AccessMode"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
af062818b47340eef15700d2f0211576ba3506eevboxsync Access mode for opening files.
af062818b47340eef15700d2f0211576ba3506eevboxsync name="MachineState"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="e998d075-543a-41fc-8aa9-5ca3e92393fd"
af062818b47340eef15700d2f0211576ba3506eevboxsync Virtual machine execution state.
af062818b47340eef15700d2f0211576ba3506eevboxsync This enumeration represents possible values of the <link
af062818b47340eef15700d2f0211576ba3506eevboxsync to="IMachine::state"/> attribute.
af062818b47340eef15700d2f0211576ba3506eevboxsync Below is the basic virtual machine state diagram. It shows how the state
af062818b47340eef15700d2f0211576ba3506eevboxsync changes during virtual machine execution. The text in square braces shows
af062818b47340eef15700d2f0211576ba3506eevboxsync a method of the IConsole interface that performs the given state
af062818b47340eef15700d2f0211576ba3506eevboxsync transition.
af062818b47340eef15700d2f0211576ba3506eevboxsync +---------[powerDown()] <- Stuck <--[failure]-+
af062818b47340eef15700d2f0211576ba3506eevboxsync +-> PoweredOff --+-->[powerUp()]--> Starting --+ | +-----[resume()]-----+
af062818b47340eef15700d2f0211576ba3506eevboxsync | | | | V |
af062818b47340eef15700d2f0211576ba3506eevboxsync | Aborted -----+ +--> Running --[pause()]--> Paused
af062818b47340eef15700d2f0211576ba3506eevboxsync | | ^ | ^ |
af062818b47340eef15700d2f0211576ba3506eevboxsync | Saved -----------[powerUp()]--> Restoring -+ | | | |
af062818b47340eef15700d2f0211576ba3506eevboxsync | ^ | | | |
af062818b47340eef15700d2f0211576ba3506eevboxsync | | +-----------------------------------------+-|-------------------+ +
af062818b47340eef15700d2f0211576ba3506eevboxsync | | +-- Saving <--------[takeSnapshot()]<-------+---------------------+
af062818b47340eef15700d2f0211576ba3506eevboxsync | +-------- Saving <--------[saveState()]<----------+---------------------+
af062818b47340eef15700d2f0211576ba3506eevboxsync +-------------- Stopping -------[powerDown()]<----------+---------------------+
af062818b47340eef15700d2f0211576ba3506eevboxsync Note that states to the right from PoweredOff, Aborted and Saved in the
af062818b47340eef15700d2f0211576ba3506eevboxsync above diagram are called <i>online VM states</i>. These states
af062818b47340eef15700d2f0211576ba3506eevboxsync represent the virtual machine which is being executed in a dedicated
af062818b47340eef15700d2f0211576ba3506eevboxsync process (usually with a GUI window attached to it where you can see the
af062818b47340eef15700d2f0211576ba3506eevboxsync activity of the virtual machine and interact with it). There are two
af062818b47340eef15700d2f0211576ba3506eevboxsync special pseudo-states, FirstOnline and LastOnline, that can be used in
af062818b47340eef15700d2f0211576ba3506eevboxsync relational expressions to detect if the given machine state is online or
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync if (machine.GetState() >= MachineState_FirstOnline &&
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync ...the machine is being executed...
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync When the virtual machine is in one of the online VM states (that is, being
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync executed), only a few machine settings can be modified. Methods working
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync with such settings contain an explicit note about that. An attempt to
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync change any oter setting or perform a modifying operation during this time
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync All online states except Running, Paused and Stuck are transitional: they
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync represent temporary conditions of the virtual machine that will last as
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync long as the operation that initiated such a condition.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync The Stuck state is a special case. It means that execution of the machine
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync has reached the "Guru Meditation" condition. This condition indicates an
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync internal VMM (virtual machine manager) failure which may happen as a
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync result of either an unhandled low-level virtual hardware exception or one
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync of the recompiler exceptions (such as the <i>too-many-traps</i>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync condition).
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Note also that any online VM state may transit to the Aborted state. This
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync happens if the process that is executing the virtual machine terminates
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync unexpectedly (for example, crashes). Other than that, the Aborted state is
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync equivalent to PoweredOff.
040b4a09341f574825386333398110f4db3e1e51vboxsync There are also a few additional state diagrams that do not deal with
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync virtual machine execution and therefore are shown separately. The states
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync shown on these diagrams are called <i>offline VM states</i> (this includes
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync PoweredOff, Aborted and Saved too).
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync The first diagram shows what happens when a lengthy setup operation is
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync being executed (such as <link to="IMachine::attachDevice"/>).
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync +----------------------------------(same state as before the call)------+
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync +-> PoweredOff --+ |
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync |-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync +-> Saved -------+
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync The next two diagrams demonstrate the process of taking a snapshot of a
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync powered off virtual machine, restoring the state to that as of a snapshot
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync or deleting a snapshot, respectively.
040b4a09341f574825386333398110f4db3e1e51vboxsync +----------------------------------(same state as before the call)------+
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync +-> PoweredOff --+ |
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync | +-->[takeSnapshot()] -------------------> Saving ------+
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync +-> Aborted -----+
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync +-> PoweredOff --+
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync | Aborted -----+-->[restoreSnapshot() ]-------> RestoringSnapshot -+
040b4a09341f574825386333398110f4db3e1e51vboxsync | | [deleteSnapshot() ]-------> DeletingSnapshot --+
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync +-> Saved -------+ |
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Note that the Saving state is present in both the offline state group and
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync online state group. Currently, the only way to determine what group is
040b4a09341f574825386333398110f4db3e1e51vboxsync assumed in a particular case is to remember the previous machine state: if
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync it was Running or Paused, then Saving is an online state, otherwise it is
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync an offline state. This inconsistency may be removed in one of the future
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync versions of VirtualBox by adding a new state.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync For whoever decides to touch this enum: In order to keep the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync comparisons involving FirstOnline and LastOnline pseudo-states valid,
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync the numeric values of these states must be correspondingly updated if
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync needed: for any online VM state, the condition
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <tt>FirstOnline <= state <= LastOnline</tt> must be
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync @c true. The same relates to transient states for which
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync the condition <tt>FirstOnline <= state <= LastOnline</tt> must be
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync The machine is not running and has no saved execution state; it has
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync either never been started or been shut down successfully.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync The machine is not currently running, but the execution state of the machine
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync has been saved to an external file when it was running, from where
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync it can be resumed.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync The machine was teleported to a different host (or process) and then
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync powered off. Take care when powering it on again may corrupt resources
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync it shares with the teleportation target (e.g. disk and network).
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync The process running the machine has terminated abnormally. This may
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync indicate a crash of the VM process in host execution context, or
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync the VM process has been terminated externally.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync The machine is currently being executed.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync For whoever decides to touch this enum: In order to keep the
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync comparisons in the old source code valid, this state must immediately
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync precede the Paused state.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync TODO: Lift this spectacularly wonderful restriction.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Execution of the machine has been paused.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync For whoever decides to touch this enum: In order to keep the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync comparisons in the old source code valid, this state must immediately
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync follow the Running state.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync TODO: Lift this spectacularly wonderful restriction.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Execution of the machine has reached the "Guru Meditation"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync condition. This indicates a severe error in the hypervisor itself.
af062818b47340eef15700d2f0211576ba3506eevboxsync bird: Why this uncool name? Could we rename it to "GuruMeditation" or
af062818b47340eef15700d2f0211576ba3506eevboxsync "Guru", perhaps? Or are there some other VMM states that are
af062818b47340eef15700d2f0211576ba3506eevboxsync intended to be lumped in here as well?
af062818b47340eef15700d2f0211576ba3506eevboxsync The machine is about to be teleported to a different host or process.
af062818b47340eef15700d2f0211576ba3506eevboxsync It is possible to pause a machine in this state, but it will go to the
af062818b47340eef15700d2f0211576ba3506eevboxsync @c TeleportingPausedVM state and it will not be
af062818b47340eef15700d2f0211576ba3506eevboxsync possible to resume it again unless the teleportation fails.
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync A live snapshot is being taken. The machine is running normally, but
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync some of the runtime configuration options are inaccessible. Also, if
af062818b47340eef15700d2f0211576ba3506eevboxsync paused while in this state it will transition to
af062818b47340eef15700d2f0211576ba3506eevboxsync @c Saving and it will not be resume the
af062818b47340eef15700d2f0211576ba3506eevboxsync execution until the snapshot operation has completed.
af062818b47340eef15700d2f0211576ba3506eevboxsync Machine is being started after powering it on from a
af062818b47340eef15700d2f0211576ba3506eevboxsync zero execution state.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Machine is being normally stopped powering it off, or after the guest OS
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync has initiated a shutdown sequence.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Machine is saving its execution state to a file, or an online
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync snapshot of the machine is being taken.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Execution state of the machine is being restored from a file
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync after powering it on from the saved execution state.
5941b2269255a4db8c3d1258dbf57ef453bee303vboxsync The machine is being teleported to another host or process, but it is
5941b2269255a4db8c3d1258dbf57ef453bee303vboxsync not running. This is the paused variant of the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Teleporting the machine state in from another host or process.
5941b2269255a4db8c3d1258dbf57ef453bee303vboxsync Like @c DeletingSnapshot, but the merging of media is ongoing in
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync the background while the machine is running.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Like @c DeletingSnapshotOnline, but the machine was paused when the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync merging of differencing media was started.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync A machine snapshot is being restored; this typically does not take long.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync A machine snapshot is being deleted; this can take a long time since this
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync may require merging differencing media. This value indicates that the
af062818b47340eef15700d2f0211576ba3506eevboxsync machine is not running while the snapshot is being deleted.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Lengthy setup operation is in progress.
af062818b47340eef15700d2f0211576ba3506eevboxsync <const name="FirstOnline" value="5" wsmap="suppress"> <!-- Running -->
af062818b47340eef15700d2f0211576ba3506eevboxsync Pseudo-state: first online state (for use in relational expressions).
af062818b47340eef15700d2f0211576ba3506eevboxsync <const name="LastOnline" value="17" wsmap="suppress"> <!-- DeletingSnapshotPaused -->
af062818b47340eef15700d2f0211576ba3506eevboxsync Pseudo-state: last online state (for use in relational expressions).
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <const name="FirstTransient" value="8" wsmap="suppress"> <!-- Teleporting -->
af062818b47340eef15700d2f0211576ba3506eevboxsync Pseudo-state: first transient state (for use in relational expressions).
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <const name="LastTransient" value="20" wsmap="suppress"> <!-- SettingUp -->
af062818b47340eef15700d2f0211576ba3506eevboxsync Pseudo-state: last transient state (for use in relational expressions).
af062818b47340eef15700d2f0211576ba3506eevboxsync name="SessionState"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8"
af062818b47340eef15700d2f0211576ba3506eevboxsync Session state. This enumeration represents possible values of
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
af062818b47340eef15700d2f0211576ba3506eevboxsync attributes.
af062818b47340eef15700d2f0211576ba3506eevboxsync In <link to="IMachine::sessionState"/>, this means that the machine
af062818b47340eef15700d2f0211576ba3506eevboxsync is not locked for any sessions.
af062818b47340eef15700d2f0211576ba3506eevboxsync In <link to="ISession::state"/>, this means that no machine is
af062818b47340eef15700d2f0211576ba3506eevboxsync currently locked for this session.
af062818b47340eef15700d2f0211576ba3506eevboxsync In <link to="IMachine::sessionState"/>, this means that the machine
af062818b47340eef15700d2f0211576ba3506eevboxsync is currently locked for a session, whose process identifier can
af062818b47340eef15700d2f0211576ba3506eevboxsync then be found in the <link to="IMachine::sessionPid" /> attribute.
af062818b47340eef15700d2f0211576ba3506eevboxsync In <link to="ISession::state"/>, this means that a machine is
af062818b47340eef15700d2f0211576ba3506eevboxsync currently locked for this session, and the mutable machine object
af062818b47340eef15700d2f0211576ba3506eevboxsync can be found in the <link to="ISession::machine"/> attribute
af062818b47340eef15700d2f0211576ba3506eevboxsync (see <link to="IMachine::lockMachine" /> for details).
af062818b47340eef15700d2f0211576ba3506eevboxsync A new process is being spawned for the machine as a result of
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="IMachine::launchVMProcess"/> call. This state also occurs
040b4a09341f574825386333398110f4db3e1e51vboxsync as a short transient state during an <link to="IMachine::lockMachine"/>
12ba2b5cbd2137f984723ceb240d4210c7b79ff5vboxsync The session is being unlocked.
040b4a09341f574825386333398110f4db3e1e51vboxsync name="CPUPropertyType"
040b4a09341f574825386333398110f4db3e1e51vboxsync uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5"
040b4a09341f574825386333398110f4db3e1e51vboxsync Virtual CPU property type. This enumeration represents possible values of the
040b4a09341f574825386333398110f4db3e1e51vboxsync IMachine get- and setCPUProperty methods.
af062818b47340eef15700d2f0211576ba3506eevboxsync This setting determines whether VirtualBox will expose the Physical Address
af062818b47340eef15700d2f0211576ba3506eevboxsync Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
af062818b47340eef15700d2f0211576ba3506eevboxsync is not available, it will not be reported.
af062818b47340eef15700d2f0211576ba3506eevboxsync This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow
af062818b47340eef15700d2f0211576ba3506eevboxsync teleporting between host systems that differ significantly.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync name="HWVirtExPropertyType"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync uuid="ce81dfdd-d2b8-4a90-bbea-40ee8b7ffcee"
af062818b47340eef15700d2f0211576ba3506eevboxsync Hardware virtualization property type. This enumeration represents possible values
af062818b47340eef15700d2f0211576ba3506eevboxsync for the <link to="IMachine::getHWVirtExProperty"/> and
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="IMachine::setHWVirtExProperty"/> methods.
af062818b47340eef15700d2f0211576ba3506eevboxsync Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If
af062818b47340eef15700d2f0211576ba3506eevboxsync such extensions are not available, they will not be used.
af062818b47340eef15700d2f0211576ba3506eevboxsync Whether hardware virtualization is used exclusively by VirtualBox. When enabled,
af062818b47340eef15700d2f0211576ba3506eevboxsync VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V
af062818b47340eef15700d2f0211576ba3506eevboxsync feature of the host. To share these with other hypervisors, you must disable this property.
af062818b47340eef15700d2f0211576ba3506eevboxsync Whether VT-x VPID is enabled. If this extension is not available, it will not be used.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Whether Nested Paging is enabled. If this extension is not available, it will not be used.
af062818b47340eef15700d2f0211576ba3506eevboxsync Whether large page allocation is enabled; requires nested paging and a 64 bits host.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync name="FaultToleranceState"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="05f65593-743e-4862-8700-57bf6cc48f3f"
af062818b47340eef15700d2f0211576ba3506eevboxsync Used with <link to="IMachine::faultToleranceState" />.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync name="LockType"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync uuid="138b53f8-db4b-47c5-b32b-4ef52f769413"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Request only a shared read lock for remote-controlling the machine.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync name="SessionType"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Session type. This enumeration represents possible values of the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Session has acquired an exclusive write lock on a machine
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Session has launched a VM process using
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Session has obtained a link to another session using
af062818b47340eef15700d2f0211576ba3506eevboxsync name="DeviceType"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Device type.
af062818b47340eef15700d2f0211576ba3506eevboxsync Null value, may also mean "no device" (not allowed for
af062818b47340eef15700d2f0211576ba3506eevboxsync name="DeviceActivity"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
af062818b47340eef15700d2f0211576ba3506eevboxsync Device activity for <link to="IConsole::getDeviceActivity"/>.
af062818b47340eef15700d2f0211576ba3506eevboxsync name="ClipboardMode"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="33364716-4008-4701-8f14-be0fa3d62950"
af062818b47340eef15700d2f0211576ba3506eevboxsync Host-Guest clipboard interchange mode.
af062818b47340eef15700d2f0211576ba3506eevboxsync name="Scope"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
af062818b47340eef15700d2f0211576ba3506eevboxsync Scope of the operation.
af062818b47340eef15700d2f0211576ba3506eevboxsync A generic enumeration used in various methods to define the action or
af062818b47340eef15700d2f0211576ba3506eevboxsync argument scope.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync name="BIOSBootMenuMode"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync BIOS boot menu mode.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync name="ProcessorFeature"
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync CPU features.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync name="FirmwareType"
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync uuid="b903f264-c230-483e-ac74-2b37ce60d371"
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Firmware type.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <desc>EFI Firmware, bitness detetced basing on OS type.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync name="PointingHidType"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="0d3c17a2-821a-4b2e-ae41-890c6c60aa97"
e068057c82b010bc7cc663e8f57ac3ef1890a33cvboxsync Type of pointing device used in a virtual machine.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Using of such device can have negative performance implications. </desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync name="KeyboardHidType"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync uuid="5a5b0996-3a3e-44bb-9019-56979812cbcc"
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync Type of keyboard device used in a virtual machine.
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.
af062818b47340eef15700d2f0211576ba3506eevboxsync Using of such device can have negative performance implications. </desc>
3b5b00fc19a7b52f11075648a1b93d477137f4d3vboxsync // IVirtualBoxErrorInfo
af062818b47340eef15700d2f0211576ba3506eevboxsync /////////////////////////////////////////////////////////////////////////
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync uuid="e053d3c0-f493-491b-a735-3a9f0b1feed4"
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync supportsErrorInfo="no"
6decafdf89f825b3af922ab6fa02345e08e5be7bvboxsync wsmap="managed"
af062818b47340eef15700d2f0211576ba3506eevboxsync The IVirtualBoxErrorInfo interface represents extended error information.
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync Extended error information can be set by VirtualBox components after
af062818b47340eef15700d2f0211576ba3506eevboxsync unsuccessful or partially successful method invocation. This information
5112e32d7072e280613921c982a6672f2c859cf3vboxsync can be retrieved by the calling party as an IVirtualBoxErrorInfo object
af062818b47340eef15700d2f0211576ba3506eevboxsync and then shown to the client in addition to the plain 32-bit result code.
af062818b47340eef15700d2f0211576ba3506eevboxsync In MS COM, this interface extends the IErrorInfo interface,
040b4a09341f574825386333398110f4db3e1e51vboxsync in XPCOM, it extends the nsIException interface. In both cases,
040b4a09341f574825386333398110f4db3e1e51vboxsync it provides a set of common attributes to retrieve error
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync information.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync Sometimes invocation of some component's method may involve methods of
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync other components that may also fail (independently of this method's
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync failure), or a series of non-fatal errors may precede a fatal error that
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync causes method failure. In cases like that, it may be desirable to preserve
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync information about all errors happened during method invocation and deliver
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync it to the caller. The <link to="#next"/> attribute is intended
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync specifically for this purpose and allows to represent a chain of errors
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync through a single IVirtualBoxErrorInfo object set after method invocation.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync Note that errors are stored to a chain in the reverse order, i.e. the
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync initial error object you query right after method invocation is the last
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync error set by the callee, the object it points to in the @a next attribute
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync is the previous error and so on, up to the first error (which is the last
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync in the chain).
af062818b47340eef15700d2f0211576ba3506eevboxsync <attribute name="resultCode" type="long" readonly="yes">
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync Result code of the error.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync Usually, it will be the same as the result code returned
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync by the method that provided this error information, but not
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync always. For example, on Win32, CoCreateInstance() will most
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync likely return E_NOINTERFACE upon unsuccessful component
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync instantiation attempt, but not the value the component factory
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync returned. Value is typed 'long', not 'result',
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync to make interface usable from scripting languages.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync In MS COM, there is no equivalent.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync In XPCOM, it is the same as nsIException::result.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync </attribute>
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync <attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync UUID of the interface that defined the error.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync In MS COM, it is the same as IErrorInfo::GetGUID, except for the
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync In XPCOM, there is no equivalent.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync </attribute>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <attribute name="component" type="wstring" readonly="yes">
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync Name of the component that generated the error.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync In MS COM, it is the same as IErrorInfo::GetSource.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync In XPCOM, there is no equivalent.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync </attribute>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <attribute name="text" type="wstring" readonly="yes">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Text description of the error.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync In MS COM, it is the same as IErrorInfo::GetDescription.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync In XPCOM, it is the same as nsIException::message.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync </attribute>
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Next error object if there is any, or @c null otherwise.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync In MS COM, there is no equivalent.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync In XPCOM, it is the same as nsIException::inner.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync </attribute>
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync </interface>
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync // IVirtualBox
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync /////////////////////////////////////////////////////////////////////////
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync wsmap="managed"
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync The IDHCPServer interface represents the vbox dhcp server configuration.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync To enumerate all the dhcp servers on the host, use the
af062818b47340eef15700d2f0211576ba3506eevboxsync specifies if the dhcp server is enabled
af062818b47340eef15700d2f0211576ba3506eevboxsync </attribute>
af062818b47340eef15700d2f0211576ba3506eevboxsync <attribute name="IPAddress" type="wstring" readonly="yes">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync specifies server IP
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync </attribute>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <attribute name="networkMask" type="wstring" readonly="yes">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync specifies server network mask
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync </attribute>
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync <attribute name="networkName" type="wstring" readonly="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync specifies internal network name the server is used for
d10b60270f0c0eeb87f45002a010cff8ba2126b1vboxsync </attribute>
d10b60270f0c0eeb87f45002a010cff8ba2126b1vboxsync <attribute name="lowerIP" type="wstring" readonly="yes">
6b9422045350f9373da5033a86972ce1131dd356vboxsync specifies from IP adrres in server address range
6ce53b61ec00c84abbe9936d7a179c687db124e6vboxsync </attribute>
601ad8faca2e55f8871903c44b6b62e922c3928evboxsync <attribute name="upperIP" type="wstring" readonly="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync specifies to IP adrres in server address range
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync </attribute>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync configures the server
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync invalid configuration supplied
af062818b47340eef15700d2f0211576ba3506eevboxsync server IP address
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync server network mask
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="FromIPAddress" type="wstring" dir="in">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync server From IP address for address range
af062818b47340eef15700d2f0211576ba3506eevboxsync server To IP address for address range
af062818b47340eef15700d2f0211576ba3506eevboxsync Starts DHCP server process.
af062818b47340eef15700d2f0211576ba3506eevboxsync Failed to start the process.
af062818b47340eef15700d2f0211576ba3506eevboxsync Name of internal network DHCP server should attach to.
af062818b47340eef15700d2f0211576ba3506eevboxsync Name of internal network trunk.
af062818b47340eef15700d2f0211576ba3506eevboxsync Type of internal network trunk.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Stops DHCP server process.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Failed to stop the process.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </interface>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync uuid="ec6cc7e7-06a2-4c5d-8993-1e3619c53817"
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync wsmap="managed"
5112e32d7072e280613921c982a6672f2c859cf3vboxsync The IVirtualBox interface represents the main interface exposed by the
5112e32d7072e280613921c982a6672f2c859cf3vboxsync product that provides virtual machine management.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync An instance of IVirtualBox is required for the product to do anything
5112e32d7072e280613921c982a6672f2c859cf3vboxsync useful. Even though the interface does not expose this, internally,
5112e32d7072e280613921c982a6672f2c859cf3vboxsync IVirtualBox is implemented as a singleton and actually lives in the
5112e32d7072e280613921c982a6672f2c859cf3vboxsync process of the VirtualBox server (VBoxSVC.exe). This makes sure that
5112e32d7072e280613921c982a6672f2c859cf3vboxsync IVirtualBox can track the state of all virtual machines on a particular
5112e32d7072e280613921c982a6672f2c859cf3vboxsync host, regardless of which frontend started them.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync To enumerate all the virtual machines on the host, use the
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <attribute name="version" type="wstring" readonly="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync A string representing the version number of the product. The
5112e32d7072e280613921c982a6672f2c859cf3vboxsync format is 3 integer numbers divided by dots (e.g. 1.0.1). The
5112e32d7072e280613921c982a6672f2c859cf3vboxsync last number represents the build number and will frequently change.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </attribute>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <attribute name="revision" type="unsigned long" readonly="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync The internal build revision number of the product.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </attribute>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <attribute name="packageType" type="wstring" readonly="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync A string representing the package type of this product. The
5112e32d7072e280613921c982a6672f2c859cf3vboxsync format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
5112e32d7072e280613921c982a6672f2c859cf3vboxsync SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
5112e32d7072e280613921c982a6672f2c859cf3vboxsync is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </attribute>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <attribute name="homeFolder" type="wstring" readonly="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync Full path to the directory where the global settings file,
5112e32d7072e280613921c982a6672f2c859cf3vboxsync In this version of VirtualBox, the value of this property is
5112e32d7072e280613921c982a6672f2c859cf3vboxsync always <tt><user_dir>/.VirtualBox</tt> (where
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <tt><user_dir></tt> is the path to the user directory,
5112e32d7072e280613921c982a6672f2c859cf3vboxsync as determined by the host OS), and cannot be changed.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync This path is also used as the base to resolve relative paths in
5112e32d7072e280613921c982a6672f2c859cf3vboxsync places where relative paths are allowed (unless otherwise
5112e32d7072e280613921c982a6672f2c859cf3vboxsync expressly indicated).
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </attribute>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <attribute name="settingsFilePath" type="wstring" readonly="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync Full name of the global settings file.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync The value of this property corresponds to the value of
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </attribute>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <attribute name="host" type="IHost" readonly="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </attribute>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </attribute>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync Array of machine objects registered within this VirtualBox instance.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </attribute>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync Array of medium objects known to this VirtualBox installation.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync This array contains only base media. All differencing
5112e32d7072e280613921c982a6672f2c859cf3vboxsync media of the given base medium can be enumerated using
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync </attribute>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Array of CD/DVD image objects currently in use by this VirtualBox instance.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync </attribute>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Array of floppy image objects currently in use by this VirtualBox instance.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync </attribute>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Collection of global shared folders. Global shared folders are
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync available to all virtual machines.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync New shared folders are added to the collection using
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <link to="#createSharedFolder"/>. Existing shared folders can be
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync In the current version of the product, global shared folders are not
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync implemented and therefore this collection is always empty.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync </attribute>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Associated performance collector object.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync </attribute>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync dhcp server settings.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync </attribute>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <attribute name="eventSource" type="IEventSource" readonly="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Event source for VirtualBox events.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync </attribute>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Creates a new virtual machine.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync The new machine is created unregistered, with the initial configuration
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync set according to the specified guest OS type. A typical sequence of
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync actions to create a new virtual machine is as follows:
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Call this method to have a new machine created. The returned machine
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync object will be "mutable" allowing to change any machine property.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Configure the machine using the appropriate attributes and methods.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Call <link to="IMachine::saveSettings" /> to write the settings
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync to the machine's XML settings file. The configuration of the newly
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync created machine will not be saved to disk until this method is
5112e32d7072e280613921c982a6672f2c859cf3vboxsync Call <link to="#registerMachine" /> to add the machine to the list
5112e32d7072e280613921c982a6672f2c859cf3vboxsync of machines known to VirtualBox.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync You should specify valid name for the newly created machine when calling
5112e32d7072e280613921c982a6672f2c859cf3vboxsync this method. See the <link to="IMachine::name"/> attribute description
5112e32d7072e280613921c982a6672f2c859cf3vboxsync for more details about the machine name.
af062818b47340eef15700d2f0211576ba3506eevboxsync The specified guest OS type identifier must match an ID of one of known
5112e32d7072e280613921c982a6672f2c859cf3vboxsync guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
af062818b47340eef15700d2f0211576ba3506eevboxsync Every machine has a <i>settings file</i> that is used to store
af062818b47340eef15700d2f0211576ba3506eevboxsync the machine configuration. This file is stored in a directory called the
040b4a09341f574825386333398110f4db3e1e51vboxsync <i>machine settings subfolder</i>. Both the settings subfolder and file
5112e32d7072e280613921c982a6672f2c859cf3vboxsync will have a name that corresponds to the name of the virtual machine.
af062818b47340eef15700d2f0211576ba3506eevboxsync You can specify where to create the machine setting subfolder using the
af062818b47340eef15700d2f0211576ba3506eevboxsync @a baseFolder argument. The base folder can be absolute (full path) or
af062818b47340eef15700d2f0211576ba3506eevboxsync relative to the <link to="IVirtualBox::homeFolder">VirtualBox home
af062818b47340eef15700d2f0211576ba3506eevboxsync directory</link>.
af062818b47340eef15700d2f0211576ba3506eevboxsync If @a baseFolder is a @c null or empty string (which is recommended), the
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="ISystemProperties::defaultMachineFolder">default machine
91563ca66c54f5974bd78d4a8e51e1a690c03e0fvboxsync settings folder</link> will be used as a base folder for the created
5112e32d7072e280613921c982a6672f2c859cf3vboxsync machine. Otherwise the given base folder will be used. In either case,
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync the full path to the resulting settings file has the following
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <base_folder>/<machine_name>/<machine_name>.xml
5112e32d7072e280613921c982a6672f2c859cf3vboxsync Note that if the resulting settings file already exists, this method
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Optionally, you may specify an UUID of to assign to the created machine.
91563ca66c54f5974bd78d4a8e51e1a690c03e0fvboxsync However, this is not recommended and you should normally pass an empty
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync (@c null) UUID to this method so that a new UUID will be automatically
af062818b47340eef15700d2f0211576ba3506eevboxsync generated for every created machine. You can use UUID
af062818b47340eef15700d2f0211576ba3506eevboxsync 00000000-0000-0000-0000-000000000000 as @c null value.
af062818b47340eef15700d2f0211576ba3506eevboxsync There is no way to change the name of the settings file or
af062818b47340eef15700d2f0211576ba3506eevboxsync subfolder of the created machine directly.
af062818b47340eef15700d2f0211576ba3506eevboxsync @a osTypeId is invalid.
af062818b47340eef15700d2f0211576ba3506eevboxsync Resulting settings file name is invalid or the settings file already
af062818b47340eef15700d2f0211576ba3506eevboxsync exists or could not be created due to an I/O error.
af062818b47340eef15700d2f0211576ba3506eevboxsync @a name is empty or @c null.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="id" type="uuid" mod="string" dir="in">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Create the VM even if there are conflicting files.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="machine" type="IMachine" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync Opens a virtual machine from the existing settings file.
af062818b47340eef15700d2f0211576ba3506eevboxsync The opened machine remains unregistered until you call
af062818b47340eef15700d2f0211576ba3506eevboxsync The specified settings file name can be absolute
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync (full path) or relative to the <link to="IVirtualBox::homeFolder">
af062818b47340eef15700d2f0211576ba3506eevboxsync VirtualBox home directory</link>. This file must exist
af062818b47340eef15700d2f0211576ba3506eevboxsync and must be a valid machine settings file whose contents
af062818b47340eef15700d2f0211576ba3506eevboxsync will be used to construct the machine object.
af062818b47340eef15700d2f0211576ba3506eevboxsync Settings file name invalid, not found or sharing violation.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="settingsFile" type="wstring" dir="in">
040b4a09341f574825386333398110f4db3e1e51vboxsync Name of the machine settings file.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="machine" type="IMachine" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="IMachine::settingsModified"/> will return
af062818b47340eef15700d2f0211576ba3506eevboxsync @c false for the created machine, until any of machine settings
af062818b47340eef15700d2f0211576ba3506eevboxsync are changed.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Registers the machine previously created using
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="#openMachine"/> within this VirtualBox installation. After
af062818b47340eef15700d2f0211576ba3506eevboxsync successful method invocation, the
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="IMachineRegisteredEvent"/> event is fired.
af062818b47340eef15700d2f0211576ba3506eevboxsync This method implicitly calls <link to="IMachine::saveSettings"/>
af062818b47340eef15700d2f0211576ba3506eevboxsync to save all current machine settings before registering it.
af062818b47340eef15700d2f0211576ba3506eevboxsync No matching virtual machine found.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Virtual machine was not created within this VirtualBox instance.
3a974120cf0d8d23b2531cd62fe04532e6ac205evboxsync Attempts to find a virtual machine given its UUID.
af062818b47340eef15700d2f0211576ba3506eevboxsync To look up a machine by name, use <link to="IVirtualBox::findMachine" />
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Could not find registered machine matching @a id.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="id" type="uuid" mod="string" dir="in"/>
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync <param name="machine" type="IMachine" dir="return"/>
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Attempts to find a virtual machine given its name.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Could not find registered machine matching @a name.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync <param name="machine" type="IMachine" dir="return"/>
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Creates a new appliance object, which represents an appliance in the Open Virtual Machine
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync <param name="appliance" type="IAppliance" dir="return">
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Creates a new base medium object that will use the given storage
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync format and location for medium data.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Note that the actual storage unit is not created by this method. In
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync order to do it, and before you are able to attach the created medium
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync to virtual machines, you must call one of the following methods to
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync allocate a format-specific storage unit at the specified location:
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Some medium attributes, such as <link to="IMedium::id"/>, may
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync remain uninitialized until the medium storage unit is successfully
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync created by one of the above methods.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync After the storage unit is successfully created, it will be
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync accessible through the <link to="#findMedium"/> method and can
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync The list of all storage formats supported by this VirtualBox
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync installation can be obtained using
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync <link to="ISystemProperties::mediumFormats"/>. If the @a format
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync attribute is empty or @c null then the default storage format
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync be used for creating a storage unit of the medium.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Note that the format of the location string is storage format specific.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync <link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync @a format identifier is invalid. See
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync @a location is a not valid file name (for file-based formats only).
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Identifier of the storage format to use for the new medium.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Location of the storage unit for the new medium.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Opens a medium from an existing storage location.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Once a medium has been opened, it can be passed to other VirtualBox
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync methods, in particular to <link to="IMachine::attachDevice" />.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Depending on the given device type, the file at the storage location
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync must be in one of the media formats understood by VirtualBox:
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync <li>With a "HardDisk" device type, the file must be a hard disk image
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync in one of the formats supported by VirtualBox (see
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync After this method succeeds, if the medium is a base medium, it
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync will be added to the <link to="#hardDisks"/> array attribute. </li>
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync <li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync After this method succeeds, the medium will be added to the
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync <li>With a "Floppy" device type, the file must be an RAW floppy image.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync After this method succeeds, the medium will be added to the
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync After having been opened, the medium can be found by the <link to="#findMedium"/>
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync method and can be attached to virtual machines. See <link to="IMedium" /> for more details.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync The UUID of the newly opened medium will either be retrieved from the
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync storage location, if the format supports it (e.g. for hard disk images),
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync or a new UUID will be randomly generated (e.g. for ISO and RAW files).
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync If for some reason you need to change the medium's UUID, use
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync If a differencing hard disk medium is to be opened by this method, the
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync operation will succeed only if its parent medium and all ancestors,
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync if any, are already known to this VirtualBox installation (for example,
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync were opened by this method before).
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync This method attempts to guess the storage format of the specified medium
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync by reading medium data at the specified location.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync If @a accessMode is ReadWrite (which it should be for hard disks and floppies),
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync the image is opened for read/write access and must have according permissions,
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync as VirtualBox may actually write status information into the disk's metadata
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Note that write access is required for all typical hard disk usage in VirtualBox,
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync since VirtualBox may need to write metadata such as a UUID into the image.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync The only exception is opening a source image temporarily for copying and
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync cloning (see <link to="IMedium::cloneTo" /> when the image will be closed
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync again soon.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync The format of the location string is storage format specific. See
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync <link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Prior to VirtualBox 3.3, opening a medium added it to a global media
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync registry in the VirtualBox.xml file, which was shared between
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync all machines and made transporting machines and their media from one
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync host to another difficult.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Starting with VirtualBox 3.3, media are only added to a registry when
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync they are attached to a machine. Machines created with VirtualBox 3.3
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync or later can have their own media registry. As a result, a medium attached
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync to such a machine will be remembered in that machine's XML settings file.
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Media attached to older machines will continue to be added to the global
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Invalid medium storage file location or could not find the medium
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync at the specified location.
af062818b47340eef15700d2f0211576ba3506eevboxsync Could not get medium storage format.
af062818b47340eef15700d2f0211576ba3506eevboxsync Invalid medium storage format.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Medium has already been added to a media registry.
af062818b47340eef15700d2f0211576ba3506eevboxsync Location of the storage unit that contains medium data in one of
af062818b47340eef15700d2f0211576ba3506eevboxsync the supported storage formats.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="deviceType" type="DeviceType" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync Must be one of "HardDisk", "DVD" or "Floppy".
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="accessMode" type="AccessMode" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Whether to open the image in read/write or read-only mode. For
af062818b47340eef15700d2f0211576ba3506eevboxsync a "DVD" device type, this is ignored and read-only mode is always assumed.</desc>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Returns a medium of the given type that uses the given location or
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync UUID to store medium data.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync The given medium must be known to this VirtualBox installation, i.e.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync it must be previously created by <link to="#createHardDisk"/> or opened
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync The search is done by comparing the value of the @a location argument to
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync the <link to="IMedium::location"/> and <link to="IMedium::id" />
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync attributes of each known medium.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync For locations represented by file names in the host's file system, the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync requested location can be a path relative to the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync only a file name without any path is given, the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <link to="ISystemProperties::defaultHardDiskFolder"> default medium
5112e32d7072e280613921c982a6672f2c859cf3vboxsync folder</link> will be prepended to the file name before searching. Note
5112e32d7072e280613921c982a6672f2c859cf3vboxsync that on case sensitive file systems, a case sensitive comparison is
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync performed, otherwise the case of symbols in the file path is ignored.
af062818b47340eef15700d2f0211576ba3506eevboxsync No medium object matching @a location found.
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>What to search for. This can either be the UUID or the location string of an open medium.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Device type (must be HardDisk, DVD or Floppy)</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync Returns an object describing the specified guest OS type.
af062818b47340eef15700d2f0211576ba3506eevboxsync The requested guest OS type is specified using a string which is a
af062818b47340eef15700d2f0211576ba3506eevboxsync mnemonic identifier of the guest operating system, such as
af062818b47340eef15700d2f0211576ba3506eevboxsync <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
af062818b47340eef15700d2f0211576ba3506eevboxsync particular virtual machine can be read or set using the
af062818b47340eef15700d2f0211576ba3506eevboxsync The <link to="IVirtualBox::guestOSTypes"/> collection contains all
af062818b47340eef15700d2f0211576ba3506eevboxsync available guest OS type objects. Each object has an
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="IGuestOSType::id"/> attribute which contains an identifier of
af062818b47340eef15700d2f0211576ba3506eevboxsync the guest OS this object describes.
af062818b47340eef15700d2f0211576ba3506eevboxsync @a id is not a valid Guest OS type.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="id" type="uuid" mod="string" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="type" type="IGuestOSType" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync Creates a new global shared folder by associating the given logical
af062818b47340eef15700d2f0211576ba3506eevboxsync name with the given host path, adds it to the collection of shared
af062818b47340eef15700d2f0211576ba3506eevboxsync folders and starts sharing it. Refer to the description of
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="ISharedFolder"/> to read more about logical names.
af062818b47340eef15700d2f0211576ba3506eevboxsync In the current implementation, this operation is not
af062818b47340eef15700d2f0211576ba3506eevboxsync implemented.
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Unique logical name of the shared folder.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Full path to the shared folder in the host file system.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Whether the share is writable or readonly</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Whether the share gets automatically mounted by the guest
af062818b47340eef15700d2f0211576ba3506eevboxsync or not.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync Removes the global shared folder with the given name previously
af062818b47340eef15700d2f0211576ba3506eevboxsync created by <link to="#createSharedFolder"/> from the collection of
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync shared folders and stops sharing it.
af062818b47340eef15700d2f0211576ba3506eevboxsync In the current implementation, this operation is not
d10b60270f0c0eeb87f45002a010cff8ba2126b1vboxsync implemented.
b62daae35a821b998dc41ab2c90da52d18b6f229vboxsync <desc>Logical name of the shared folder to remove.</desc>
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync Returns an array representing the global extra data keys which currently
1185da5f621ac306d4b9bed97f289380873dc0b3vboxsync have values defined.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="value" type="wstring" dir="return" safearray="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Returns associated global extra data.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync If the requested data @a key does not exist, this function will
5112e32d7072e280613921c982a6672f2c859cf3vboxsync succeed and return an empty string in the @a value argument.
3a974120cf0d8d23b2531cd62fe04532e6ac205evboxsync Settings file not accessible.
9811e5280582debe26aac8a3b5e30d489450014avboxsync Could not parse the settings file.
114410893548b9522c46fdcbd8f63385eb8bfb68vboxsync Sets associated global extra data.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync If you pass @c null or empty string as a key @a value, the given @a key
af062818b47340eef15700d2f0211576ba3506eevboxsync will be deleted.
af062818b47340eef15700d2f0211576ba3506eevboxsync Before performing the actual data change, this method will ask all
af062818b47340eef15700d2f0211576ba3506eevboxsync registered event listener using the
af062818b47340eef15700d2f0211576ba3506eevboxsync notification for a permission. If one of the listeners refuses the
af062818b47340eef15700d2f0211576ba3506eevboxsync new value, the change will not be performed.
af062818b47340eef15700d2f0211576ba3506eevboxsync On success, the
af062818b47340eef15700d2f0211576ba3506eevboxsync is called to inform all registered listeners about a successful data
af062818b47340eef15700d2f0211576ba3506eevboxsync Settings file not accessible.
af062818b47340eef15700d2f0211576ba3506eevboxsync Could not parse the settings file.
af062818b47340eef15700d2f0211576ba3506eevboxsync Modification request refused.
af062818b47340eef15700d2f0211576ba3506eevboxsync Blocks the caller until any of the properties represented by the
af062818b47340eef15700d2f0211576ba3506eevboxsync @a what argument changes the value or until the given timeout interval
955c1cdb6f113d55c6516187612a87c3b05dc154vboxsync The @a what argument is a comma separated list of property masks that
955c1cdb6f113d55c6516187612a87c3b05dc154vboxsync describe properties the caller is interested in. The property mask is
14e23ea879a4aad5f0beb4cadee81a25cefe6303vboxsync a string in the following format:
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync [[group.]subgroup.]name
af062818b47340eef15700d2f0211576ba3506eevboxsync where @c name is the property name and @c group, @c subgroup are zero
af062818b47340eef15700d2f0211576ba3506eevboxsync or more property group specifiers. Each element (group or name) in
af062818b47340eef15700d2f0211576ba3506eevboxsync the property mask may be either a Latin string or an asterisk symbol
af062818b47340eef15700d2f0211576ba3506eevboxsync (@c "*") which is used to match any string for the given element. A
af062818b47340eef15700d2f0211576ba3506eevboxsync property mask that doesn't contain asterisk symbols represents a
af062818b47340eef15700d2f0211576ba3506eevboxsync single fully qualified property name.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Groups in the fully qualified property name go from more generic (the
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync left-most part) to more specific (the right-most part). The first
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync element is usually a name of the object the property belongs to. The
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync second element may be either a property name, or a child object name,
af062818b47340eef15700d2f0211576ba3506eevboxsync or an index if the preceding element names an object which is one of
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync many objects of the same type. This way, property names form a
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync hierarchy of properties. Here are some examples of property names:
9a0dee30f5bea4fb02c0e836cd9689822e4645d1vboxsync <td><link to="IVirtualBox::version"/> property</td>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <td><link to="IMachine::name"/> property of the machine with the
af062818b47340eef15700d2f0211576ba3506eevboxsync given UUID</td>
9811e5280582debe26aac8a3b5e30d489450014avboxsync Most property names directly correspond to the properties of objects
3a343ca21a267ec3c54e2317e2ed18fe99b8ebbbvboxsync (components) provided by the VirtualBox library and may be used to
3a343ca21a267ec3c54e2317e2ed18fe99b8ebbbvboxsync track changes to these properties. However, there may be
af062818b47340eef15700d2f0211576ba3506eevboxsync pseudo-property names that don't correspond to any existing object's
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync property directly, as well as there may be object properties that
af062818b47340eef15700d2f0211576ba3506eevboxsync don't have a corresponding property name that is understood by this
af062818b47340eef15700d2f0211576ba3506eevboxsync method, and therefore changes to such properties cannot be
af062818b47340eef15700d2f0211576ba3506eevboxsync tracked. See individual object's property descriptions to get a
af062818b47340eef15700d2f0211576ba3506eevboxsync fully qualified property name that can be used with this method (if
af062818b47340eef15700d2f0211576ba3506eevboxsync There is a special property mask @c "*" (i.e. a string consisting of a
af062818b47340eef15700d2f0211576ba3506eevboxsync single asterisk symbol) that can be used to match all properties.
af062818b47340eef15700d2f0211576ba3506eevboxsync Below are more examples of property masks:
af062818b47340eef15700d2f0211576ba3506eevboxsync <td>Track all properties of the VirtualBox object</td>
af062818b47340eef15700d2f0211576ba3506eevboxsync <td>Track changes to the <link to="IMachine::name"/> property of
af062818b47340eef15700d2f0211576ba3506eevboxsync all registered virtual machines</td>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync This function is not implemented in the current version of the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Comma separated list of property masks.</desc>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="timeout" type="unsigned long" dir="in">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Wait timeout in milliseconds.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Specify -1 for an indefinite wait.
af062818b47340eef15700d2f0211576ba3506eevboxsync Comma separated list of properties that have been changed and caused
af062818b47340eef15700d2f0211576ba3506eevboxsync this method to return to the caller.
af062818b47340eef15700d2f0211576ba3506eevboxsync <!--method name="createDHCPServerForInterface">
af062818b47340eef15700d2f0211576ba3506eevboxsync Creates a dhcp server settings to be used for the given interface
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <result name="E_INVALIDARG">
399601f2a6de2856ea7b055d69639bd279d88a08vboxsync Host network interface @a name already exists.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="interface" type="IHostNetworkInterface" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Network Interface</desc>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="server" type="IDHCPServer" dir="out">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <desc>Dhcp server settings</desc>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync </method-->
3a343ca21a267ec3c54e2317e2ed18fe99b8ebbbvboxsync Creates a dhcp server settings to be used for the given internal network name
af062818b47340eef15700d2f0211576ba3506eevboxsync Host network interface @a name already exists.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="server" type="IDHCPServer" dir="return">
30438b06a7a54cb1e30907e480fc66561bd7ea4bvboxsync Searches a dhcp server settings to be used for the given internal network name
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Host network interface @a name already exists.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <param name="server" type="IDHCPServer" dir="return">
14e23ea879a4aad5f0beb4cadee81a25cefe6303vboxsync <!--method name="findDHCPServerForInterface">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Searches a dhcp server settings to be used for the given interface
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <result name="E_INVALIDARG">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Host network interface @a name already exists.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="interface" type="IHostNetworkInterface" dir="in">
d0a71f63bd810b54e0359223fe53b07730154dc5vboxsync <desc>Network Interface</desc>
d0a71f63bd810b54e0359223fe53b07730154dc5vboxsync <param name="server" type="IDHCPServer" dir="out">
d0a71f63bd810b54e0359223fe53b07730154dc5vboxsync <desc>Dhcp server settings</desc>
d0a71f63bd810b54e0359223fe53b07730154dc5vboxsync </method-->
d0a71f63bd810b54e0359223fe53b07730154dc5vboxsync Removes the dhcp server settings
af062818b47340eef15700d2f0211576ba3506eevboxsync Host network interface @a name already exists.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Check if this VirtualBox installation has a firmware
af062818b47340eef15700d2f0211576ba3506eevboxsync of the given type available, either system-wide or per-user.
af062818b47340eef15700d2f0211576ba3506eevboxsync Optionally, this may return a hint where this firmware can be
af062818b47340eef15700d2f0211576ba3506eevboxsync downloaded from.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="firmwareType" type="FirmwareType" dir="in">
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync Type of firmware to check.
9a0dee30f5bea4fb02c0e836cd9689822e4645d1vboxsync <desc>Expected version number, usually empty string (presently ignored).</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync Suggested URL to download this firmware from.
af062818b47340eef15700d2f0211576ba3506eevboxsync Filename of firmware, only valid if result == TRUE.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>If firmware of this type and version is available.</desc>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync </interface>
e0e6ca112bdf0d25db2d07365a502ecda5b391d3vboxsync // IVFSExplorer
ba6524ccac330688123403ddf0a83d702cd9e371vboxsync /////////////////////////////////////////////////////////////////////////
af062818b47340eef15700d2f0211576ba3506eevboxsync name="VFSType"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
af062818b47340eef15700d2f0211576ba3506eevboxsync Virtual file systems supported by VFSExplorer.
af062818b47340eef15700d2f0211576ba3506eevboxsync name="VFSFileType"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="714333cd-44e2-415f-a245-d378fa9b1242"
af062818b47340eef15700d2f0211576ba3506eevboxsync File types known by VFSExplorer.
20bc7269cdb015fe47a9a4a0511470f3b26660f8vboxsync uuid="2bb864a1-02a3-4474-a1d4-fb5f23b742e1"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync wsmap="managed"
af062818b47340eef15700d2f0211576ba3506eevboxsync The VFSExplorer interface unifies access to different file system
af062818b47340eef15700d2f0211576ba3506eevboxsync types. This includes local file systems as well remote file systems like
af062818b47340eef15700d2f0211576ba3506eevboxsync S3. For a list of supported types see <link to="VFSType" />.
af062818b47340eef15700d2f0211576ba3506eevboxsync An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
af062818b47340eef15700d2f0211576ba3506eevboxsync <attribute name="path" type="wstring" readonly="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Returns the current path in the virtual file system.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync </attribute>
af062818b47340eef15700d2f0211576ba3506eevboxsync <attribute name="type" type="VFSType" readonly="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Returns the file system type which is currently in use.</desc>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync </attribute>
20bc7269cdb015fe47a9a4a0511470f3b26660f8vboxsync <desc>Updates the internal list of files/directories from the
20bc7269cdb015fe47a9a4a0511470f3b26660f8vboxsync current directory level. Use <link to="#entryList" /> to get the full list
20bc7269cdb015fe47a9a4a0511470f3b26660f8vboxsync after a call to this method.</desc>
20bc7269cdb015fe47a9a4a0511470f3b26660f8vboxsync <param name="aProgress" type="IProgress" dir="return">
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync <desc>Progress object to track the operation completion.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aProgress" type="IProgress" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Progress object to track the operation completion.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Go one directory upwards from the current directory level.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aProgress" type="IProgress" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Progress object to track the operation completion.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Returns a list of files/directories after a call to <link
af062818b47340eef15700d2f0211576ba3506eevboxsync to="#update" />. The user is responsible for keeping this internal
af062818b47340eef15700d2f0211576ba3506eevboxsync list up do date.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aNames" type="wstring" safearray="yes" dir="out">
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aTypes" type="unsigned long" safearray="yes" dir="out">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Checks if the given file list exists in the current directory
af062818b47340eef15700d2f0211576ba3506eevboxsync level.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aNames" type="wstring" safearray="yes" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aExists" type="wstring" safearray="yes" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Deletes the given files in the current directory level.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aNames" type="wstring" safearray="yes" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aProgress" type="IProgress" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Progress object to track the operation completion.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync </interface>
af062818b47340eef15700d2f0211576ba3506eevboxsync // IAppliance
af062818b47340eef15700d2f0211576ba3506eevboxsync /////////////////////////////////////////////////////////////////////////
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="fb61a4fc-57e7-48d6-859b-71f37d484cf2"
af062818b47340eef15700d2f0211576ba3506eevboxsync wsmap="managed"
040b4a09341f574825386333398110f4db3e1e51vboxsync Represents a platform-independent appliance in OVF format. An instance of this is returned
040b4a09341f574825386333398110f4db3e1e51vboxsync by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
040b4a09341f574825386333398110f4db3e1e51vboxsync virtual machines within an appliance with VirtualBox.
af062818b47340eef15700d2f0211576ba3506eevboxsync The OVF standard suggests two different physical file formats:
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
af062818b47340eef15700d2f0211576ba3506eevboxsync file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
af062818b47340eef15700d2f0211576ba3506eevboxsync this descriptor file references other files such as disk images, as OVF appliances typically
af062818b47340eef15700d2f0211576ba3506eevboxsync do, those additional files must be in the same directory as the descriptor file.</li>
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>If the appliance is distributed as a single file, it must be in TAR format and have the
af062818b47340eef15700d2f0211576ba3506eevboxsync <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
af062818b47340eef15700d2f0211576ba3506eevboxsync files and optionally other files.
af062818b47340eef15700d2f0211576ba3506eevboxsync At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
af062818b47340eef15700d2f0211576ba3506eevboxsync be added with a later version.</li>
af062818b47340eef15700d2f0211576ba3506eevboxsync <b>Importing</b> an OVF appliance into VirtualBox as instances of
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="IMachine" /> involves the following sequence of API calls:
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>On the new object, call <link to="#read" /> with the full path of the OVF file you
af062818b47340eef15700d2f0211576ba3506eevboxsync would like to import. So long as this file is syntactically valid, this will succeed
af062818b47340eef15700d2f0211576ba3506eevboxsync and fill the appliance object with the parsed data from the OVF file.
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
af062818b47340eef15700d2f0211576ba3506eevboxsync contents of the IAppliance attributes accordingly. These can be inspected by a
40bd0fc692d21a6d579862d7ccdc20c2ccf361a5vboxsync VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
40bd0fc692d21a6d579862d7ccdc20c2ccf361a5vboxsync user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
40bd0fc692d21a6d579862d7ccdc20c2ccf361a5vboxsync instances of <link to="IVirtualSystemDescription" /> which represent the virtual
40bd0fc692d21a6d579862d7ccdc20c2ccf361a5vboxsync systems (machines) in the OVF, which in turn describe the virtual hardware prescribed
af062818b47340eef15700d2f0211576ba3506eevboxsync by the OVF (network and hardware adapters, virtual disk images, memory size and so on).
af062818b47340eef15700d2f0211576ba3506eevboxsync The GUI can then give the user the option to confirm and/or change these suggestions.
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync virtual system (machine) to override the suggestions made by the interpret() routine.
040b4a09341f574825386333398110f4db3e1e51vboxsync <li>Finally, call <link to="#importMachines" /> to create virtual machines in
040b4a09341f574825386333398110f4db3e1e51vboxsync VirtualBox as instances of <link to="IMachine" /> that match the information in the
040b4a09341f574825386333398110f4db3e1e51vboxsync virtual system descriptions. After this call suceeded, the UUIDs of the machines created
9a0dee30f5bea4fb02c0e836cd9689822e4645d1vboxsync can be found in the <link to="#machines" /> array attribute.
9a0dee30f5bea4fb02c0e836cd9689822e4645d1vboxsync <b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync an empty IAppliance object.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <li>For each machine you would like to export, call <link to="IMachine::export" />
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync with the IAppliance object you just created. Each such call creates one instance of
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <link to="IVirtualSystemDescription" /> inside the appliance.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync virtual system (machine) to override the suggestions made by the export() routine.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <li>Finally, call <link to="#write" /> with a path specification to have the OVF
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync file written.</li>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <attribute name="path" type="wstring" readonly="yes">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync This attribute is empty until one of these methods has been called.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync </attribute>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <attribute name="disks" type="wstring" readonly="yes" safearray="yes">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Array of virtual disk definitions. One such description exists for each
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync disk definition in the OVF; each string array item represents one such piece of
af062818b47340eef15700d2f0211576ba3506eevboxsync disk information, with the information fields separated by tab (\t) characters.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync The caller should be prepared for additional fields being appended to
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync this string in future versions of VirtualBox and therefore check for
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync the number of tabs in the strings returned.
af062818b47340eef15700d2f0211576ba3506eevboxsync In the current version, the following eight fields are returned per string
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync in the array:
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <li>Disk ID (unique string identifier given to disk)</li>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>Populated size (optional unsigned integer indicating the current size of the
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync disk; can be approximate; -1 if unspecified)</li>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <li>Format (string identifying the disk format, typically
af062818b47340eef15700d2f0211576ba3506eevboxsync "http://www.vmware.com/specifications/vmdk.html#sparse")</li>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <li>Reference (where to find the disk image, typically a file name; if empty,
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync then the disk should be created on import)</li>
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>Image size (optional unsigned integer indicating the size of the image,
af062818b47340eef15700d2f0211576ba3506eevboxsync which need not necessarily be the same as the values specified above, since
af062818b47340eef15700d2f0211576ba3506eevboxsync the image may be compressed or sparse; -1 if not specified)</li>
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>Chunk size (optional unsigned integer if the image is split into chunks;
af062818b47340eef15700d2f0211576ba3506eevboxsync presently unsupported and always -1)</li>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync </attribute>
af062818b47340eef15700d2f0211576ba3506eevboxsync <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc> Array of virtual system descriptions. One such description is created
af062818b47340eef15700d2f0211576ba3506eevboxsync for each virtual system (machine) found in the OVF.
af062818b47340eef15700d2f0211576ba3506eevboxsync This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
af062818b47340eef15700d2f0211576ba3506eevboxsync (for export) has been called.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync </attribute>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <attribute name="machines" type="wstring" readonly="yes" safearray="yes">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Contains the UUIDs of the machines created from the information in this appliances. This is only
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync relevant for the import case, and will only contain data after a call to <link to="#importMachines" />
e068057c82b010bc7cc663e8f57ac3ef1890a33cvboxsync </attribute>
9a0dee30f5bea4fb02c0e836cd9689822e4645d1vboxsync Reads an OVF file into the appliance object.
9a0dee30f5bea4fb02c0e836cd9689822e4645d1vboxsync This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
af062818b47340eef15700d2f0211576ba3506eevboxsync mere fact that this method returns successfully does not mean that VirtualBox supports all
af062818b47340eef15700d2f0211576ba3506eevboxsync features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
af062818b47340eef15700d2f0211576ba3506eevboxsync Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
af062818b47340eef15700d2f0211576ba3506eevboxsync on whether the appliance is distributed as a set of files or as a single file, respectively).
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aProgress" type="IProgress" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Progress object to track the operation completion.</desc>
9a0dee30f5bea4fb02c0e836cd9689822e4645d1vboxsync Interprets the OVF data that was read when the appliance was constructed. After
af062818b47340eef15700d2f0211576ba3506eevboxsync calling this method, one can inspect the
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="#virtualSystemDescriptions" /> array attribute, which will then contain
af062818b47340eef15700d2f0211576ba3506eevboxsync one <link to="IVirtualSystemDescription" /> for each virtual machine found in
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync the appliance.
af062818b47340eef15700d2f0211576ba3506eevboxsync Calling this method is the second step of importing an appliance into VirtualBox;
af062818b47340eef15700d2f0211576ba3506eevboxsync After calling this method, one should call <link to="#getWarnings" /> to find out
af062818b47340eef15700d2f0211576ba3506eevboxsync if problems were encountered during the processing which might later lead to
af062818b47340eef15700d2f0211576ba3506eevboxsync Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
af062818b47340eef15700d2f0211576ba3506eevboxsync and other interfaces that match the information contained in the appliance as
af062818b47340eef15700d2f0211576ba3506eevboxsync closely as possible, as represented by the import instructions in the
af062818b47340eef15700d2f0211576ba3506eevboxsync Calling this method is the final step of importing an appliance into VirtualBox;
af062818b47340eef15700d2f0211576ba3506eevboxsync Since importing the appliance will most probably involve copying and converting
af062818b47340eef15700d2f0211576ba3506eevboxsync disk images, which can take a long time, this method operates asynchronously and
af062818b47340eef15700d2f0211576ba3506eevboxsync returns an IProgress object to allow the caller to monitor the progress.
af062818b47340eef15700d2f0211576ba3506eevboxsync After the import succeeded, the UUIDs of the IMachine instances created can be
af062818b47340eef15700d2f0211576ba3506eevboxsync retrieved from the <link to="#machines" /> array attribute.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aProgress" type="IProgress" dir="return">
040b4a09341f574825386333398110f4db3e1e51vboxsync <desc>Progress object to track the operation completion.</desc>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>The URI describing the file system to use.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aExplorer" type="IVFSExplorer" dir="return">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Writes the contents of the appliance exports into a new OVF file.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Calling this method is the final step of exporting an appliance from VirtualBox;
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Since exporting the appliance will most probably involve copying and converting
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync disk images, which can take a long time, this method operates asynchronously and
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync returns an IProgress object to allow the caller to monitor the progress.
af062818b47340eef15700d2f0211576ba3506eevboxsync Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
af062818b47340eef15700d2f0211576ba3506eevboxsync future versions of VirtualBox may support additional formats.
af062818b47340eef15700d2f0211576ba3506eevboxsync Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync on whether the appliance is distributed as a set of files or as a single file, respectively).
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aProgress" type="IProgress" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Progress object to track the operation completion.</desc>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <desc>Returns textual warnings which occured during execution of <link to="#interpret" />.</desc>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="aWarnings" type="wstring" dir="return" safearray="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync </interface>
af062818b47340eef15700d2f0211576ba3506eevboxsync name="VirtualSystemDescriptionType"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="c0f8f135-3a1d-417d-afa6-b38b95a91f90"
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync a configuration value.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync name="VirtualSystemDescriptionValueType"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
af062818b47340eef15700d2f0211576ba3506eevboxsync type to fetch.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync name="IVirtualSystemDescription" extends="$unknown"
af062818b47340eef15700d2f0211576ba3506eevboxsync uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
af062818b47340eef15700d2f0211576ba3506eevboxsync wsmap="managed"
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Represents one virtual system (machine) in an appliance. This interface is used in
af062818b47340eef15700d2f0211576ba3506eevboxsync the <link to="IAppliance::virtualSystemDescriptions" /> array. After
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="IAppliance::interpret" /> has been called, that array contains information
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync about how the virtual systems described in the OVF should best be imported into
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync VirtualBox virtual machines. See <link to="IAppliance" /> for the steps required to
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync import an OVF into VirtualBox.
af062818b47340eef15700d2f0211576ba3506eevboxsync <attribute name="count" type="unsigned long" readonly="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Return the number of virtual system description entries.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync </attribute>
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Returns information about the virtual system as arrays of instruction items. In each array, the
af062818b47340eef15700d2f0211576ba3506eevboxsync items with the same indices correspond and jointly represent an import instruction for VirtualBox.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync The list below identifies the value sets that are possible depending on the
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
af062818b47340eef15700d2f0211576ba3506eevboxsync the array item with the same index in @a aOvfValues[] will contain the original value as contained
af062818b47340eef15700d2f0211576ba3506eevboxsync in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
af062818b47340eef15700d2f0211576ba3506eevboxsync will contain a suggested value to be used for VirtualBox. Depending on the description type,
af062818b47340eef15700d2f0211576ba3506eevboxsync the @a aExtraConfigValues[] array item may also be used.
af062818b47340eef15700d2f0211576ba3506eevboxsync "OS": the guest operating system type. There must be exactly one such array item on import. The
5112e32d7072e280613921c982a6672f2c859cf3vboxsync corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
af062818b47340eef15700d2f0211576ba3506eevboxsync item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF.
af062818b47340eef15700d2f0211576ba3506eevboxsync "Name": the name to give to the new virtual machine. There can be at most one such array item;
af062818b47340eef15700d2f0211576ba3506eevboxsync if none is present on import, then an automatic name will be created from the operating system
af062818b47340eef15700d2f0211576ba3506eevboxsync type. The correponding item im @a aOvfValues[] will contain the suggested virtual machine name
af062818b47340eef15700d2f0211576ba3506eevboxsync from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
af062818b47340eef15700d2f0211576ba3506eevboxsync <link to="IMachine" /> name that does not exist yet.
af062818b47340eef15700d2f0211576ba3506eevboxsync "Description": an arbitrary description.
af062818b47340eef15700d2f0211576ba3506eevboxsync "License": the EULA section from the OVF, if present. It is the responsibility of the calling
af062818b47340eef15700d2f0211576ba3506eevboxsync code to display such a license for agreement; the Main API does not enforce any such policy.
af062818b47340eef15700d2f0211576ba3506eevboxsync Miscellaneous: reserved for future use.
af062818b47340eef15700d2f0211576ba3506eevboxsync "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
af062818b47340eef15700d2f0211576ba3506eevboxsync "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
af062818b47340eef15700d2f0211576ba3506eevboxsync is present on import, then VirtualBox will set a meaningful default based on the operating system
af062818b47340eef15700d2f0211576ba3506eevboxsync "HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
af062818b47340eef15700d2f0211576ba3506eevboxsync An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
af062818b47340eef15700d2f0211576ba3506eevboxsync the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
af062818b47340eef15700d2f0211576ba3506eevboxsync writes into the OVF.
af062818b47340eef15700d2f0211576ba3506eevboxsync The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
af062818b47340eef15700d2f0211576ba3506eevboxsync type can use to specify which hard disk controller a virtual disk should be connected to.
af062818b47340eef15700d2f0211576ba3506eevboxsync Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
af062818b47340eef15700d2f0211576ba3506eevboxsync in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
af062818b47340eef15700d2f0211576ba3506eevboxsync its virtual machines supports four channels (primary master, primary slave, secondary master,
af062818b47340eef15700d2f0211576ba3506eevboxsync secondary slave) and thus maps to two IDE controllers in the OVF sense.
af062818b47340eef15700d2f0211576ba3506eevboxsync "HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
af062818b47340eef15700d2f0211576ba3506eevboxsync has no value in @a aOvfValues[] or @a aVBoxValues[].
af062818b47340eef15700d2f0211576ba3506eevboxsync The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
af062818b47340eef15700d2f0211576ba3506eevboxsync "HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
af062818b47340eef15700d2f0211576ba3506eevboxsync The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or
af062818b47340eef15700d2f0211576ba3506eevboxsync "LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller
af062818b47340eef15700d2f0211576ba3506eevboxsync whereas VirtualBox considers it a class of storage controllers of its own; see
af062818b47340eef15700d2f0211576ba3506eevboxsync The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
af062818b47340eef15700d2f0211576ba3506eevboxsync "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
af062818b47340eef15700d2f0211576ba3506eevboxsync arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
af062818b47340eef15700d2f0211576ba3506eevboxsync The array item in @a aOvfValues[] will contain the file specification from the OVF file (without
5112e32d7072e280613921c982a6672f2c859cf3vboxsync a path since the image file should be in the same location as the OVF file itself), whereas the
5112e32d7072e280613921c982a6672f2c859cf3vboxsync item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
5112e32d7072e280613921c982a6672f2c859cf3vboxsync hard disk image. This means that on import the image will be copied and converted from the
af062818b47340eef15700d2f0211576ba3506eevboxsync "ovf" location to the "vbox" location; on export, this will be handled the other way round.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync The matching item in the @a aExtraConfigValues[] array must contain a string of the following
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync format: "controller=<index>;channel=<c>"
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync In this string, <index> must be an integer specifying the hard disk controller to connect
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync the image to. That number must be the index of an array item with one of the hard disk controller
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync In addition, <c> must specify the channel to use on that controller. For IDE controllers,
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
af062818b47340eef15700d2f0211576ba3506eevboxsync before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
af062818b47340eef15700d2f0211576ba3506eevboxsync no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
af062818b47340eef15700d2f0211576ba3506eevboxsync "CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
af062818b47340eef15700d2f0211576ba3506eevboxsync attachment information as with "HardDiskImage" items.
af062818b47340eef15700d2f0211576ba3506eevboxsync "CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
af062818b47340eef15700d2f0211576ba3506eevboxsync attachment information as with "HardDiskImage" items.
af062818b47340eef15700d2f0211576ba3506eevboxsync "NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
af062818b47340eef15700d2f0211576ba3506eevboxsync for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
af062818b47340eef15700d2f0211576ba3506eevboxsync of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
af062818b47340eef15700d2f0211576ba3506eevboxsync "USBController": a USB controller. There can be at most one such item. If and only if such an
5112e32d7072e280613921c982a6672f2c859cf3vboxsync item ispresent, USB support will be enabled for the new virtual machine.
af062818b47340eef15700d2f0211576ba3506eevboxsync "SoundCard": a sound card. There can be at most one such item. If and only if such an item is
af062818b47340eef15700d2f0211576ba3506eevboxsync present, sound support will be enabled for the new virtual machine. Note that the virtual
af062818b47340eef15700d2f0211576ba3506eevboxsync machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
af062818b47340eef15700d2f0211576ba3506eevboxsync may be different from the virtual soundcard expected by the appliance.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aRefs" type="wstring" dir="out" safearray="yes">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <desc>This is the same as <link to="#getDescription" /> except that you can specify which types
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync should be returned.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aType" type="VirtualSystemDescriptionType" dir="in">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aRefs" type="wstring" dir="out" safearray="yes">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync values.</desc>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="aType" type="VirtualSystemDescriptionType" dir="in">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="aValues" type="wstring" dir="return" safearray="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync This method allows the appliance's user to change the configuration for the virtual
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync system descriptions. For each array item returned from <link to="#getDescription" />,
af062818b47340eef15700d2f0211576ba3506eevboxsync you must pass in one boolean value and one configuration value.
af062818b47340eef15700d2f0211576ba3506eevboxsync Each item in the boolean array determines whether the particular configuration item
af062818b47340eef15700d2f0211576ba3506eevboxsync should be enabled.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
af062818b47340eef15700d2f0211576ba3506eevboxsync HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
af062818b47340eef15700d2f0211576ba3506eevboxsync and SoundCard.
af062818b47340eef15700d2f0211576ba3506eevboxsync For the "vbox" and "extra configuration" values, if you pass in the same arrays
af062818b47340eef15700d2f0211576ba3506eevboxsync as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription(),
af062818b47340eef15700d2f0211576ba3506eevboxsync the configuration remains unchanged. Please see the documentation for getDescription()
5112e32d7072e280613921c982a6672f2c859cf3vboxsync for valid configuration values for the individual array item types. If the
af062818b47340eef15700d2f0211576ba3506eevboxsync corresponding item in the aEnabled array is @c false, the configuration value is ignored.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aEnabled" type="boolean" dir="in" safearray="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aVBoxValues" type="wstring" dir="in" safearray="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync This method adds an additional description entry to the stack of already
06bfdb01d92810c68168b1304ac7aef2130c86a0vboxsync available descriptions for this virtual system. This is handy for writing
bf7ab711aa3580b3a587dcbc4653fe78c99fff37vboxsync values which aren't directly supported by VirtualBox. One example would
bf7ab711aa3580b3a587dcbc4653fe78c99fff37vboxsync be the License type of <link to="VirtualSystemDescriptionType" />.
06bfdb01d92810c68168b1304ac7aef2130c86a0vboxsync <param name="aType" type="VirtualSystemDescriptionType" dir="in">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="aExtraConfigValue" type="wstring" dir="in">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync </interface>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync // IMachine
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync /////////////////////////////////////////////////////////////////////////
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync uuid="e2da8b1a-2ad1-490e-b29e-c33a144791b6"
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync internal="yes"
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync wsmap="suppress"
5112e32d7072e280613921c982a6672f2c859cf3vboxsync Updates the flag whether the saved state file is removed on a
5112e32d7072e280613921c982a6672f2c859cf3vboxsync machine state change from Saved to PoweredOff.
af062818b47340eef15700d2f0211576ba3506eevboxsync Updates the VM state.
af062818b47340eef15700d2f0211576ba3506eevboxsync This operation will also update the settings file with the correct
af062818b47340eef15700d2f0211576ba3506eevboxsync information about the saved state file and delete this file from disk
af062818b47340eef15700d2f0211576ba3506eevboxsync when appropriate.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync gives it the progress object that should be part of any pending
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <link to="IMachine::launchVMProcess"/> operations. The progress
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync object may be called back to reflect an early cancelation, so some care
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync have to be taken with respect to any cancelation callbacks. The console
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync object will call <link to="IInternalMachineControl::endPowerUp"/>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync to signal the completion of the progress object.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="aProgress" type="IProgress" dir="in" />
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Tells VBoxSVC that <link to="IConsole::powerUp"/> has completed.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync This method may query status information from the progress object it
af062818b47340eef15700d2f0211576ba3506eevboxsync received in <link to="IInternalMachineControl::beginPowerUp"/> and copy
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync it over to any in-progress <link to="IMachine::launchVMProcess"/>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync call in order to complete that progress object.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Asks the server to run USB devices filters of the associated
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync machine against the given USB device and tell if there is
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Intended to be used only for remote USB devices. Local
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync ones don't require to call this method (this is done
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync implicitly by the Host and USBProxyService).
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="maskedInterfaces" type="unsigned long" dir="out"/>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Requests a capture of the given host USB device.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync When the request is completed, the VM process will
5112e32d7072e280613921c982a6672f2c859cf3vboxsync get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync notification.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="id" type="uuid" mod="string" dir="in"/>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Notification that a VM is going to detach (@a done = @c false) or has
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync already detached (@a done = @c true) the given USB device.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync When the @a done = @c true request is completed, the VM process will
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
af062818b47340eef15700d2f0211576ba3506eevboxsync notification.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync In the @a done = @c true case, the server must run its own filters
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync and filters of all VMs but this one on the detached device
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync as if it were just attached to the host computer.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <param name="id" type="uuid" mod="string" dir="in"/>
af062818b47340eef15700d2f0211576ba3506eevboxsync Requests a capture all matching USB devices attached to the host.
af062818b47340eef15700d2f0211576ba3506eevboxsync When the request is completed, the VM process will
af062818b47340eef15700d2f0211576ba3506eevboxsync get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
af062818b47340eef15700d2f0211576ba3506eevboxsync notification per every captured device.
af062818b47340eef15700d2f0211576ba3506eevboxsync Notification that a VM that is being powered down. The done
af062818b47340eef15700d2f0211576ba3506eevboxsync parameter indicates whether which stage of the power down
af062818b47340eef15700d2f0211576ba3506eevboxsync we're at. When @a done = @c false the VM is announcing its
af062818b47340eef15700d2f0211576ba3506eevboxsync intentions, while when @a done = @c true the VM is reporting
af062818b47340eef15700d2f0211576ba3506eevboxsync what it has done.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync In the @a done = @c true case, the server must run its own filters
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync and filters of all VMs but this one on all detach devices as
af062818b47340eef15700d2f0211576ba3506eevboxsync if they were just attached to the host computer.
af062818b47340eef15700d2f0211576ba3506eevboxsync Triggered by the given session object when the session is about
af062818b47340eef15700d2f0211576ba3506eevboxsync to close normally.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="progress" type="IProgress" dir="return">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Used to wait until the corresponding machine is actually
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync dissociated from the given session on the server.
af062818b47340eef15700d2f0211576ba3506eevboxsync Returned only when this session is a direct one.
af062818b47340eef15700d2f0211576ba3506eevboxsync Called by the VM process to inform the server it wants to
af062818b47340eef15700d2f0211576ba3506eevboxsync save the current state and stop the VM execution.
af062818b47340eef15700d2f0211576ba3506eevboxsync Progress object created by the VM process to wait until
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync the state is saved.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="stateFilePath" type="wstring" dir="out">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync File path the VM process must save the execution state to.
af062818b47340eef15700d2f0211576ba3506eevboxsync Called by the VM process to inform the server that saving
af062818b47340eef15700d2f0211576ba3506eevboxsync the state previously requested by #beginSavingState is either
af062818b47340eef15700d2f0211576ba3506eevboxsync successfully finished or there was a failure.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync Settings file not accessible.
af062818b47340eef15700d2f0211576ba3506eevboxsync Could not parse the settings file.
b62daae35a821b998dc41ab2c90da52d18b6f229vboxsync <desc>@c true to indicate success and @c false otherwise.
af062818b47340eef15700d2f0211576ba3506eevboxsync Gets called by IConsole::adoptSavedState.
af062818b47340eef15700d2f0211576ba3506eevboxsync Invalid saved state file path.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="savedStateFile" type="wstring" dir="in">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <desc>Path to the saved state file to adopt.</desc>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Called from the VM process to request from the server to perform the
040b4a09341f574825386333398110f4db3e1e51vboxsync server-side actions of creating a snapshot (creating differencing images
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync and the snapshot object).
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Settings file not accessible.
af062818b47340eef15700d2f0211576ba3506eevboxsync Could not parse the settings file.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>The console object that initiated this call.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="consoleProgress" type="IProgress" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync Progress object created by the VM process tracking the
af062818b47340eef15700d2f0211576ba3506eevboxsync snapshot's progress. This has the following sub-operations:
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
af062818b47340eef15700d2f0211576ba3506eevboxsync <li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <param name="fTakingSnapshotOnline" type="boolean" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync Whether this is an online snapshot (i.e. the machine is running).
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="stateFilePath" type="wstring" dir="out">
af062818b47340eef15700d2f0211576ba3506eevboxsync File path the VM process must save the execution state to.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Called by the VM process to inform the server that the snapshot
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync previously requested by #beginTakingSnapshot is either
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync successfully taken or there was a failure.
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>@c true to indicate success and @c false otherwise</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync Gets called by IConsole::deleteSnapshot.
af062818b47340eef15700d2f0211576ba3506eevboxsync Snapshot has more than one child snapshot.
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>The console object that initiated this call.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="id" type="uuid" mod="string" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="machineState" type="MachineState" dir="out">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <desc>New machine state after this operation is started.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="progress" type="IProgress" dir="return">
af062818b47340eef15700d2f0211576ba3506eevboxsync <desc>Progress object to track the operation completion.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync Gets called by IConsole::onlineMergeMedium.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="mediumAttachment" type="IMediumAttachment" dir="in">
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>The medium attachment which needs to be cleaned up.</desc>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <param name="mergeForward" type="boolean" dir="in">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <param name="parentForTarget" type="IMedium" dir="in">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <desc>For forward merges: new parent for target medium.</desc>
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <desc>For backward merges: list of media which need their parent UUID
5112e32d7072e280613921c982a6672f2c859cf3vboxsync updated.</desc>
040b4a09341f574825386333398110f4db3e1e51vboxsync Gets called by IConsole::RestoreSnapshot.
040b4a09341f574825386333398110f4db3e1e51vboxsync <desc>The console object that initiated this call.</desc>
040b4a09341f574825386333398110f4db3e1e51vboxsync <desc>The snapshot to restore the VM state from.</desc>
040b4a09341f574825386333398110f4db3e1e51vboxsync <param name="machineState" type="MachineState" dir="out">
040b4a09341f574825386333398110f4db3e1e51vboxsync <desc>New machine state after this operation is started.</desc>
040b4a09341f574825386333398110f4db3e1e51vboxsync <param name="progress" type="IProgress" dir="return">
040b4a09341f574825386333398110f4db3e1e51vboxsync <desc>Progress object to track the operation completion.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync Get the list of the guest properties matching a set of patterns along
af062818b47340eef15700d2f0211576ba3506eevboxsync with their values, time stamps and flags and give responsibility for
af062818b47340eef15700d2f0211576ba3506eevboxsync managing properties to the console.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="name" type="wstring" dir="out" safearray="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync The names of the properties returned.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="value" type="wstring" dir="out" safearray="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync The values of the properties returned. The array entries match the
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync corresponding entries in the @a name array.
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
af062818b47340eef15700d2f0211576ba3506eevboxsync The time stamps of the properties returned. The array entries match
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync the corresponding entries in the @a name array.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync <param name="flags" type="wstring" dir="out" safearray="yes">
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync The flags of the properties returned. The array entries match the
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync corresponding entries in the @a name array.
b62daae35a821b998dc41ab2c90da52d18b6f229vboxsync Update a single guest property in IMachine.
040b4a09341f574825386333398110f4db3e1e51vboxsync The name of the property to be updated.
af062818b47340eef15700d2f0211576ba3506eevboxsync The value of the property.
af062818b47340eef15700d2f0211576ba3506eevboxsync <param name="timestamp" type="unsigned long long" dir="in">
af062818b47340eef15700d2f0211576ba3506eevboxsync The timestamp of the property.
af062818b47340eef15700d2f0211576ba3506eevboxsync The flags of the property.
af062818b47340eef15700d2f0211576ba3506eevboxsync Locks all media attached to the machine for writing and parents of
af062818b47340eef15700d2f0211576ba3506eevboxsync attached differencing media (if any) for reading. This operation is
af062818b47340eef15700d2f0211576ba3506eevboxsync atomic so that if it fails no media is actually locked.
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync This method is intended to be called when the machine is in Starting or
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync Restoring state. The locked media will be automatically unlocked when
af062818b47340eef15700d2f0211576ba3506eevboxsync the machine is powered off or crashed.
af062818b47340eef15700d2f0211576ba3506eevboxsync Unlocks all media previously locked using
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync This method is intended to be used with teleportation so that it is
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync possible to teleport between processes on the same machine.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync </interface>
040b4a09341f574825386333398110f4db3e1e51vboxsync uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync wsmap="managed"
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync The IBIOSSettings interface represents BIOS settings of the virtual
af062818b47340eef15700d2f0211576ba3506eevboxsync machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync </attribute>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync <desc>Fade out flag for BIOS logo animation.</desc>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync </attribute>
040b4a09341f574825386333398110f4db3e1e51vboxsync <attribute name="logoDisplayTime" type="unsigned long">
040b4a09341f574825386333398110f4db3e1e51vboxsync <desc>BIOS logo display time in milliseconds (0 = default).</desc>
040b4a09341f574825386333398110f4db3e1e51vboxsync </attribute>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync Local file system path for external BIOS splash image. Empty string
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync means the default image is shown on boot.
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync </attribute>
af062818b47340eef15700d2f0211576ba3506eevboxsync <attribute name="bootMenuMode" type="BIOSBootMenuMode">
af062818b47340eef15700d2f0211576ba3506eevboxsync </attribute>
af062818b47340eef15700d2f0211576ba3506eevboxsync </attribute>
af062818b47340eef15700d2f0211576ba3506eevboxsync IO APIC support flag. If set, VirtualBox will provide an IO APIC
af062818b47340eef15700d2f0211576ba3506eevboxsync and support IRQs above 15.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync </attribute>
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync Offset in milliseconds from the host system time. This allows for
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync guests running with a different system date/time than the host.
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync It is equivalent to setting the system date/time in the BIOS except
a3133ef29cdf3656735d569fd64e54c9286effc0vboxsync it is not an absolute value but a relative one. Guest Additions
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync time synchronization honors this offset.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync </attribute>
589fd26cedb2b4ebbed14f2964cad03cc8ebbca2vboxsync PXE debug logging flag. If set, VirtualBox will write extensive
5112e32d7072e280613921c982a6672f2c859cf3vboxsync PXE trace information to the release log.
af062818b47340eef15700d2f0211576ba3506eevboxsync </attribute>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync </interface>
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441">
554f00fe75489f3f3ce7fbb6d126ce1d2c5c922cvboxsync <desc>Cleanup mode, used with <link to="IMachine::unregister" />.
5112e32d7072e280613921c982a6672f2c859cf3vboxsync <desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc>
ee6bcfc59fe3b0230aad85e2ef63d0402b7719b2vboxsync <desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc>
af062818b47340eef15700d2f0211576ba3506eevboxsync <const name="DetachAllReturnHardDisksOnly" value="3">
<desc>Delete all snapshots, detach all media and return hard disks for closing, but not removeable media.</desc>
machine (e.g. the virtual machine is running), the machine object
configuration of the virtual machine in detail (i.e. network
settings (e.g. to get access to VM statistics or take
the machine (i.e. the machine has stopped running).
attached to other machines (i.e. shared between several machines). If such a shared
This method must only be called on machines which are either write-locked (i.e. on instances
in use, e.g. because it is still attached to a second machine; in that case the
file data, i.e. the line ending style depends on the platform of
folders). When the session is closed (e.g. the machine is powered down),
for other reason (e.g. implicitly because of multiple machine
<desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
output data, i.e. the line ending style depends on the platform of
The returned machine object is immutable, i.e. no
@c null if the snapshot has no parent (i.e. is the first snapshot).
See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
removable media, but can also point to a network location (e.g.
VirtualBox, e.g. by storing a copy of the real medium of the corresponding
As a result, when VirtualBox starts up (e.g. the VirtualBox
e.g. before the storage unit is created, and works as follows. You set the
CurState (none) CurState (D3->D2.vdi)
CurState (D3->B.vdi)
it cannot be attached directly and needs an indirect attachment (i.e.
object. This can e.g. happen for medium objects representing host
property returns the medium object itself (i.e. the same object this
(i.e. the value equal to the @c machineId argument), followed by
Invalid medium state (e.g. not created, locked, inaccessible,
Invalid medium state (e.g. not created, locked, inaccessible,
state (i.e. must not have an existing storage unit). Upon successful
target medium is a linear chain, i.e. all medium in this
state (i.e. must not have an existing storage unit) or in
be a base image, i.e. completely independent. It is possible to specify
See also www.fourcc.org for more information about FOURCC pixel formats.
The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color covnersion, overlaying, etc.)
current video mode (i.e. left unchanged).
Filename where a network trace will be stored. If not set, VBox-pid.pcap
i.e. it is ignored by IHostUSBDeviceFilter objects.
To start a VM using one of the existing VirtualBox front-ends (e.g. the
if the session currently has a machine locked (i.e. its
This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.
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.
unidirectional protocols (i.e. web services), the concepts of passive and active
for example for vetoable changes, or if event refers to some resource which need to be kept immutable
namespace="virtualbox.org">
namespace="virtualbox.org">
namespace="virtualbox.org">