VirtualBox.xidl revision 8eb41be1e0e5ce004d030dac627e4df6d486e145
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync * :tabSize=2:indentSize=2:noTabs=true:
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync * :folding=explicit:collapseFolds=1:
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * Master declaration for VirtualBox's Main API, represented
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * by COM/XPCOM and web service interfaces.
d14682a025d2c801f1e777f491092d2ebbe78c3cvboxsync * From this document, the build system generates several files
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * via XSLT that are then used during the build process.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * Below is the list of XSL templates that operate on this file and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * output files they generate. These XSL templates must be updated
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * whenever the schema of this file changes:
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * out/<platform>/bin/sdk/idl/VirtualBox.idl
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * (MS COM interface definition file for Main API)
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync * out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * (XPCOM interface definition file for Main API)
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * out/<platform>/obj/src/VBox/Main/VirtualBox.idl
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * (pseudo-IDL for Doxygen to generate the official Main API
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * documentation)
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * 4. src/VBox/Main/webservice/*.xsl =>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * a bunch of WSDL and C++ files
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * (VirtualBox web service sources and SOAP mappers;
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * see src/VBox/Main/webservice/Makefile.kmk for details)
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * (smart Qt-based C++ wrapper classes for COM interfaces
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * of the Main API)
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * 6. src/VBox/Frontends/VirtualBox4/include/COMWrappers.xsl =>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * out/<platform>/obj/src/VBox/Frontends/VirtualBox4/VirtualBox/include/COMWrappers.h
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * (smart Qt-based C++ wrapper classes for COM interfaces
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * of the Main API)
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * 7. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * (Main API TypeLib block for the WiX installer)
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Copyright (C) 2006-2007 Sun Microsystems, Inc.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync This file is part of VirtualBox Open Source Edition (OSE), as
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync available from http://www.virtualbox.org. This file is free software;
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync you can redistribute it and/or modify it under the terms of the GNU
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync General Public License (GPL) as published by the Free Software
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Foundation, in version 2 as it comes in the "COPYING" file of the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync VirtualBox OSE distribution. VirtualBox OSE is distributed in the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Clara, CA 95054 USA or visit http://www.sun.com if you need
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync additional information or have any questions.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync// currenty, nsISupportsImpl.h lacks the below-like macros
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync#define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync NS_IMPL_THREADSAFE_ADDREF(_class) \
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync NS_IMPL_THREADSAFE_RELEASE(_class) \
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync NS_IMPL_QUERY_INTERFACE1_CI(_class, _interface) \
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync#define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync NS_IMPL_THREADSAFE_ADDREF(_class) \
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync NS_IMPL_THREADSAFE_RELEASE(_class) \
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync NS_IMPL_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
e6e69eb2216092b564f920a6214f5103333ce54cvboxsync NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
529e6bec97f5ef2e005c99c205c9624583ecb7f0vboxsync name="VirtualBox"
529e6bec97f5ef2e005c99c205c9624583ecb7f0vboxsync uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
529e6bec97f5ef2e005c99c205c9624583ecb7f0vboxsync version="1.3"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync desc="VirtualBox Type Library"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync supportsErrorInfo="yes"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync // all common enums
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync /////////////////////////////////////////////////////////////////////////
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync name="TSBool"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Boolean variable having a third state, default.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync name="MachineState"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync uuid="73bf04d0-7c4f-4684-9abf-d65a9ad74343"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Virtual machine execution state. This enumeration represents possible
730f8be51b729e8a3c1e32c756cd0f4ec088dd4dvboxsync values of the <link to="IMachine::state"/> attribute.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <desc><tt>null</tt> value. Never used by the API.</desc>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The machine is not running.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The machine is not currently running, but the execution state
18745d2ecb6a9d5f83c1c7a6f823847b9c3b4f57vboxsync of the machine has been saved to an external file when it
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync was running.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync No any machine settings can be altered when the machine
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync is in this state.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync A process that run the machine has abnormally terminated.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Other than that, this value is equivalent to #PoweredOff.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The machine is currently being executed.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync This value can be used in comparison expressions:
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync all state values below it describe a virtual machine that is
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync not currently being executed (i.e., it is completely out of
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync For whoever decides to touch this enum: In order to keep the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync aforementioned comparisons valid, this state must immediately
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync preceed the Paused state.
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync The execution of the machine has been paused.
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync This value can be used in comparison expressions: all state values
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync above it represent unstable states of the running virtual
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync machine. Unless explicitly stated otherwise, no machine settings can
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync be altered when it is in one of the unstable sates.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync For whoever decides to touch this enum: In order to keep the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync aforementioned comparisons valid, this state must immediately
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync follow the Running state.
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync The execution of the machine has reached the Guru Meditaion
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync condition. This condition indicates an internal VMM failure which may
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync happen as a result of either an unhandled low-level virtual hardware
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync exception or one of the recompiler exceptions (such as
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The machine is being started after
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <link to="IConsole::powerUp">powering it on</link> from a
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync zero execution state.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The machine is being normally stopped
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync (after explicitly <link to="IConsole::powerDown">powering it off</link>,
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync or after the guest OS has initiated a shutdown sequence).
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The machine is saving its execution state to a file as a
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync result of calling <link to="IConsole::saveState"/> or an online
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync snapshot of the machine is being taken using
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The execution state of the machine is being restored from a file
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync after <link to="IConsole::powerUp">powering it on</link> from
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync a saved execution state.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync A snapshot of the machine is being discarded after calling
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <link to="IConsole::discardSnapshot"/> or its current state is
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync being discarded after <link to="IConsole::discardCurrentState"/>.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync name="SessionState"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Session state. This enumeration represents possible values of
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
7c19e11502220292d5270519296442234c2493cdvboxsync attributes. Idividual value descriptions contain the appropriate
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync meaning for every case.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <desc><tt>null</tt> value. Never used by the API.</desc>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The machine has no open sessions (<link to="IMachine::sessionState"/>);
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the session is closed (<link to="ISession::state"/>)
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The machine has an open direct session (<link to="IMachine::sessionState"/>);
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync A new (direct) session is being opened for the machine
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync as a result of <link to="IVirtualBox::openRemoteSession()"/>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the session is currently being opened
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync as a result of <link to="IVirtualBox::openRemoteSession()"/>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The direct session is being closed (<link to="IMachine::sessionState"/>);
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the session is being closed (<link to="ISession::state"/>)
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync name="SessionType"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Session type. This enumeration represents possible values of the
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <desc><tt>null</tt> value. Never used by the API.</desc>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Direct session
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync (opened by <link to="IVirtualBox::openSession()"/>)
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Remote session
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync (opened by <link to="IVirtualBox::openRemoteSession()"/>)
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Existing session
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync (opened by <link to="IVirtualBox::openExistingSession()"/>)
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync name="DeviceType"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Device type.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <tt>null</tt> value which may also mean "no device".
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync This value is not allowed for
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync name="DeviceActivity"
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync Device activity for <link to="IConsole::getDeviceActivity"/>.
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync name="ResourceUsage"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync uuid="FC56E4B6-B195-48e2-A5E1-A667B0D9F809"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Usage type constants for
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc><tt>null</tt> value. Never used by the API.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Scopes the VMs that use the resource permanently
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync (the information about this usage is stored in the VM
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync settings file).
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Scopes the VMs that are temporarily using the resource
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync (the information about the usage is not yet saved in the VM
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync settings file). Temporary usage can take place only in the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync context of an open session.
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync Combines Permanent and Temporary.
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync name="StorageBus"
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync uuid="715984a5-093c-43bb-aa42-a16ed16828dd"
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync <desc>Interface bus type for storage devices.</desc>
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync <desc><tt>null</tt> value. Never used by the API.</desc>
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync name="ClipboardMode"
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync uuid="33364716-4008-4701-8f14-be0fa3d62950"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Host-Guest clipboard interchange mode.
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync name="Scope"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Scope of the operation.
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync A generic enumeration used in various methods to define the action or
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync argument scope.
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync name="GuestStatisticType"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync uuid="aa7c1d71-aafe-47a8-9608-27d2d337cf55"
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync Statistics type for <link to="IGuest::getStatistic"/>.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Idle CPU load (0-100%) for last interval.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Kernel CPU load (0-100%) for last interval.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync User CPU load (0-100%) for last interval.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Total number of threads in the system.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Total number of processes in the system.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Total number of handles in the system.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Memory load (0-100%).
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Total physical memory in megabytes.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Free physical memory in megabytes.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Ballooned physical memory in megabytes.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Total amount of memory in the committed state in megabytes.
374a0d34cb36711e4f767e3fcb67c4c032bb386cvboxsync Total amount of memory used by the guest OS's kernel in megabytes.
374a0d34cb36711e4f767e3fcb67c4c032bb386cvboxsync Total amount of paged memory used by the guest OS's kernel in megabytes.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Total amount of nonpaged memory used by the guest OS's kernel in megabytes.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Total amount of memory used by the guest OS's system cache in megabytes.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Pagefile size in megabytes.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Statistics sample number
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync name="BIOSBootMenuMode"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync BIOS boot menu mode.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync name="IDEControllerType"
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync uuid="445330e3-202a-4dab-854f-ce22e6cb9715"
374a0d34cb36711e4f767e3fcb67c4c032bb386cvboxsync IDE controller type.
374a0d34cb36711e4f767e3fcb67c4c032bb386cvboxsync <desc><tt>null</tt> value. Never used by the API.</desc>
374a0d34cb36711e4f767e3fcb67c4c032bb386cvboxsync name="DriveState"
374a0d34cb36711e4f767e3fcb67c4c032bb386cvboxsync uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <desc><tt>null</tt> value. Never used by the API.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync // IVirtualBoxErrorInfo
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync /////////////////////////////////////////////////////////////////////////
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync supportsErrorInfo="no"
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync wsmap="suppress"
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync The IVirtualBoxErrorInfo interface represents extended error information.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Extended error information can be set by VirtualBox components after
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync unsuccessful or partially successful method invocation. This information
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync can be retrievefd by the calling party as an IVirtualBoxErrorInfo object
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync and then shown to the client in addition to the plain 32-bit result code.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync In MS COM, this interface extends the IErrorInfo interface,
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync in XPCOM, it extends the nsIException interface. In both cases,
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync it provides a set of common attributes to retrieve error
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync information.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Sometimes invocation of some component's method may involve methods of
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync other components that may also fail (independently of this method's
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync failure), or a series of non-fatal errors may precede a fatal error that
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync causes method failure. In cases like that, it may be desirable to preserve
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync information about all errors happened during method invocation and deliver
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync it to the caller. The <link to="#next"/> attribute is intended
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync specifically for this purpose and allows to represent a chain of errors
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync through a single IVirtualBoxErrorInfo object set after method invocation.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Note that errors are stored to a chain in the reverse order, i.e. the
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync initial error object you query right after method invocation is the last
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync error set by the callee, the object it points to in the @a next attribute
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync is the previous error and so on, up to the first error (which is the last
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync in the chain).
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <attribute name="resultCode" type="result" readonly="yes">
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Result code of the error.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Usually, it will be the same as the result code returned
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync by the method that provided this error information, but not
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync always. For example, on Win32, CoCreateInstance() will most
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync likely return E_NOINTERFACE upon unsuccessful component
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync instantiation attempt, but not the value the component factory
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync In MS COM, there is no equivalent.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync In XPCOM, it is the same as nsIException::result.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync </attribute>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <attribute name="interfaceID" type="uuid" readonly="yes">
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync UUID of the interface that defined the error.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync In MS COM, it is the same as IErrorInfo::GetGUID.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync In XPCOM, there is no equivalent.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync </attribute>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <attribute name="component" type="wstring" readonly="yes">
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Name of the component that generated the error.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync In MS COM, it is the same as IErrorInfo::GetSource.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync In XPCOM, there is no equivalent.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync </attribute>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <attribute name="text" type="wstring" readonly="yes">
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Text description of the error.
374a0d34cb36711e4f767e3fcb67c4c032bb386cvboxsync In MS COM, it is the same as IErrorInfo::GetDescription.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync In XPCOM, it is the same as nsIException::message.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync </attribute>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Next error object if there is any, or @c null otherwise.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync In MS COM, there is no equivalent.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync In XPCOM, it is the same as nsIException::inner.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync </attribute>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync </interface>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync // IVirtualBox
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync /////////////////////////////////////////////////////////////////////////
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync uuid="ee95ffc2-b6c6-4ce8-9e9e-ceadbb5019fe"
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync wsmap="suppress"
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync The execution state of the given machine has changed.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>ID of the machine this event relates to.</desc>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Any of the settings of the given machine has changed.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <desc>ID of the machine this event relates to.</desc>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Notification when someone tries to change extra data for
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync either the given machine or (if null) global extra data.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync This gives the chance to veto against changes.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync ID of the machine this event relates to
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync (null ID for global extra data change requests).
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Extra data key for the attempted write.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Extra data value for the given key.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Optional error message describing the reason of the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync veto (ignored if this notification returns @c true).
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <param name="allowChange" type="boolean" dir="return">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Flag to indicate whether the callee agrees (@ true)
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync or vetoes against the change (@ false).
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Notification when machine specific or global extra data
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync has changed.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync ID of the machine this event relates to.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Null for global extra data changes.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Extra data key that has changed.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Extra data value for the given key.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The given media was registered or unregistered
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync within this VirtualBox installation.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The @a mediaType parameter describes what type of
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync media the specified @a mediaId refers to. Possible
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync values are:
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync - <link to="DeviceType::HardDisk"/>: the media is a hard disk
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync that, if registered, can be obtained using the
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync - <link to="DeviceType::DVD"/>: the media is a CD/DVD image
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync that, if registered, can be obtained using the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync - <link to="DeviceType::Floppy"/>: the media is a Floppy image
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync that, if registered, can be obtained using the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Note that if this is a deregistration notification,
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync there is no way to access the object representing the
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync unregistered media. It is supposed that the
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync application will do required cleanup based on the @a
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync mediaId value.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>ID of the media this event relates to.</desc>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <param name="mediaType" type="DeviceType" dir="in">
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <desc>Type of the media this event relates to.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync If true, the media was registered, otherwise it was
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync unregistered.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync The given machine was registered or unregistered
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync within this VirtualBox installation.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <desc>ID of the machine this event relates to.</desc>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync If true, the machine was registered, otherwise it was
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync unregistered.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The state of the session for the given machine was changed.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>ID of the machine this event relates to.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync A new snapshot of the machine has been taken.
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync <desc>ID of the machine this event relates to.</desc>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Snapshot of the given machine has been discarded.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync This notification is delivered <b>after</b> the snapshot
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync object has been uninitialized on the server (so that any
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync attempt to call its methods will return an error).
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <desc>ID of the machine this event relates to.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync ID of the discarded snapshot. <tt>null</tt> means the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync current machine state has been discarded (restored from
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync the current snapshot).
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Snapshot properties (name and/or description) have been changed.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>ID of the machine this event relates to.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync </interface>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync uuid="2d3b9ea7-25f5-4f07-a8e1-7dd7e0dcf667"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync wsmap="managed"
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync The IVirtualBox interface represents the main interface exposed by the
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync product that provides virtual machine management.
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync An instance of IVirtualBox is required for the product to do anything
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync useful. Even though the interface does not expose this, internally,
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync IVirtualBox is implemented as a singleton and actually lives in the
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync process of the VirtualBox server (VBoxSVC.exe). This makes sure that
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync IVirtualBox can track the state of all virtual machines on a particular
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync host, regardless of which frontend started them.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync To enumerate all the virtual machines on the host, use the
7cfcbe810de5334cdc2e8b92e77db705da143adavboxsync <attribute name="version" type="wstring" readonly="yes">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync A string representing the version number of the product. The
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync format is 3 integer numbers divided by dots (e.g. 1.0.1). The
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync last number represents the build number and will frequently change.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync </attribute>
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync <attribute name="packageType" type="wstring" readonly="yes">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync A string representing the package type of this product. The
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
3c9ed6defa3feca7e21adef4b5d1ba3002fc94c9vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="homeFolder" type="wstring" readonly="yes">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Full path to the directory where the global settings file,
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync In this version of VirtualBox, the value of this property is
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync always <tt><user_dir>/.VirtualBox</tt> (where
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync <tt><user_dir></tt> is the path to the user directory,
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync as determined by the host OS), and cannot be changed.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync This path is also used as the base to resolve relative paths in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync places where relative paths are allowed (unless otherwise
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync expressly indicated).
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <attribute name="settingsFilePath" type="wstring" readonly="yes">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Full name of the global settings file.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The value of this property corresponds to the value of
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="settingsFileVersion" type="wstring" readonly="yes">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Current version of the format of the global VirtualBox settings file
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The version string has the following format:
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync where <tt>x</tt> and <tt>y</tt> are the major and the minor format
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync versions, and <tt>platform</tt> is the platform identifier.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The current version usually matches the value of the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <link to="#settingsFormatVersion"/> attribute unless the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync settings file was created by an older version of VirtualBox and there
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync was a change of the settings file format since then.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Note that VirtualBox automatically converts settings files from older
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync versions to the most recent version when reading them (usually at
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync VirtualBox startup) but it doesn't save the changes back until
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync you call a method that implicitly saves settings (such as
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync explicitly. Therefore, if the value of this attribute differs from the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync value of <link to="#settingsFormatVersion"/>, then it
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync means that the settings file was converted but the result of the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync conversion is not yet saved to disk.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync The above feature may be used by interactive front-ends to inform users
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync about the settings file format change and offer them to explicitly save
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync all converted settings files (the global and VM-specific ones),
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync optionally create bacup copies of the old settings files before saving,
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <see>settingsFormatVersion, saveSettingsWithBackup()</see>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </attribute>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <attribute name="settingsFormatVersion" type="wstring" readonly="yes">
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Most recent version of the settings file format.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync The version string has the following format:
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync where <tt>x</tt> and <tt>y</tt> are the major and the minor format
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync versions, and <tt>platform</tt> is the platform identifier.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync VirtualBox uses this version of the format when saving settings files
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync (either as a result of method calls that require to save settings or as
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync a result of an explicit call to <link to="#saveSettings()"/>).
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </attribute>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <attribute name="host" type="IHost" readonly="yes">
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync </attribute>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </attribute>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <attribute name="machines" type="IMachineCollection" readonly="yes">
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync Collection of machine objects registered within this VirtualBox
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </attribute>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <attribute name="machines2" type="IMachine" readonly="yes" safearray="yes">
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync Array of machine objects registered within this VirtualBox instance.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </attribute>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <attribute name="hardDisks" type="IHardDiskCollection" readonly="yes">
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync Collection of hard disk objects registered within this VirtualBox
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync This collection contains only "top-level" (basic or independent) hard
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync disk images, but not differencing ones. All differencing images of the
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync given top-level image (i.e. all its children) can be enumerated using
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </attribute>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <attribute name="DVDImages" type="IDVDImageCollection" readonly="yes"/>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <attribute name="FloppyImages" type="IFloppyImageCollection" readonly="yes"/>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <attribute name="progressOperations" type="IProgressCollection" readonly="yes"/>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <attribute name="guestOSTypes" type="IGuestOSTypeCollection" readonly="yes"/>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync Collection of global shared folders. Global shared folders are
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync available to all virtual machines.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync New shared folders are added to the collection using
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <link to="#createSharedFolder"/>. Existing shared folders can be
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync In the current version of the product, global shared folders are not
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync implemented and therefore this collection is always empty.
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync </attribute>
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync Creates a new virtual machine.
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync The new machine will have "empty" default settings and will not
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync yet be registered. The typical sequence to create a virtual machine
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync is therefore something like this:
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <li>Call this method (IVirtualBox::createMachine) to have a new
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync machine created. The machine object returned is "mutable", i.e.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync automatically locked for the current session, as if
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <link to="#openSession" /> had been called on it.</li>
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <li>Assign meaningful settings to the new machine by calling the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync respective methods.</li>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <li>Call <link to="IMachine::saveSettings" /> to have the settings written
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync to the machine's XML settings file. The configuration of the newly
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync created machine will not be saved to disk (and the settings subfolder
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync and file, as described below, will not be created) until this method
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync is called.</li>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <li>Call <link to="#registerMachine" /> to have the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync machine show up in the list of machines registered with VirtualBox.</li>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync Every machine has a <i>settings file</i> that is used to store
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync the machine configuration. This file is stored in the directory
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync called <i>machine settings subfolder</i>. Unless specified otherwise,
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync both the subfolder and the settings file will have a name that
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync corresponds to the name of the virtual machine. You can specify
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync where to create the machine settings subfolder using the @a
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync baseFolder argument. The base folder can be absolute (full path)
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync or relative to the <link to="IVirtualBox::homeFolder">
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync VirtualBox home directory</link>.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync If a null or empty string is given as the base folder (which is
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync recommended), the <link to="ISystemProperties::defaultMachineFolder">
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync default machine settings folder</link> will be used as the base
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync folder to create the machine settings subfolder and file. In
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync any case, the full path to the settings file will look like:
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <base_folder>/<machine_name>/<machine_name>.xml
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync Optionally the UUID of the machine can be predefined. If this is
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync not desired (i.e. a new UUID should be generated), pass just an
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync empty or null UUID.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync You should also specify a valid name for the machine.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync description for more details about the machine name.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync The created machine remains
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync unregistered until you call <link to="#registerMachine()"/>.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync There is no way to change the name of the settings file or
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync subfolder of the created machine directly.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Name of the folder where to create the machine settings
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync subfolder containing the settings file.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync UUID of the newly created VM, when non-null or non-empty.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Otherwise a UUID is automatically generated.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <param name="machine" type="IMachine" dir="return">
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Creates a new virtual machine in "legacy" mode, using the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync specified settings file to store machine settings.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync As opposed to machines created by <link to="#createMachine()"/>,
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync the settings file of the machine created in "legacy" mode
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync is not automatically renamed when the machine name is
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync changed -- it will always remain the same as specified in this
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync method call.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync The specified settings file name can be absolute
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync (full path) or relative to the <link to="IVirtualBox::homeFolder">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox home directory</link>. If the file name doesn't
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync contain an extension, the default extension (.xml) will be
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Optionally the UUID of the machine can be predefined. If this is
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync not desired (i.e. a new UUID should be generated), pass just an
c9a593aa048a154e59b52d1237d89e3cdaee9b3dvboxsync empty or null UUID.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Note that the configuration of the newly created machine is not
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync saved to disk (and therefore no settings file is created)
c9a593aa048a154e59b52d1237d89e3cdaee9b3dvboxsync until <link to="IMachine::saveSettings()"/> is called. If the
c9a593aa048a154e59b52d1237d89e3cdaee9b3dvboxsync specified settings file already exists,
c9a593aa048a154e59b52d1237d89e3cdaee9b3dvboxsync <link to="IMachine::saveSettings()"/> will return an error.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync You should also specify a valid name for the machine.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync description for more details about the machine name.
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync The created machine remains
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync unregistered until you call <link to="#registerMachine()"/>.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync @deprecated This method may be removed later. It is better
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync There is no way to change the name of the settings file
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync of the created machine.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <param name="settingsFile" type="wstring" dir="in">
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync Name of the file where to store machine settings.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync UUID of the newly created VM, when non-null or non-empty.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Otherwise a UUID is automatically generated.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <param name="machine" type="IMachine" dir="return">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Opens a virtual machine from the existing settings file.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync The opened machine remains unregistered until you call
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The specified settings file name can be absolute
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync (full path) or relative to the <link to="IVirtualBox::homeFolder">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox home directory</link>. This file must exist
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync and must be a valid machine settings file whose contents
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync will be used to construct the machine object.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync @deprecated Will be removed soon.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <param name="settingsFile" type="wstring" dir="in">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Name of the machine settings file.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <param name="machine" type="IMachine" dir="return">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="IMachine::settingsModified"/> will return
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync false for the created machine, until any of machine settigs
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync are changed.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Registers the machine previously created using
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <link to="#openMachine()"/> within this VirtualBox installation. After
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync successful method invocation, the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to all registered callbacks.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync This method implicitly calls <link to="IMachine::saveSettings"/>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to save all current machine settings before registering it.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Attempts to find a virtual machine given its UUID.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync To look up a machine by name, use <link to="IVirtualBox::findMachine" /> instead.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <param name="machine" type="IMachine" dir="return"/>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Attempts to find a virtual machine given its name.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync To look up a machine by UUID, use <link to="IVirtualBox::getMachine" /> instead.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <param name="machine" type="IMachine" dir="return"/>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Unregisters the machine previously registered using
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="#registerMachine"/>. After successful method invocation, the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to all registered callbacks.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The specified machine must not be in the Saved state, have an open
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync (or a spawning) direct session associated with it, have snapshots or
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync have hard disks attached.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync This method implicitly calls <link to="IMachine::saveSettings"/> to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync save all current machine settings before unregistering it.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync If the given machine is inaccessible (see
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="IMachine::accessible"/>), it will be unregistered and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync fully uninitialized right afterwards. As a result, the returned
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync machine object will be unusable and an attempt to call
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <b>any</b> method will return the "Object not ready" error.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <param name="machine" type="IMachine" dir="return">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Creates a new unregistered hard disk that will use the given
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync storage type.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Most properties of the created hard disk object are
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync uninitialized. Valid values must be assigned to them (and probalby
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync some actions performed) to make the actual usage of this hard disk
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync (<link to="#registerHardDisk()">register</link>, attach to a virtual
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync machine, etc.). See the description of <link to="IHardDisk"/> and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync descriptions of storage type specific interfaces for more information.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync For hard disks using
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to="HardDiskStorageType::VirtualDiskImage">VirtualDiskImage</link>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync storage type, an image file is not actually created until you call
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <link to="IVirtualDiskImage::createDynamicImage()"/> or
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="IVirtualDiskImage::createFixedImage()"/>.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <param name="storageType" type="HardDiskStorageType" dir="in">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>Storage type of the hard disk image to create.</desc>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <param name="hardDisk" type="IHardDisk" dir="return">
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync <desc>Created hard disk object of the given storage type.</desc>
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync Opens a hard disk from an existing location.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync This method tries to guess the
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <link to="HardDiskStorageType">hard disk storage type</link> from the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync format of the location string and from the contents of the resource the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync location points to. Currently, a <i>file path</i> is the only
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync supported format for the location string which must point to either a
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VDI file or to a VMDK file. On success, an IHardDisk object will be
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync returned that also implements the corresponding interface
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync (IVirtualDiskImage or IVMDKImage, respectively). The
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <link to="IHardDisk::storageType"/> property may also be used to
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync determine the storage type of the returned object (instead of trying
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync to query one of these interfaces).
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The specified file path can be absolute (full path) or relative to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the <link to="IVirtualBox::homeFolder">VirtualBox home
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync directory</link>. If only a file name without any path is given,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the <link to="ISystemProperties::defaultVDIFolder"> default VDI
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync folder</link> will be used as a path to the image file.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The opened hard disk remains unregistered
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Location of the resource that contains a valid hard disk.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <param name="hardDisk" type="IHardDisk" dir="return">
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync Opens a hard disk from an existing Virtual Disk Image file.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The opened hard disk remains unregistered
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync @deprecated Use <link to="IVirtualBox::openHardDisk()"/> instead.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <note>Opening differencing images is not supported.</note>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <note>The specified file path can be absolute (full path) or
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync home directory</link>. If only a file name without any path is
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync given, the <link to="ISystemProperties::defaultVDIFolder">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync default VDI folder</link> will be used as a path to the image
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync file.</note>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Name of the file that contains a valid Virtual Disk Image.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <param name="image" type="IVirtualDiskImage" dir="return">
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Registers the given hard disk within this VirtualBox
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync installation. The hard disk must not be registered, must be
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync <link to="IHardDisk::accessible"/> and must not be a
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync differencing hard disk, otherwise the registration will fail.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Returns the registered hard disk with the given UUID.
3c9ed6defa3feca7e21adef4b5d1ba3002fc94c9vboxsync <param name="hardDisk" type="IHardDisk" dir="return">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Returns a registered hard disk that uses the given location to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync store data. The search is done by comparing the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync value of the @a location argument to the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="IHardDisk::location"/> attribute of each registered
3c9ed6defa3feca7e21adef4b5d1ba3002fc94c9vboxsync For locations repesented by file paths (such as VDI and VMDK
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync images), the specified location can be either an absolute file
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync path or a path relative to
01df41f7a4e5f7de195a059541d1c89676da9673vboxsync the <link to="IVirtualBox::homeFolder"> VirtualBox home
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync directory</link>. If only a file name without any path is
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync given, the <link to="ISystemProperties::defaultVDIFolder">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync default VDI folder</link> will be used as a path to construct
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the absolute image file name to search for. Note that on host
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync systems with case sensitive filesystems, a case sensitive
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync comparison is performed, otherwise the case of symbols in the
3c9ed6defa3feca7e21adef4b5d1ba3002fc94c9vboxsync file path is ignored.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <desc>Hard disk location specification to search for.</desc>
3c9ed6defa3feca7e21adef4b5d1ba3002fc94c9vboxsync <param name="hardDisk" type="IHardDisk" dir="return">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Returns a registered hard disk that uses the given image file.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync @deprecated Use <link to="IVirtualBox::findHardDisk()"/> instead.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <note>The specified file path can be absolute (full path) or
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync home directory</link>. If only a file name without any path is
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync given, the <link to="ISystemProperties::defaultVDIFolder">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync default VDI folder</link> will be used as a path to the image
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync file.</note>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <note>On host systems with case sensitive filesystems, a case
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync sensitive comparison is performed, otherwise the case of symbols
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync in the file path is ignored.</note>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>Virtual Disk Image file path to look for.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <param name="image" type="IVirtualDiskImage" dir="return">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Unregisters a hard disk previously registered using
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync The specified hard disk must not be attached to any of
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the existing virtual machines and must not have children
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync (differencing) hard disks.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <param name="hardDisk" type="IHardDisk" dir="return">
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync Opens the CD/DVD image contained in the specified file of
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync the supported format and assigns it the given UUID. The opened
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync image remains unregistered
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Full name of the file that contains a valid
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync CD/DVD image. Currently, only ISO images are supported.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The specified file name can be absolute or relative
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync VirtualBox home directory</link>.
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync UUID to assign to the given image file within this
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync VirtualBox installation. If an empty (null) UUID is
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync specified, the system will randomly generate an UUID.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync installation. The image must not be registered and must not
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync be associated with the same image file as any of the already
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync registered images, otherwise the registration will fail.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Returns a registered CD/DVD image with the given UUID.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync Returns a registered CD/DVD image with the given image file.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync On host systems with case sensitive filesystems, a case
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync sensitive comparison is performed, otherwise the case of
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync symbols in the file path is ignored.
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync Returns the list of of UUIDs of all virtual machines that use
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <desc>UUID of the image to get the usage information for.</desc>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <desc>Type of the usage (permanent, temporary or all).</desc>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <param name="machineIDs" type="wstring" dir="return">
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync List of UUIDs of all machines that use the given image
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync in the way specified by the usage parameter.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync The list is returned as a string containing UUIDs separated
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync by spaces. A null string means that the image is not used.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync When the usage type is <link to="ResourceUsage::All"/> and the image
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync is used by the VM both permanently and temporarily, the VM's UUID
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync will be present only once in the list.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Unregisters the CD/DVD image previously registered using
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync The specified image must not be mounted to any of
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync the existing virtual machines.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <desc>UUID of the CD/DVD image to unregister.</desc>
6f1977ffd39bde1977845dd91fb8c8027eeb247evboxsync Opens a floppy image contained in the specified file of
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the supported format and assigns it the given UUID. The opened
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync image remains unregistered
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync until <link to="#registerFloppyImage()"/> is called.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Full name of the file that contains a valid
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync floppy image.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync The specified file name can be absolute or relative
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync VirtualBox home directory</link>.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync UUID to assign to the given image file within this
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox installation. If an empty (null) UUID is
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync specified, the system will randomly generate an UUID.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <param name="image" type="IFloppyImage" dir="return">
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Registers a floppy image within this VirtualBox
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync installation. The image must not be registered and must not
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync be associated with the same image file as any of the already
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync registered images, otherwise the registration will fail.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Returns a registered floppy image with the given UUID.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <param name="image" type="IFloppyImage" dir="return">
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync Returns a registered floppy image with the given image file.
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync On host systems with case sensitive filesystems, a case
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync sensitive comparison is performed, otherwise the case of
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync symbols in the file path is ignored.
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync <param name="image" type="IFloppyImage" dir="return">
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync Returns the list of of UUIDs of all virtual machines that use
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync the given floppy image.
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync <desc>UUID of the image to get the usage information for.</desc>
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync <desc>Type of the usage (permanent, temporary or all).</desc>
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync <param name="machineIDs" type="wstring" dir="return">
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync List of UUIDs of all machines that use the given image
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync in the way specified by the usage parameter.
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync The list is returned as a string containing UUIDs separated
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync by spaces. A null string means that the image is not used.
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync When the usage type is <link to="ResourceUsage::All"/> and the image
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync is used by the VM both permanently and temporarily, the VM's UUID
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync will be present only once in the list.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Unregisters the floppy image previously registered using
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync The specified image must not be mounted to any of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the existing virtual machines.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <desc>UUID of the floppy image to unregister.</desc>
cb445170c831c6c56d2d82261e9193b66ceb98a7vboxsync <param name="image" type="IFloppyImage" dir="return">
cb445170c831c6c56d2d82261e9193b66ceb98a7vboxsync <param name="type" type="IGuestOSType" dir="return"/>
cb445170c831c6c56d2d82261e9193b66ceb98a7vboxsync Creates a new global shared folder by associating the given logical
cb445170c831c6c56d2d82261e9193b66ceb98a7vboxsync name with the given host path, adds it to the collection of shared
cb445170c831c6c56d2d82261e9193b66ceb98a7vboxsync folders and starts sharing it. Refer to the description of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <link to="ISharedFolder"/> to read more about logical names.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <desc>Unique logical name of the shared folder.</desc>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <desc>Full path to the shared folder in the host file system.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>Whether the share is writable or readonly</desc>
cb445170c831c6c56d2d82261e9193b66ceb98a7vboxsync Removes the global shared folder with the given name previously
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync created by <link to="#createSharedFolder"/> from the collection of
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync shared folders and stops sharing it.
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync <desc>Logical name of the shared folder to remove.</desc>
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync Returns the global extra data key name following the supplied key.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync An error is returned if the supplied @a key does not exist. @c NULL is
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync returned in @a nextKey if the supplied key is the last key. When
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync supplying @c NULL for the @a key, the first key item is returned in @a
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync nextKey (if there is any). @a nextValue is an optional parameter and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync if supplied, the next key's value is returned in it.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Returns associated global extra data.
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync If the requested data @a key does not exist, this function will
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync succeed and return @c NULL in the @a value argument.
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync Sets associated global extra data.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync If you pass @c NULL as a key @a value, the given @a key will be
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync Before performing the actual data change, this method will ask all
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync registered callbacks using the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <link to="IVirtualBoxCallback::onExtraDataCanChange()"/>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync notification for a permission. If one of the callbacks refuses the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync new value, the change will not be performed.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync On success, the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <link to="IVirtualBoxCallback::onExtraDataChange()"/> notification
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync is called to inform all registered callbacks about a successful data
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync Opens a new direct session with the given virtual machine.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Within the direct session context, it is possible to change
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync all VM settings, as well as to execute the VM in the process
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync space of the session object. There can be only one direct
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync session open at a time for every virtual machine. In VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync terminology, the machine becomes "mutable" after a session has
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync been opened.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Upon successful return, the session object can be used to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync get access to the machine and to the VM console.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Note that the "mutable" machine object, on which you may want
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to invoke IMachine methods to change its settings, will be a
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync different object from the immutable IMachine objects returned
129986ce8b48d5e5973ad84edae4465788db89aavboxsync by various IVirtualBox methods. To obtain a mutable
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync IMachine object, upon which you can invoke settings methods,
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync use the "machine" attribute of the ISession object which represents
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync your open session.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync In other words, to change settings on a machine, the following
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync sequence is typically performed:
7cfcbe810de5334cdc2e8b92e77db705da143adavboxsync <li>Call this method (openSession) to have a machine locked for
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync the current session.</li>
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync <li>Obtain a mutable IMachine object from ISession::machine.</li>
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync <li>Close the session by calling <link to="#close" />.</li>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Session object that will represent the opened session after
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync successful method invocation. This object must not represent
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the already open session.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync This session will be automatically closed if the
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync VirtualBox server is terminated for some reason.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <desc>ID of the virtual machine to open a session with.</desc>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Opens a new remote session with the given virtual machine.
7cfcbe810de5334cdc2e8b92e77db705da143adavboxsync Opening a remote session causes the VirtualBox server to start a new
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync process that opens a direct session with the given VM. The remote
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync session provides some level of control over the VM execution to the
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync caller (using the IConsole interface); however, within the remote
7cfcbe810de5334cdc2e8b92e77db705da143adavboxsync session context, not all VM settings are available for modification.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync This operation can take some time (a new VM is started in a new process,
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync for which memory and other resources need to be set up, which can take
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync a few seconds). Because of this, a progress object is returned to allow the
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync caller to wait for this asynchronous operation to be completed. Until then,
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the remote session object remains in the closed state and accessing the
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync machine or its console through it is invalid. It is recommended to use
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <link to="IProgress::waitForCompletion" /> or similar calls to wait for
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync completion.
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync Currently supported session types (values of the @a type
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync argument) are:
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The @a environment argument is a string containing definitions of
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync environment variables in the following format:
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync NAME[=VALUE]\n
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync NAME[=VALUE]\n
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync where <tt>\\n</tt> is the new line character. These environment
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync variables will be appended to the environment of the VirtualBox server
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync process. If an environment variable exists both in the server process
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync and in this list, the value from this list takes precedence over the
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync server's variable. If the value of the environment variable is
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync omitted, this variable will be removed from the resulting environment.
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync If the environment string is @c null, the server environment is
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync inherited by the started process as is.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync It is an error to open a remote session with the machine
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync that already has an open direct session or waits until the
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync previous request to open the remote session is completed
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The opened @a session will be automatically closed when
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync the corresponding direct session dies or gets closed.
7cfcbe810de5334cdc2e8b92e77db705da143adavboxsync Session object that will represent the opened remote session
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync after successful method invocation (this object must not
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync represent an already open session).
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <desc>ID of the virtual machine to open a session with.</desc>
4d0b7e3cba16e39e96db76fdf56abea555187ba6vboxsync Type of the remote session (case sensitive).
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Environment to pass to the opened session (may be @c null).
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <param name="progress" type="IProgress" dir="return">
4d0b7e3cba16e39e96db76fdf56abea555187ba6vboxsync <desc>Progress object to track the operation completion.</desc>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Opens a new remote session with the virtual machine for
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync which a direct session is already open.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The remote session provides some level of control over the VM
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync execution (using the IConsole interface) to the caller; however,
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync within the remote session context, not all VM settings are available
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync for modification.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync As opposed to <link to="#openRemoteSession()"/>, the number of
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync remote sessions opened this way is not limited by the API
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync It is an error to open a remote session with the machine that
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync doesn't have an open direct session.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Session object that will represent the open remote session
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync after successful method invocation. This object must not
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync represent an already open session.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync This session will be automatically closed when the peer
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync (direct) session dies or gets closed.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <desc>ID of the virtual machine to open a session with.</desc>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Registers a new global VirtualBox callback. The methods of the given
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync callback object will be called by VirtualBox when an appropriate
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync event occurs.
4d0b7e3cba16e39e96db76fdf56abea555187ba6vboxsync <param name="callback" type="IVirtualBoxCallback" dir="in">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Unregisters the previously registered global VirtualBox callback.
e2a74585316778e8df03715924c81e4f32292f5evboxsync <param name="callback" type="IVirtualBoxCallback" dir="in">
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync Blocks the caller until any of the properties represented by the @a
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync what argument changes the value or until the given timeout interval
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync The @a what argument is a comma separated list of propertiy masks that
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync describe properties the caller is interested in. The property mask is
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync a string in the following format:
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync [[group.]subgroup.]name
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync where @c name is the property name and @c group, @c subgroup are zero
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync or or more property group specifiers. Each element (group or name) in
e2a74585316778e8df03715924c81e4f32292f5evboxsync the property mask may be either a latin string or an asterisk symbol
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync (@c "*") which is used to match any string for the given element. A
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync property mask that doesn't contain asterisk symbols represents a
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync single fully qualified property name.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Groups in the fully qualified property name go from more generic (the
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync left-most part) to more specific (the right-most part). The first
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync element is usually a name of the object the property belongs to. The
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync second element may be either a property name, or a child object name,
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync or an index if the preceeding element names an object which is one of
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync many objects of the same type. This way, property names form a
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync hierarchy of properties. Here are some examples of property names:
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <td><link to="IVirtualBox::version"/> property</td>
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync <td><link to="IMachine::name"/> property of the machine with the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync given UUID</td>
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync Most property names directly correspond to the properties of objects
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync (components) provided by the VirtualBox library and may be used to
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync track changes to these properties. However, there may be
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync pseudo-property names that don't correspond to any existing object's
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync property directly, as well as there may be object properties that
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync don't have a corresponding property name that is understood by this
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync method, and therefore changes to such properties cannot be
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync tracked. See individual object's property descrcriptions to get a
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync fully qualified property name that can be used with this method (if
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync There is a special property mask @c "*" (i.e. a string consisting of a
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync single asterisk symbol) that can be used to match all properties.
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync Below are more examples of property masks:
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync <td>Track all properties of the VirtualBox object</td>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <td>Track changes to the <link to="IMachine::name"/> property of
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync all registered virtual machines</td>
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync <desc>Comma separated list of property masks.</desc>
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync <param name="timeout" type="unsigned long" dir="in">
61bb42c2bd859f319e792927ad98a97c5826756avboxsync Wait timeout in milliseconds.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Specify -1 for an indefinite wait.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Comma separated list of properties that have been changed and caused
ab8158da86979881efcdda8d21b96cee145e61ebvboxsync this method to return to the caller.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Saves the global settings to the global settings file
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync This method is only useful for explicitly saving the global settings
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync file after it has been auto-converted from the old format to the most
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync recent format (see <link to="#settingsFileVersion"/> for details).
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Normally, the global settings file is implicitly saved when a global
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync setting is changed.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Creates a backup copy of the global settings file
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync (<link to="#settingsFilePath"/>) in case of auto-conversion, and then
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync Note that the backup copy is created <b>only</b> if the settings file
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync auto-conversion took place (see <link to="#settingsFileVersion"/> for
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync details). Otherwise, this call is fully equivalent to
3a45119099f0df5230e8304145168aa5e2a3f1a1vboxsync <link to="#saveSettings()"/> and no backup copying is done.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The backup copy is created in the same directory where the original
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync settings file is located. It is given the following file name:
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync where <tt>original.xml</tt> is the original settings file name
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync (excluding path), and <tt>x.y-platform</tt> is the version of the old
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync format of the settings file (before auto-conversion).
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync If the given backup file already exists, this method will try to add the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync 0 to 9) and copy it again until it succeeds. If all suffixes are
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync occupied, or if any other copy error occurs, this method will return a
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync If the copy operation succeeds, the @a bakFileName return argument will
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync receive a full path to the created backup file (for informational
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync purposes). Note that this will happen even if the subsequent
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <link to="#saveSettings()"/> call performed by this method after the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync copy operation, fails.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The VirtualBox API never calls this method. It is intended purely for
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync the purposes of creating backup copies of the settings files by
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync front-ends before saving the results of the automatically performed
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync settings conversion to disk.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <param name="bakFileName" type="wstring" dir="return">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </interface>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync // IMachine
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync /////////////////////////////////////////////////////////////////////////
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync <enumerator
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync uuid="1b554149-be0a-4465-9252-9ff8f420af55"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <collection
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync name="IMachineCollection" type="IMachine" enumerator="IMachineEnumerator"
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync uuid="FD443EC1-3007-4F5B-9282-D72760A66916"
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync readonly="yes"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync uuid="1063893c-4c38-4304-aee9-73e072c181cc"
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync internal="yes"
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync wsmap="suppress"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Updates the VM state.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync This operation will also update the settings file with
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the correct information about the saved state file
8f0f3548de344cfe3e49ffd3e4c338792e1729cevboxsync and delete this file from disk when appropriate.
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync Asks the server to run USB devices filters of the associated
a8d502445ce722c6b9700c5579b4a38b58827b7dvboxsync machine against the given USB device and tell if there is
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Intended to be used only for remote USB devices. Local
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync ones don't require to call this method (this is done
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync implicitly by the Host and USBProxyService).
8cfe2efff2058bd07777056112155ea5353dcfbavboxsync <param name="maskedInterfaces" type="unsigned long" dir="out"/>
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync Requests a capture of the given host USB device.
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync When the request is completed, the VM process will
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync notification.
01df41f7a4e5f7de195a059541d1c89676da9673vboxsync Notification that a VM is going to detach (done = false) or has
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync already detached (done = true) the given USB device.
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync When the done = true request is completed, the VM process will
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync notification.
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync In the done = true case, the server must run its own filters
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync and filters of all VMs but this one on the detached device
01df41f7a4e5f7de195a059541d1c89676da9673vboxsync as if it were just attached to the host computer.
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync Requests a capture all matching USB devices attached to the host.
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync When the request is completed, the VM process will
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync notification per every captured device.
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync Notification that a VM that is being powered down. The done
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync parameter indicates whether which stage of the power down
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync we're at. When done = false the VM is announcing its
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync intentions, while when done = true the VM is reporting
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync what it has done.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync In the done = true case, the server must run its own filters
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync and filters of all VMs but this one on all detach devices as
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync if they were just attached to the host computer.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Triggered by the given session object when the session is about
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync to close normally.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <param name="progress" type="IProgress" dir="return">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Used to wait until the corresponding machine is actually
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync deassociated from the given session on the server.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Returned only when this session is a direct one.
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync Called by the VM process to inform the server it wants to
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync save the current state and stop the VM execution.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Progress object created by the VM process to wait until
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync the state is saved.
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync <param name="stateFilePath" type="wstring" dir="out">
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync File path the VM process must save the execution state to.
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync Called by the VM process to inform the server that saving
01df41f7a4e5f7de195a059541d1c89676da9673vboxsync the state previously requested by #beginSavingState is either
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync successfully finished or there was a failure.
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Gets called by IConsole::adoptSavedState.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <param name="savedStateFile" type="wstring" dir="in">
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <desc>Path to the saved state file to adopt.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Called by the VM process to inform the server it wants to
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync take a snapshot.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>The console object that initiated this call.</desc>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Progress object created by the VM process to wait until
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the state is saved (only for online snapshots).
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <param name="stateFilePath" type="wstring" dir="out">
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync File path the VM process must save the execution state to.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <param name="serverProgress" type="IProgress" dir="out">
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Progress object created by the server process to wait until
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the snapshot is taken (VDI diff creation, etc.).
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Called by the VM process to inform the server that the snapshot
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync previously requested by #beginTakingSnapshot is either
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync successfully taken or there was a failure.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync Gets called by IConsole::discardSnapshot.
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync <desc>The console object that initiated this call.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <param name="machineState" type="MachineState" dir="out">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>New machine state after this operation is started.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <param name="progress" type="IProgress" dir="return">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>Progress object to track the operation completion.</desc>
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync Gets called by IConsole::discardCurrentState.
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync <desc>The console object that initiated this call.</desc>
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync <param name="machineState" type="MachineState" dir="out">
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync <desc>New machine state after this operation is started.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <param name="progress" type="IProgress" dir="return">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>Progress object to track the operation completion.</desc>
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync Gets called by IConsole::discardCurrentSnapshotAndState.
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <desc>The console object that initiated this call.</desc>
01df41f7a4e5f7de195a059541d1c89676da9673vboxsync <param name="machineState" type="MachineState" dir="out">
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync <desc>New machine state after this operation is started.</desc>
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync <param name="progress" type="IProgress" dir="return">
8cb6f31c3048428b42c7370dfbb20e4de7254f40vboxsync <desc>Progress object to track the operation completion.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync </interface>
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync wsmap="struct"
2f4c1bacd54af5063c3185cc8eab03e4e8ef9b90vboxsync The IBIOSSettings interface represents BIOS settings of the virtual
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <note>With the COM API, this is an interface like all the others. With the webservice,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync this is mapped to a structure, so querying the attribute will not return an object,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync but a complete structure.</note>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </attribute>
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync <desc>Fade out flag for BIOS logo animation.</desc>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </attribute>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <attribute name="logoDisplayTime" type="unsigned long">
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <desc>BIOS logo display time in milliseconds (0 = default).</desc>
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync </attribute>
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync <desc>Local file system path for external BIOS image.</desc>
8d1da51eb6665874aa82bf03668e03d1a0d63223vboxsync </attribute>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <attribute name="bootMenuMode" type="BIOSBootMenuMode">
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </attribute>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync IO APIC support flag. If set, VirtualBox will provide an IO APIC
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync and support IRQs above 15.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Offset in milliseconds from the host system time. This allows for
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync guests running with a different system date/time than the host.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync It is equivalent to setting the system date/time in the BIOS other
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync than it's not an absolute value but a relative one. Guest Additions
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync time synchronization also honors this offset.
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync </attribute>
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync PXE debug logging flag. If set, VirtualBox will write extensive
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync PXE trace information to the release log.
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="IDEControllerType" type="IDEControllerType">
77db08a24f69bca943d5abc40b1930ee97f593edvboxsync Type of the virtual IDE controller. Depending on this value,
77db08a24f69bca943d5abc40b1930ee97f593edvboxsync VirtualBox will provide different virtual IDE hardware
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync devices to the guest.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </attribute>
d862f0eeb9eacdb46b9f5cc420de30a3d7c2c3f6vboxsync </interface>
d862f0eeb9eacdb46b9f5cc420de30a3d7c2c3f6vboxsync uuid="d6181581-e7c7-418a-b3b6-2da10b11a763"
d862f0eeb9eacdb46b9f5cc420de30a3d7c2c3f6vboxsync wsmap="managed"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The IMachine interface represents a virtual machine, or guest, created
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync in VirtualBox.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync This interface is used in two contexts. First of all, a collection of
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync objects implementing this interface is stored in the
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <link to="IVirtualBox::machines"/> attribute which lists all the virtual
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync machines that are currently registered with this VirtualBox
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync installation. Also, once a session has been opened for the given virtual
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync machine (e.g. the virtual machine is running), the machine object
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync associated with the open session can be queried from the session object;
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync The main role of this interface is to expose the settings of the virtual
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync machine and provide methods to change various aspects of the virtual
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync machine's configuration. For machine objects stored in the
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <link to="IVirtualBox::machines"/> collection, all attributes are
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync read-only unless explicitely stated otherwise in individual attribute
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync and method descriptions. In order to change a machine setting, a session
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync for this machine must be opened using one of
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <link to="IVirtualBox::openExistingSession"/> methdods. After the
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync session has been successfully opened, a mutable machine object needs to
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync be queried from the session object and then the desired settings changes
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync can be applied to the returned object using IMachine attributes and
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync methods. See the ISession interface description for more information
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync about sessions.
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync Note that the IMachine interface does not provide methods to control
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync virtual machine execution (such as start the machine, or power it
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync down) -- these methods are grouped in a separate IConsole
9161d9a8318db73b2848c1feaef3880980474e64vboxsync interface. Refer to the IConsole interface description to get more
9161d9a8318db73b2848c1feaef3880980474e64vboxsync information about this topic.
9161d9a8318db73b2848c1feaef3880980474e64vboxsync <attribute name="parent" type="IVirtualBox" readonly="yes">
9161d9a8318db73b2848c1feaef3880980474e64vboxsync </attribute>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync <attribute name="accessible" type="boolean" readonly="yes">
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Whether this virtual machine is currently accessible or not.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync The machine is considered to be inaccessible when:
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <li>It is a registered virtual machine, and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <li>Its settings file is inaccessible (for example, it is
9161d9a8318db73b2848c1feaef3880980474e64vboxsync located on a network share that is not accessible during
9161d9a8318db73b2848c1feaef3880980474e64vboxsync VirtualBox startup, or becomes inaccessible later, or if
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the settings file can be read but is invalid).
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync Otherwise, the value of this property is always <tt>true</tt>.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Every time this property is read, the accessibility state of
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync this machine is re-evaluated. If the returned value is |false|,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the <link to="#accessError"/> property may be used to get the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync detailed error information describing the reason of
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync inaccessibility.
ad1aea7f006b1feaea275f858b5b574ae61bfe39vboxsync When the machine is inaccessible, only the following properties
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync can be used on it:
529e6bec97f5ef2e005c99c205c9624583ecb7f0vboxsync An attempt to access any other property or method will return
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The only possible action you can perform on an inaccessible
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync machine is to unregister it using the
ae2a9b93d772d52146af2c010701ead81e4fb348vboxsync <link to="IVirtualBox::unregisterMachine"/> call (or, to check
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync for the accessibility state once more by querying this
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync In the current implementation, once this property returns
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync <tt>true</tt>, the machine will never become inaccessible
7c19e11502220292d5270519296442234c2493cdvboxsync later, even if its settings file cannot be successfully
7c19e11502220292d5270519296442234c2493cdvboxsync read/written any more (at least, until the VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync server is restarted). This limitation may be removed in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync future releases.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Error information describing the reason of machine
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync inaccessibility.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Reading this property is only valid after the last call to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="#accessible"/> returned <tt>false</tt> (i.e. the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync machine is currently unaccessible). Otherwise, a null
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync IVirtualBoxErrorInfo object will be returned.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Name of the virtual machine.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Besides being used for human-readable identification purposes
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync everywhere in VirtualBox, the virtual machine name is also used
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync as a name of the machine's settings file and as a name of the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync subdirectory this settings file resides in. Thus, every time you
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync change the value of this property, the settings file will be
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync renamed once you call <link to="#saveSettings()"/> to confirm the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync change. The containing subdirectory will be also renamed, but
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync only if it has exactly the same name as the settings file
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync itself prior to changing this property (for backward compatibility
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync with previous API releases). The above implies the following
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync limitations:
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <li>The machine name can contain only characters that are valid
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync file name characters according to the rules of the file
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync system used to store VirtualBox configuration.</li>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <li>You cannot have two or more machines with the same name
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync if they use the same subdirectory for storing the machine
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync settings files.</li>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <li>You cannot change the name of the machine if it is running,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync or if any file in the directory containing the settings file
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync is being used by another running machine or by any other
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync process in the host operating system at a time when
d14682a025d2c801f1e777f491092d2ebbe78c3cvboxsync If any of the above limitations are hit, <link to="#saveSettings()"/>
d14682a025d2c801f1e777f491092d2ebbe78c3cvboxsync will return an appropriate error message explaining the exact
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync reason and the changes you made to this machine will not be
d14682a025d2c801f1e777f491092d2ebbe78c3cvboxsync For "legacy" machines created using the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="IVirtualBox::createLegacyMachine()"/> call,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the above naming limitations do not apply because the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync machine name does not affect the settings file name.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The settings file name remains the same as it was specified
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync during machine creation and never changes.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Description of the virtual machine.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync The description attribute can contain any text and is
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync typically used to describe the hardware and software
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync configuration of the virtual machine in detail (i.e. network
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync settings, versions of the installed software and so on).
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync User-defined identifier of the Guest OS type.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync an IGuestOSType object representing details about the given
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync Guest OS type.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync This value may differ from the value returned by
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="IGuest::OSTypeId"/> if Guest Additions are
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync installed to the guest OS.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="memoryBalloonSize" type="unsigned long">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <desc>Initial memory balloon size in megabytes.</desc>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <attribute name="statisticsUpdateInterval" type="unsigned long">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <desc>Initial interval to update guest statistics in seconds.</desc>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <attribute name="MonitorCount" type="unsigned long">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Number of virtual monitors.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Only effective on Windows XP and later guests with
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Guest Additions installed.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync </attribute>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync This setting determines whether VirtualBox will try to make use of
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the host CPU's hardware virtualization extensions such as Intel VT-x
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync and AMD-V. Note that in case such extensions are not available,
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync they will not be used.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <attribute name="PAEEnabled" type="boolean" default="false">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync This setting determines whether VirtualBox will expose the Physical Address
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync is not available, it will not be reported.
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Full path to the directory used to store snapshot data
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync (difrerencing hard disks and saved state files) of this machine.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync The initial value of this property is
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Currently, it is an error to try to change this property on
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync a machine that has snapshots (because this would require to
6f1977ffd39bde1977845dd91fb8c8027eeb247evboxsync move possibly large files to a different location).
6f1977ffd39bde1977845dd91fb8c8027eeb247evboxsync A separate method will be available for this purpose later.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Setting this property to <tt>null</tt> will restore the
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync initial value.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync When setting this property, the specified path can be
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync absolute (full path) or relative to the directory where the
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <link to="#settingsFilePath">machine settings file</link>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync is located. When reading this property, a full path is
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync always returned.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The specified path may not exist, it will be created
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync when necessary.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync </attribute>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync </attribute>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <attribute name="hardDiskAttachments" type="IHardDiskAttachmentCollection" readonly="yes">
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <desc>Collection of hard disks attached to the machine.</desc>
6f1977ffd39bde1977845dd91fb8c8027eeb247evboxsync </attribute>
6f1977ffd39bde1977845dd91fb8c8027eeb247evboxsync <attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="FloppyDrive" type="IFloppyDrive" readonly="yes">
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync </attribute>
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <attribute name="USBController" type="IUSBController" readonly="yes">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Associated USB controller object.
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync This method may set a @ref com_warnings "warning result code".
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync If USB functionality is not avaliable in the given edition of
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync VirtualBox, this method will set the result code to @c E_NOTIMPL.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
3c9ed6defa3feca7e21adef4b5d1ba3002fc94c9vboxsync <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync <desc>Associated audio adapter, always present.</desc>
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="SATAController" type="ISATAController" readonly="yes">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Associated SATA controller object.
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <attribute name="settingsFilePath" type="wstring" readonly="yes">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Full name of the file containing machine settings data.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <attribute name="settingsFileVersion" type="wstring" readonly="yes">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Current version of the format of the settings file of this machine
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The version string has the following format:
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync where <tt>x</tt> and <tt>y</tt> are the major and the minor format
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync versions, and <tt>platform</tt> is the platform identifier.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The current version usually matches the value of the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync settings file was created by an older version of VirtualBox and there
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync was a change of the settings file format since then.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Note that VirtualBox automatically converts settings files from older
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync versions to the most recent version when reading them (usually at
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox startup) but it doesn't save the changes back until
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync you call a method that implicitly saves settings (such as
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync explicitly. Therefore, if the value of this attribute differs from the
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync means that the settings file was converted but the result of the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync conversion is not yet saved to disk.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync The above feature may be used by interactive front-ends to inform users
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync about the settings file format change and offer them to explicitly save
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync all converted settings files (the global and VM-specific ones),
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync optionally create bacup copies of the old settings files before saving,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <attribute name="settingsModified" type="boolean" readonly="yes">
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Whether the settings of this machine have been modified
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync (but neither yet saved nor discarded).
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync Reading this property is only valid on instances returned
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync by <link to="ISession::machine"/> and on new machines
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync created by <link to="IVirtualBox::createMachine"/> or opened
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync yet registered, or on unregistered machines after calling
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <link to="IVirtualBox::unregisterMachine"/>. For all other
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync cases, the settigs can never be modified.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync For newly created unregistered machines, the value of this
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync property is always TRUE until <link to="#saveSettings()"/>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync is called (no matter if any machine settings have been
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync changed after the creation or not). For opened machines
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the value is set to FALSE (and then follows to normal rules).
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <attribute name="sessionState" type="SessionState" readonly="yes">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <desc>Current session state for this machine.</desc>
6ba96ad7028e4d559a5998de4bab0b71a8251c99vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="sessionType" type="wstring" readonly="yes">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Type of the session. If <link to="#sessionState"/> is
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync SessionSpawning or SessionOpen, this attribute contains the
e23e238e79c2d0e00beb102d43bdb4e40cb8534fvboxsync same value as passed to the
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <link to="IVirtualBox::openRemoteSession()"/> method in the @a
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync type parameter. If the session was opened directly using
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <link to="#sessionState"/> is SessionClosed, the value of this
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync attribute is @c null.
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync </attribute>
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <attribute name="sessionPid" type="unsigned long" readonly="yes">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Identifier of the session process. This attribute contains the
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync platform-dependent identifier of the process that has opened a
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync direct session for this machine using the
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync <link to="IVirtualBox::openSession()"/> call. The returned value
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync is only valid if <link to="#sessionState"/> is SessionOpen or
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync SessionClosing (i.e. a session is currently open or being
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync closed) by the time this property is read.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="state" type="MachineState" readonly="yes">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <desc>Current execution state of this machine.</desc>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <attribute name="lastStateChange" type="long long" readonly="yes">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Time stamp of the last execution state change,
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync in milliseconds since 1970-01-01 UTC.
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync </attribute>
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync <attribute name="stateFilePath" type="wstring" readonly="yes">
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync Full path to the file that stores the execution state of
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync the machine when it is in the <link to="MachineState::Saved"/>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync When the machine is not in the Saved state, this attribute
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync </attribute>
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync <attribute name="logFolder" type="wstring" readonly="yes">
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync Full path to the folder that stores a set of rotated log files
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync recorded during machine execution. The most recent log file is
ece707b8d97e63ed54d4b48d7a8d841187e0023cvboxsync named <tt>VBox.log.1</tt> and so on (upto <tt>VBox.log.3</tt>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync in the current version).
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
b57c052e6d9d432fa8b66fb33d373fc608d4d050vboxsync <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Current snapshot of this machine.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync A <tt>null</tt> object is returned if the machine doesn't
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync have snapshots.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <attribute name="snapshotCount" type="unsigned long" readonly="yes">
8be5264d31d6a6ec949ff2285764c9af57298b52vboxsync Number of snapshots taken on this machine. Zero means the
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync machine doesn't have any snapshots.
8be5264d31d6a6ec949ff2285764c9af57298b52vboxsync </attribute>
8be5264d31d6a6ec949ff2285764c9af57298b52vboxsync <attribute name="currentStateModified" type="boolean" readonly="yes">
8be5264d31d6a6ec949ff2285764c9af57298b52vboxsync Returns <tt>true</tt> if the current state of the machine is not
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync identical to the state stored in the current snapshot.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The current state is identical to the current snapshot right
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync after one of the following calls are made:
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync <link to="IConsole::discardCurrentSnapshotAndState"/>
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync <li><link to="IConsole::takeSnapshot"/> (issued on a
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync powered off or saved machine, for which
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <link to="#settingsModified"/> returns <tt>false</tt>)
ee357d0503e525172eab0eeb8f5befc2993c7ea5vboxsync The current state remains identical until one of the following
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync For machines that don't have snapshots, this property is
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync Collection of shared folders for this machine (permanent shared
07557d07616212d7ba6e7ab3059e85cb14633775vboxsync folders). These folders are shared automatically at machine startup
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync and available only to the guest OS installed within this machine.
7c19e11502220292d5270519296442234c2493cdvboxsync New shared folders are added to the collection using
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <link to="#createSharedFolder"/>. Existing shared folders can be
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <attribute name="clipboardMode" type="ClipboardMode">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Synchronization mode between the host OS clipboard
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync and the guest OS clipboard.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync </attribute>
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Puts the given device to the specified position in
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync the boot order.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync To indicate that no device is associated with the given position,
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync @todo setHardDiskBootOrder(), setNetworkBootOrder()
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync <param name="position" type="unsigned long" dir="in">
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Position in the boot order (<tt>1</tt> to the total number of
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync devices the machine can boot from, as returned by
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync The type of the device used to boot at the given position.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Returns the device type that occupies the specified
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync position in the boot order.
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync @todo [remove?]
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync If the machine can have more than one device of the returned type
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync (such as hard disks), then a separate method should be used to
5414e69c0f099d0a46301eb9c20cb1536ab1e71avboxsync retrieve the individual device that occupies the given position.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync If here are no devices at the given position, then
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync @todo getHardDiskBootOrder(), getNetworkBootOrder()
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync Position in the boot order (<tt>1</tt> to the total number of
892e4404b22b024dd58b9561787a5ac46a02b6c5vboxsync devices the machine can boot from, as returned by
folders). When the session is closed (e.g. the machine is powered down),
state (i.e. its current execution state, current settings and
children at all (i.e. the first snapshot is the only snapshot of
hard disk simply becomes unused (i.e. not attached to any VM). In the
If the current snapshot is the first snapshot of the machine (i.e. it
On DOS-like platforms, it is a drive name (e.g. R:).
On DOS-like platforms, it is a drive name (e.g. A:).
last taken snapshot (i.e. the head snapshot on the branch) and it
The returned machine object is immutable, i.e. no
hard disk being attached. Otherwise, the first (i.e. the most
hard disk is cloned (i.e. copied to a separate Virtual Disk Image
returns the hard disk object itself (i.e. the same object you
See also www.fourcc.org for more informantion about FOURCC pixel formats.
current video mode (i.e. left unchanged).
Note that when VBox allocates a TAP device, this property will not be set, i.e. the
has not been defined. This property is non persistent, i.e. it will not be
Filename where a network trace will be stored. If not set, VBox-pid.pcap
i.e. it is ignored by IHostUSBDeviceFilter objects.
if the session is currently open (i.e. its #state is SessionType::SessionOpen),
namespace="virtualbox.org">
namespace="virtualbox.org">