ea0316554d23852601ee840c4a856339501411a4vboxsync<?xml version="1.0" ?>

ea0316554d23852601ee840c4a856339501411a4vboxsync

ea0316554d23852601ee840c4a856339501411a4vboxsync

<idl>

<desc>

Welcome to the <b>VirtualBox Main API documentation</b>. This documentation

describes the so-called <i>VirtualBox Main API</i> which comprises all public

COM interfaces and components provided by the VirtualBox server and by the

VirtualBox client library.

VirtualBox employs a client-server design, meaning that whenever any part of

VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line

interface or any virtual machine --, a dedicated server process named

VBoxSVC runs in the background. This allows multiple processes working with

VirtualBox to cooperate without conflicts. These processes communicate to each

other using inter-process communication facilities provided by the COM

implementation of the host computer.

On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM

implementation. On all other platforms, Mozilla XPCOM, an open-source COM

implementation, is used.

All the parts that a typical VirtualBox user interacts with (the Qt GUI

and the VBoxManage command-line interface) are technically

front-ends to the Main API and only use the interfaces that are documented

in this Main API documentation. This ensures that, with any given release

version of VirtualBox, all capabilities of the product that could be useful

to an external client program are always exposed by way of this API.

The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)

contains two public component classes:

<tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which

implement IVirtualBox and ISession interfaces respectively. These two classes

are of supreme importance and will be needed in order for any front-end

program to do anything useful. It is recommended to read the documentation of

the mentioned interfaces first.

The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that

there can be only one object of this class on the local machine at any given

time. This object is a parent of many other objects in the VirtualBox COM

library and lives in the VBoxSVC process. In fact, when you create an instance

of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC

process is already running, starts it if not, and returns you a reference to

the <tt>VirtualBox</tt> object created in this process. When the last reference

to this object is released, the VBoxSVC process ends (with a 5 second delay to

protect from too frequent restarts).

The <tt>%VirtualBox.Session</tt> class is a regular component. You can create

as many <tt>Session</tt> objects as you need but all of them will live in a

process which issues the object instantiation call. <tt>Session</tt> objects

represent virtual machine sessions which are used to configure virtual

machines and control their execution.

</desc>

<if target="midl">

<cpp line="enum {"/>

<cpp line=" kTypeLibraryMajorVersion = 1,"/>

<cpp line=" kTypeLibraryMinorVersion = 0"/>

<cpp line="};"/>

</if>

<if target="xpidl">

<!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->

<cpp>

/* currently, nsISupportsImpl.h lacks the below-like macros */

#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI

#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI

#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI

#define NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI NS_IMPL_QUERY_INTERFACE4_CI

#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI

# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \

NS_IMPL_THREADSAFE_ADDREF(_class) \

NS_IMPL_THREADSAFE_RELEASE(_class) \

NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \

NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)

#endif

#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI

# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \

NS_IMPL_THREADSAFE_ADDREF(_class) \

NS_IMPL_THREADSAFE_RELEASE(_class) \

NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \

NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)

#endif

#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI

# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \

NS_IMPL_THREADSAFE_ADDREF(_class) \

NS_IMPL_THREADSAFE_RELEASE(_class) \

NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \

NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)

#endif

#ifndef NS_IMPL_THREADSAFE_ISUPPORTS4_CI

# define NS_IMPL_THREADSAFE_ISUPPORTS4_CI(_class, _i1, _i2, _i3, _i4) \

NS_IMPL_THREADSAFE_ADDREF(_class) \

NS_IMPL_THREADSAFE_RELEASE(_class) \

NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI(_class, _i1, _i2, _i3, _i4) \

NS_IMPL_CI_INTERFACE_GETTER4(_class, _i1, _i2, _i3, _i4)

#endif

#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI

# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \

NS_INTERFACE_MAP_BEGIN(_class) \

NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \

NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \

NS_IMPL_QUERY_CLASSINFO(_class) \

NS_INTERFACE_MAP_END

#endif

#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI

# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \

_i2, _ic2) \

NS_INTERFACE_MAP_BEGIN(_class) \

NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \

NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \

NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \

NS_IMPL_QUERY_CLASSINFO(_class) \

NS_INTERFACE_MAP_END

#endif

#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI

# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \

_i2, _ic2, _i3, _ic3) \

NS_INTERFACE_MAP_BEGIN(_class) \

NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \

NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \

NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \

NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \

NS_IMPL_QUERY_CLASSINFO(_class) \

NS_INTERFACE_MAP_END

#endif

#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI

#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI

#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI

#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI

# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \

NS_IMPL_THREADSAFE_ADDREF(_class) \

NS_IMPL_THREADSAFE_RELEASE(_class) \

NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \

NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)

#endif

#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI

# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \

_i2, _ic2) \

