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