NS_IMPL_THREADSAFE_ADDREF(_class) \

NS_IMPL_THREADSAFE_RELEASE(_class) \

NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \

_i2, _ic2) \

NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)

#endif

#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI

# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \

_i2, _ic2, _i3, _ic3) \

NS_IMPL_THREADSAFE_ADDREF(_class) \

NS_IMPL_THREADSAFE_RELEASE(_class) \

NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \

_i2, _ic2, _i3, _ic3) \

NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)

#endif

</cpp>

</if>

<library

name="VirtualBox"

uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"

version="1.3"

desc="VirtualBox Type Library"

appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"

supportsErrorInfo="yes"

>

<!--

<descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">

<desc>

This section describes all VirtualBox-specific COM result codes that may

be returned by methods of VirtualBox COM interfaces in addition to

standard COM result codes.

Note that along with the result code, every VirtualBox method returns

extended error information through the IVirtualBoxErrorInfo interface on

failure. This interface is a preferred way to present the error to the end

user because it contains a human readable description of the error. Raw

result codes, both standard and described in this section, are intended to

be used by programs to analyze the reason of a failure and select an

appropriate course of action without involving the end user (for example,

retry the operation later or make a different call).

The standard COM result codes that may originate from our methods include:

<table>

<tr><td>E_INVALIDARG</td>

<td>

Returned when the value of the method's argument is not within the range

of valid values. This should not be confused with situations when the

value is within the range but simply doesn't suit the current object

state and there is a possibility that it will be accepted later (in such

cases VirtualBox-specific codes are returned, for example,

<link to="VBOX_E_OBJECT_NOT_FOUND"/>).

</td>

</tr>

<tr><td>E_POINTER</td>

<td>

Returned if a memory pointer for the output argument is invalid (for

example, @c null). When pointers representing input arguments (such

as strings) are invalid, E_INVALIDARG is returned.

</td>

</tr>

<tr><td>E_ACCESSDENIED</td>

<td>

Returned when the called object is not ready. Since the lifetime of a

public COM object cannot be fully controlled by the implementation,

VirtualBox maintains the readiness state for all objects it creates and

returns this code in response to any method call on the object that was

deactivated by VirtualBox and is not functioning any more.

</td>

</tr>

<tr><td>E_OUTOFMEMORY</td>

<td>

Returned when a memory allocation operation fails.

</td>

</tr>

</table>

</desc>

</descGroup>

<!--

<result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">

<desc>

Object corresponding to the supplied arguments does not exist.

</desc>

</result>

<result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">

<desc>

Current virtual machine state prevents the operation.

</desc>

</result>

<result name="VBOX_E_VM_ERROR" value="0x80BB0003">

<desc>

Virtual machine error occurred attempting the operation.

</desc>

</result>

<result name="VBOX_E_FILE_ERROR" value="0x80BB0004">

<desc>

File not accessible or erroneous file contents.

</desc>

</result>

<result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">

<desc>

Runtime subsystem error.

</desc>

</result>

<result name="VBOX_E_PDM_ERROR" value="0x80BB0006">

<desc>

Pluggable Device Manager error.

</desc>

</result>

<result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">

<desc>

Current object state prohibits operation.

</desc>

</result>

<result name="VBOX_E_HOST_ERROR" value="0x80BB0008">

<desc>

Host operating system related error.

</desc>

</result>

<result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">

<desc>

Requested operation is not supported.

</desc>

</result>

<result name="VBOX_E_XML_ERROR" value="0x80BB000A">

<desc>

Invalid XML found.

</desc>

</result>

<result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">

<desc>

Current session state prohibits operation.

</desc>

</result>

<result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">

<desc>

Object being in use prohibits operation.

</desc>

</result>

<!--

<descGroup/>

<!--

<enum

name="SettingsVersion"

uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f"

>

<desc>

Settings version of VirtualBox settings files. This is written to

the "version" attribute of the root "VirtualBox" element in the settings

file XML and indicates which VirtualBox version wrote the file.

</desc>

<const name="Null" value="0">

<desc>Null value, indicates invalid version.</desc>

</const>

<const name="v1_0" value="1">

<desc>Legacy settings version, not currently supported.</desc>

</const>

<const name="v1_1" value="2">

<desc>Legacy settings version, not currently supported.</desc>

</const>

<const name="v1_2" value="3">

<desc>Legacy settings version, not currently supported.</desc>

</const>

<const name="v1_3pre" value="4">

<desc>Legacy settings version, not currently supported.</desc>

</const>

<const name="v1_3" value="5">

<desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>

<!--

</const>

<const name="v1_4" value="6">

<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>

<!--

</const>

<const name="v1_5" value="7">

<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>

<!--

</const>

<const name="v1_6" value="8">

<desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>

<!--

</const>

<const name="v1_7" value="9">

<desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>

<!--

</const>

<const name="v1_8" value="10">

<desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>

<!--

</const>

<const name="v1_9" value="11">

<desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>

<!--

</const>

<const name="v1_10" value="12">

<desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc>

<!--

</const>

<const name="v1_11" value="13">

<desc>Settings version "1.11", written by VirtualBox 4.0.x.</desc>

<!--

</const>

<const name="v1_12" value="14">

<desc>Settings version "1.12", written by VirtualBox 4.1.x.</desc>

<!--

</const>

<const name="Future" value="99999">

<desc>Settings version greater than "1.12", written by a future VirtualBox version.</desc>

</const>

</enum>

<enum

name="AccessMode"

uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"

>

<desc>

Access mode for opening files.

</desc>

<const name="ReadOnly" value="1"/>

<const name="ReadWrite" value="2"/>

</enum>

<enum

name="MachineState"

uuid="ec6c6a9e-113d-4ff4-b44f-0b69f21c97fe"

>

<desc>

Virtual machine execution state.

This enumeration represents possible values of the <link

to="IMachine::state"/> attribute.

Below is the basic virtual machine state diagram. It shows how the state

changes during virtual machine execution. The text in square braces shows

a method of the IConsole interface that performs the given state

transition.

<pre>

+---------[powerDown()] &lt;- Stuck &lt;--[failure]-+

V |

+-&gt; PoweredOff --+--&gt;[powerUp()]--&gt; Starting --+ | +-----[resume()]-----+

| | | | V |

| Aborted -----+ +--&gt; Running --[pause()]--&gt; Paused

| | ^ | ^ |

| Saved -----------[powerUp()]--&gt; Restoring -+ | | | |

| ^ | | | |

| | +-----------------------------------------+-|-------------------+ +

| | | | |

| | +-- Saving &lt;--------[takeSnapshot()]&lt;-------+---------------------+

| | | |

| +-------- Saving &lt;--------[saveState()]&lt;----------+---------------------+

| | |

+-------------- Stopping -------[powerDown()]&lt;----------+---------------------+

</pre>

Note that states to the right from PoweredOff, Aborted and Saved in the

above diagram are called <i>online VM states</i>. These states

represent the virtual machine which is being executed in a dedicated

process (usually with a GUI window attached to it where you can see the

activity of the virtual machine and interact with it). There are two

special pseudo-states, FirstOnline and LastOnline, that can be used in

relational expressions to detect if the given machine state is online or

not:

<pre>

if (machine.GetState() &gt;= MachineState_FirstOnline &amp;&amp;

machine.GetState() &lt;= MachineState_LastOnline)

{

...the machine is being executed...

}

</pre>

When the virtual machine is in one of the online VM states (that is, being

executed), only a few machine settings can be modified. Methods working

with such settings contain an explicit note about that. An attempt to

change any other setting or perform a modifying operation during this time

will result in the @c VBOX_E_INVALID_VM_STATE error.

All online states except Running, Paused and Stuck are transitional: they

represent temporary conditions of the virtual machine that will last as

long as the operation that initiated such a condition.

The Stuck state is a special case. It means that execution of the machine

has reached the "Guru Meditation" condition. This condition indicates an

internal VMM (virtual machine manager) failure which may happen as a

result of either an unhandled low-level virtual hardware exception or one

of the recompiler exceptions (such as the <i>too-many-traps</i>

condition).

Note also that any online VM state may transit to the Aborted state. This

happens if the process that is executing the virtual machine terminates

unexpectedly (for example, crashes). Other than that, the Aborted state is

equivalent to PoweredOff.

There are also a few additional state diagrams that do not deal with

virtual machine execution and therefore are shown separately. The states

shown on these diagrams are called <i>offline VM states</i> (this includes

PoweredOff, Aborted and Saved too).

The first diagram shows what happens when a lengthy setup operation is

being executed (such as <link to="IMachine::attachDevice"/>).

<pre>

+----------------------------------(same state as before the call)------+

| |

+-&gt; PoweredOff --+ |

| | |

|-&gt; Aborted -----+--&gt;[lengthy VM configuration call] --&gt; SettingUp -----+

| |

+-&gt; Saved -------+

</pre>

The next two diagrams demonstrate the process of taking a snapshot of a

powered off virtual machine, restoring the state to that as of a snapshot

or deleting a snapshot, respectively.

<pre>

+----------------------------------(same state as before the call)------+

| |

+-&gt; PoweredOff --+ |

| +--&gt;[takeSnapshot()] -------------------&gt; Saving ------+

+-&gt; Aborted -----+

+-&gt; PoweredOff --+

| |

| Aborted -----+--&gt;[restoreSnapshot() ]-------&gt; RestoringSnapshot -+

| | [deleteSnapshot() ]-------&gt; DeletingSnapshot --+

+-&gt; Saved -------+ |

| |

+---(Saved if restored from an online snapshot, PoweredOff otherwise)---+

</pre>

Note that the Saving state is present in both the offline state group and

online state group. Currently, the only way to determine what group is

assumed in a particular case is to remember the previous machine state: if

it was Running or Paused, then Saving is an online state, otherwise it is

an offline state. This inconsistency may be removed in one of the future

versions of VirtualBox by adding a new state.

<note internal="yes">

For whoever decides to touch this enum: In order to keep the

comparisons involving FirstOnline and LastOnline pseudo-states valid,

the numeric values of these states must be correspondingly updated if

needed: for any online VM state, the condition

<tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be

@c true. The same relates to transient states for which

the condition <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be

@c true.

</note>

</desc>

<const name="Null" value="0">

<desc>Null value (never used by the API).</desc>

</const>

<const name="PoweredOff" value="1">

<desc>

The machine is not running and has no saved execution state; it has

either never been started or been shut down successfully.

</desc>

</const>

<const name="Saved" value="2">

<desc>

The machine is not currently running, but the execution state of the machine

has been saved to an external file when it was running, from where

it can be resumed.

</desc>

</const>

<const name="Teleported" value="3">

<desc>

The machine was teleported to a different host (or process) and then

powered off. Take care when powering it on again may corrupt resources

it shares with the teleportation target (e.g. disk and network).

</desc>

</const>

<const name="Aborted" value="4">

<desc>

The process running the machine has terminated abnormally. This may

indicate a crash of the VM process in host execution context, or

the VM process has been terminated externally.

</desc>

</const>

<const name="Running" value="5">

<desc>

The machine is currently being executed.

<note internal="yes">

For whoever decides to touch this enum: In order to keep the

comparisons in the old source code valid, this state must immediately

precede the Paused state.

TODO: Lift this spectacularly wonderful restriction.

</note>

</desc>

</const>

<const name="Paused" value="6">

<desc>

Execution of the machine has been paused.

<note internal="yes">

For whoever decides to touch this enum: In order to keep the

comparisons in the old source code valid, this state must immediately

follow the Running state.

TODO: Lift this spectacularly wonderful restriction.

</note>

</desc>

</const>

<const name="Stuck" value="7">

<desc>

Execution of the machine has reached the "Guru Meditation"

condition. This indicates a severe error in the hypervisor itself.

<note internal="yes">

bird: Why this uncool name? Could we rename it to "GuruMeditation" or

"Guru", perhaps? Or are there some other VMM states that are

intended to be lumped in here as well?

</note>

</desc>

</const>

<const name="Teleporting" value="8">

<desc>

The machine is about to be teleported to a different host or process.

It is possible to pause a machine in this state, but it will go to the

@c TeleportingPausedVM state and it will not be

possible to resume it again unless the teleportation fails.

</desc>

</const>

<const name="LiveSnapshotting" value="9">

<desc>

A live snapshot is being taken. The machine is running normally, but

some of the runtime configuration options are inaccessible. Also, if

paused while in this state it will transition to

@c Saving and it will not be resume the

execution until the snapshot operation has completed.

</desc>

</const>

<const name="Starting" value="10">

<desc>

Machine is being started after powering it on from a

zero execution state.

</desc>

</const>

<const name="Stopping" value="11">

<desc>

Machine is being normally stopped powering it off, or after the guest OS

has initiated a shutdown sequence.

</desc>

</const>

<const name="Saving" value="12">

<desc>

Machine is saving its execution state to a file, or an online

snapshot of the machine is being taken.

</desc>

</const>

<const name="Restoring" value="13">

<desc>

Execution state of the machine is being restored from a file

after powering it on from the saved execution state.

</desc>

</const>

<const name="TeleportingPausedVM" value="14">

<desc>

The machine is being teleported to another host or process, but it is

not running. This is the paused variant of the

@c state.

</desc>

</const>

<const name="TeleportingIn" value="15">

<desc>

Teleporting the machine state in from another host or process.

</desc>

</const>

<const name="FaultTolerantSyncing" value="16">

<desc>

The machine is being synced with a fault tolerant VM running elsewhere.

</desc>

</const>

<const name="DeletingSnapshotOnline" value="17">

<desc>

Like @c DeletingSnapshot, but the merging of media is ongoing in

the background while the machine is running.

</desc>

</const>

<const name="DeletingSnapshotPaused" value="18">

<desc>

Like @c DeletingSnapshotOnline, but the machine was paused when the

merging of differencing media was started.

</desc>

</const>

<const name="RestoringSnapshot" value="19">

<desc>

A machine snapshot is being restored; this typically does not take long.

</desc>

</const>

<const name="DeletingSnapshot" value="20">

<desc>

A machine snapshot is being deleted; this can take a long time since this

may require merging differencing media. This value indicates that the

machine is not running while the snapshot is being deleted.

</desc>

</const>

<const name="SettingUp" value="21">

<desc>

Lengthy setup operation is in progress.

</desc>

</const>

<const name="FirstOnline" value="5" wsmap="suppress"> <!-- Running -->

<desc>

Pseudo-state: first online state (for use in relational expressions).

</desc>

</const>

<const name="LastOnline" value="18" wsmap="suppress"> <!-- DeletingSnapshotPaused -->

<desc>

Pseudo-state: last online state (for use in relational expressions).

</desc>

</const>

<const name="FirstTransient" value="8" wsmap="suppress"> <!-- Teleporting -->

<desc>

Pseudo-state: first transient state (for use in relational expressions).

</desc>

</const>

<const name="LastTransient" value="21" wsmap="suppress"> <!-- SettingUp -->

<desc>

Pseudo-state: last transient state (for use in relational expressions).

</desc>

</const>

</enum>

<enum

name="SessionState"

uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8"

>

<desc>

Session state. This enumeration represents possible values of

<link to="IMachine::sessionState"/> and <link to="ISession::state"/>

attributes.

</desc>

<const name="Null" value="0">

<desc>Null value (never used by the API).</desc>

</const>

<const name="Unlocked" value="1">

<desc>

In <link to="IMachine::sessionState"/>, this means that the machine

is not locked for any sessions.

In <link to="ISession::state"/>, this means that no machine is

currently locked for this session.

</desc>

</const>

<const name="Locked" value="2">

<desc>

In <link to="IMachine::sessionState"/>, this means that the machine

is currently locked for a session, whose process identifier can

then be found in the <link to="IMachine::sessionPid" /> attribute.

In <link to="ISession::state"/>, this means that a machine is

currently locked for this session, and the mutable machine object

can be found in the <link to="ISession::machine"/> attribute

(see <link to="IMachine::lockMachine" /> for details).

</desc>

</const>

<const name="Spawning" value="3">

<desc>

A new process is being spawned for the machine as a result of

<link to="IMachine::launchVMProcess"/> call. This state also occurs

as a short transient state during an <link to="IMachine::lockMachine"/>

call.

</desc>

</const>

<const name="Unlocking" value="4">

<desc>

The session is being unlocked.

</desc>

</const>

</enum>

<enum

name="CPUPropertyType"

uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5"

>

<desc>

Virtual CPU property type. This enumeration represents possible values of the

IMachine get- and setCPUProperty methods.

</desc>

<const name="Null" value="0">

<desc>Null value (never used by the API).</desc>

</const>

<const name="PAE" value="1">

<desc>

This setting determines whether VirtualBox will expose the Physical Address

Extension (PAE) feature of the host CPU to the guest. Note that in case PAE

is not available, it will not be reported.

</desc>

</const>

<const name="Synthetic" value="2">

<desc>

This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow

teleporting between host systems that differ significantly.

</desc>

</const>

</enum>

<enum

name="HWVirtExPropertyType"

uuid="ce81dfdd-d2b8-4a90-bbea-40ee8b7ffcee"

>

<desc>

Hardware virtualization property type. This enumeration represents possible values

for the <link to="IMachine::getHWVirtExProperty"/> and

<link to="IMachine::setHWVirtExProperty"/> methods.

</desc>

<const name="Null" value="0">

<desc>Null value (never used by the API).</desc>

</const>

<const name="Enabled" value="1">

<desc>

Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If

such extensions are not available, they will not be used.

</desc>

</const>

<const name="Exclusive" value="2">

<desc>

Whether hardware virtualization is used exclusively by VirtualBox. When enabled,

VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V

feature of the host. To share these with other hypervisors, you must disable this property.

</desc>

</const>

<const name="VPID" value="3">

<desc>

Whether VT-x VPID is enabled. If this extension is not available, it will not be used.

</desc>

</const>

<const name="NestedPaging" value="4">

<desc>

Whether Nested Paging is enabled. If this extension is not available, it will not be used.

</desc>

</const>

<const name="LargePages" value="5">

<desc>

Whether large page allocation is enabled; requires nested paging and a 64 bits host.

</desc>

</const>

<const name="Force" value="6">

<desc>

Whether the VM should fail to start if hardware virtualization (VT-x/AMD-V) cannot be used. If

not set, there will be an automatic fallback to software virtualization.

</desc>

</const>

</enum>

<enum

name="FaultToleranceState"

uuid="5124f7ec-6b67-493c-9dee-ee45a44114e1"

>

<desc>

Used with <link to="IMachine::faultToleranceState" />.

</desc>

<const name="Inactive" value="1">

<desc>No fault tolerance enabled.</desc>

</const>

<const name="Master" value="2">

<desc>Fault tolerant master VM.</desc>

</const>

<const name="Standby" value="3">

<desc>Fault tolerant standby VM.</desc>

</const>

</enum>

<enum

name="LockType"

uuid="138b53f8-db4b-47c5-b32b-4ef52f769413"

>

<desc>

Used with <link to="IMachine::lockMachine" />.

</desc>

<const name="Write" value="2">

<desc>Lock the machine for writing.</desc>

</const>

<const name="Shared" value="1">

<desc>Request only a shared read lock for remote-controlling the machine.</desc>

</const>

</enum>

<enum

name="SessionType"

uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"

>

<desc>

Session type. This enumeration represents possible values of the

<link to="ISession::type"/> attribute.

</desc>

<const name="Null" value="0">

<desc>Null value (never used by the API).</desc>

</const>

<const name="WriteLock" value="1">

<desc>

Session has acquired an exclusive write lock on a machine

using <link to="IMachine::lockMachine"/>.

</desc>

</const>

<const name="Remote" value="2">

<desc>

Session has launched a VM process using

<link to="IMachine::launchVMProcess"/>

</desc>

</const>

<const name="Shared" value="3">

<desc>

Session has obtained a link to another session using

<link to="IMachine::lockMachine"/>

</desc>

</const>

</enum>

<enum

name="DeviceType"

uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"

>

<desc>

Device type.

</desc>

<const name="Null" value="0">

<desc>

Null value, may also mean "no device" (not allowed for

<link to="IConsole::getDeviceActivity"/>).

</desc>

</const>

<const name="Floppy" value="1">

<desc>Floppy device.</desc>

</const>

<const name="DVD" value="2">

<desc>CD/DVD-ROM device.</desc>

</const>

<const name="HardDisk" value="3">

<desc>Hard disk device.</desc>

</const>

<const name="Network" value="4">

<desc>Network device.</desc>

</const>

<const name="USB" value="5">

<desc>USB device.</desc>

</const>

<const name="SharedFolder" value="6">

<desc>Shared folder device.</desc>

</const>

</enum>

<enum

name="DeviceActivity"

uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"

>

<desc>

Device activity for <link to="IConsole::getDeviceActivity"/>.

</desc>

<const name="Null" value="0"/>

<const name="Idle" value="1"/>

<const name="Reading" value="2"/>

<const name="Writing" value="3"/>

</enum>

<enum

name="ClipboardMode"

uuid="33364716-4008-4701-8f14-be0fa3d62950"

>

<desc>

Host-Guest clipboard interchange mode.

</desc>

<const name="Disabled" value="0"/>

<const name="HostToGuest" value="1"/>

<const name="GuestToHost" value="2"/>

<const name="Bidirectional" value="3"/>

</enum>

<enum

name="Scope"

uuid="7c91096e-499e-4eca-9f9b-9001438d7855"

>

<desc>

Scope of the operation.

A generic enumeration used in various methods to define the action or

argument scope.

</desc>

<const name="Global" value="0"/>

<const name="Machine" value="1"/>

<const name="Session" value="2"/>

</enum>

<enum

name="BIOSBootMenuMode"

uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"

>

<desc>

BIOS boot menu mode.

</desc>

<const name="Disabled" value="0"/>

<const name="MenuOnly" value="1"/>

<const name="MessageAndMenu" value="2"/>

</enum>

<enum

name="ProcessorFeature"

uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"

>

<desc>

CPU features.

</desc>

<const name="HWVirtEx" value="0"/>

<const name="PAE" value="1"/>

<const name="LongMode" value="2"/>

<const name="NestedPaging" value="3"/>

</enum>

<enum

name="FirmwareType"

uuid="b903f264-c230-483e-ac74-2b37ce60d371"

>

<desc>

Firmware type.

</desc>

<const name="BIOS" value="1">

<desc>BIOS Firmware.</desc>

</const>

<const name="EFI" value="2">

<desc>EFI Firmware, bitness detected basing on OS type.</desc>

</const>

<const name="EFI32" value="3">

<desc>Efi firmware, 32-bit.</desc>

</const>

<const name="EFI64" value="4">

<desc>Efi firmware, 64-bit.</desc>

</const>

<const name="EFIDUAL" value="5">

<desc>Efi firmware, combined 32 and 64-bit.</desc>

</const>

</enum>

<enum

name="PointingHidType"

uuid="0d3c17a2-821a-4b2e-ae41-890c6c60aa97"

>

<desc>

Type of pointing device used in a virtual machine.

</desc>

<const name="None" value="1">

<desc>No mouse.</desc>

</const>

<const name="PS2Mouse" value="2">

<desc>PS/2 auxiliary device, a.k.a. mouse.</desc>

</const>

<const name="USBMouse" value="3">

<desc>USB mouse (relative pointer).</desc>

</const>

<const name="USBTablet" value="4">

<desc>USB tablet (absolute pointer).</desc>

</const>

<const name="ComboMouse" value="5">

<desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.

Using of such device can have negative performance implications. </desc>

</const>

</enum>

<enum

name="KeyboardHidType"

uuid="5a5b0996-3a3e-44bb-9019-56979812cbcc"

>

<desc>

Type of keyboard device used in a virtual machine.

</desc>

<const name="None" value="1">

<desc>No keyboard.</desc>

</const>

<const name="PS2Keyboard" value="2">

<desc>PS/2 keyboard.</desc>

</const>

<const name="USBKeyboard" value="3">

<desc>USB keyboard.</desc>

</const>

<const name="ComboKeyboard" value="4">

<desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.

Using of such device can have negative performance implications. </desc>

</const>

</enum>

<!--

<interface

name="IVirtualBoxErrorInfo" extends="$errorinfo"

uuid="e053d3c0-f493-491b-a735-3a9f0b1feed4"

supportsErrorInfo="no"

wsmap="managed"

>

<desc>

The IVirtualBoxErrorInfo interface represents extended error information.

Extended error information can be set by VirtualBox components after

unsuccessful or partially successful method invocation. This information

can be retrieved by the calling party as an IVirtualBoxErrorInfo object

and then shown to the client in addition to the plain 32-bit result code.

In MS COM, this interface extends the IErrorInfo interface,

in XPCOM, it extends the nsIException interface. In both cases,

it provides a set of common attributes to retrieve error

information.

Sometimes invocation of some component's method may involve methods of

other components that may also fail (independently of this method's

failure), or a series of non-fatal errors may precede a fatal error that

causes method failure. In cases like that, it may be desirable to preserve

information about all errors happened during method invocation and deliver

it to the caller. The <link to="#next"/> attribute is intended

specifically for this purpose and allows to represent a chain of errors

through a single IVirtualBoxErrorInfo object set after method invocation.

<note>errors are stored to a chain in the reverse order, i.e. the

initial error object you query right after method invocation is the last

error set by the callee, the object it points to in the @a next attribute

is the previous error and so on, up to the first error (which is the last

in the chain).</note>

</desc>

<attribute name="resultCode" type="long" readonly="yes">

<desc>

Result code of the error.

Usually, it will be the same as the result code returned

by the method that provided this error information, but not

always. For example, on Win32, CoCreateInstance() will most

likely return E_NOINTERFACE upon unsuccessful component

instantiation attempt, but not the value the component factory

returned. Value is typed 'long', not 'result',

to make interface usable from scripting languages.

<note>

In MS COM, there is no equivalent.

In XPCOM, it is the same as nsIException::result.

</note>

</desc>

</attribute>

<attribute name="interfaceID" type="uuid" mod="string" readonly="yes">

<desc>

UUID of the interface that defined the error.

<note>

In MS COM, it is the same as IErrorInfo::GetGUID, except for the

data type.

In XPCOM, there is no equivalent.

</note>

</desc>

</attribute>

<attribute name="component" type="wstring" readonly="yes">

<desc>

Name of the component that generated the error.

<note>

In MS COM, it is the same as IErrorInfo::GetSource.

In XPCOM, there is no equivalent.

</note>

</desc>

</attribute>

<attribute name="text" type="wstring" readonly="yes">

<desc>

Text description of the error.

<note>

In MS COM, it is the same as IErrorInfo::GetDescription.

In XPCOM, it is the same as nsIException::message.

</note>

</desc>

</attribute>

<attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">

<desc>

Next error object if there is any, or @c null otherwise.

<note>

In MS COM, there is no equivalent.

In XPCOM, it is the same as nsIException::inner.

</note>

</desc>

</attribute>

</interface>

<!--

<interface

name="IDHCPServer" extends="$unknown"

uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"

wsmap="managed"

>

<desc>

The IDHCPServer interface represents the vbox dhcp server configuration.

To enumerate all the dhcp servers on the host, use the

<link to="IVirtualBox::DHCPServers"/> attribute.

</desc>

<attribute name="enabled" type="boolean">

<desc>

specifies if the dhcp server is enabled

</desc>

</attribute>

<attribute name="IPAddress" type="wstring" readonly="yes">

<desc>

specifies server IP

</desc>

</attribute>

<attribute name="networkMask" type="wstring" readonly="yes">

<desc>

specifies server network mask

</desc>

</attribute>

<attribute name="networkName" type="wstring" readonly="yes">

<desc>

specifies internal network name the server is used for

</desc>

</attribute>

<attribute name="lowerIP" type="wstring" readonly="yes">

<desc>

specifies from IP address in server address range

</desc>

</attribute>

<attribute name="upperIP" type="wstring" readonly="yes">

<desc>

specifies to IP address in server address range

</desc>

</attribute>

<method name="setConfiguration">

<desc>

configures the server

<result name="E_INVALIDARG">

invalid configuration supplied

</result>

</desc>

<param name="IPAddress" type="wstring" dir="in">

<desc>

server IP address

</desc>

</param>

<param name="networkMask" type="wstring" dir="in">

<desc>

server network mask

</desc>

</param>

<param name="FromIPAddress" type="wstring" dir="in">

<desc>

server From IP address for address range

</desc>

</param>

<param name="ToIPAddress" type="wstring" dir="in">

<desc>

server To IP address for address range

</desc>

</param>

</method>

<method name="start">

<desc>

Starts DHCP server process.

<result name="E_FAIL">

Failed to start the process.

</result>

</desc>

<param name="networkName" type="wstring" dir="in">

<desc>

Name of internal network DHCP server should attach to.

</desc>

</param>

<param name="trunkName" type="wstring" dir="in">

<desc>

Name of internal network trunk.

</desc>

</param>

<param name="trunkType" type="wstring" dir="in">

<desc>

Type of internal network trunk.

</desc>

</param>

</method>

<method name="stop">

<desc>

Stops DHCP server process.

<result name="E_FAIL">

Failed to stop the process.

</result>

</desc>

</method>

</interface>

<interface

name="IVirtualBox" extends="$unknown"

uuid="d627bf11-2758-46be-9a4d-7d9ef794c247"

wsmap="managed"

>

<desc>

The IVirtualBox interface represents the main interface exposed by the

product that provides virtual machine management.

An instance of IVirtualBox is required for the product to do anything

useful. Even though the interface does not expose this, internally,

IVirtualBox is implemented as a singleton and actually lives in the

process of the VirtualBox server (VBoxSVC.exe). This makes sure that

IVirtualBox can track the state of all virtual machines on a particular

host, regardless of which frontend started them.

To enumerate all the virtual machines on the host, use the

<link to="IVirtualBox::machines"/> attribute.

</desc>

<attribute name="version" type="wstring" readonly="yes">

<desc>

A string representing the version number of the product. The

format is 3 integer numbers divided by dots (e.g. 1.0.1). The

last number represents the build number and will frequently change.

</desc>

</attribute>

<attribute name="revision" type="unsigned long" readonly="yes">

<desc>

The internal build revision number of the product.

</desc>

</attribute>

<attribute name="packageType" type="wstring" readonly="yes">

<desc>

A string representing the package type of this product. The

format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,

SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST

is either GENERIC, UBUNTU_606, UBUNTU_710, or something like

this.

</desc>

</attribute>

<attribute name="APIVersion" type="wstring" readonly="yes">

<desc>

A string representing the VirtualBox API version number. The format is

2 integer numbers divided by an underscore (e.g. 1_0). After the

first public release of packages with a particular API version the

API will not be changed in an incompatible way. Note that this

guarantee does not apply to development builds, and also there is no

guarantee that this version is identical to the first two integer

numbers of the package version.

</desc>

</attribute>

<attribute name="homeFolder" type="wstring" readonly="yes">

<desc>

Full path to the directory where the global settings file,

<tt>VirtualBox.xml</tt>, is stored.

In this version of VirtualBox, the value of this property is

always <tt>&lt;user_dir&gt;/.VirtualBox</tt> (where

<tt>&lt;user_dir&gt;</tt> is the path to the user directory,

as determined by the host OS), and cannot be changed.

This path is also used as the base to resolve relative paths in

places where relative paths are allowed (unless otherwise

expressly indicated).

</desc>

</attribute>

<attribute name="settingsFilePath" type="wstring" readonly="yes">

<desc>

Full name of the global settings file.

The value of this property corresponds to the value of

<link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.

</desc>

</attribute>

<attribute name="host" type="IHost" readonly="yes">

<desc>Associated host object.</desc>

</attribute>

<attribute name="systemProperties" type="ISystemProperties" readonly="yes">

<desc>Associated system information object.</desc>

</attribute>

<attribute name="machines" type="IMachine" readonly="yes" safearray="yes">

<desc>

Array of machine objects registered within this VirtualBox instance.

</desc>

</attribute>

<attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">

<desc>

Array of medium objects known to this VirtualBox installation.

This array contains only base media. All differencing

media of the given base medium can be enumerated using

<link to="IMedium::children"/>.

</desc>

</attribute>

<attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">

<desc>

Array of CD/DVD image objects currently in use by this VirtualBox instance.

</desc>

</attribute>

<attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">

<desc>

Array of floppy image objects currently in use by this VirtualBox instance.

</desc>