<?xml version="1.0" ?>

<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). Note that 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.11", 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 oter setting or perform a modifying operation during this time

will result in the <link to="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 that 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).

</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="d2de270c-1d4b-4c9e-843f-bbb9b47269ff"

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="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>

</attribute>

<attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>

<attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>

<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">

<desc>

Collection of global shared folders. Global shared folders are

available to all virtual machines.

New shared folders are added to the collection using

<link to="#createSharedFolder"/>. Existing shared folders can be

removed using <link to="#removeSharedFolder"/>.

<note>

In the current version of the product, global shared folders are not

implemented and therefore this collection is always empty.

</note>

</desc>

</attribute>

<attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">

<desc>

Associated performance collector object.

</desc>

</attribute>

<attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">

<desc>

DHCP servers.

</desc>

</attribute>

<attribute name="eventSource" type="IEventSource" readonly="yes">

<desc>

Event source for VirtualBox events.

</desc>

</attribute>

<attribute name="extensionPackManager" type="IExtPackManager" readonly="yes">

<desc>

The extension pack manager.

</desc>

</attribute>

<method name="composeMachineFilename">

<desc>

Returns a recommended full path of the settings file name for a new virtual

machine.

This API serves two purposes:

<ul>

<li>It gets called by <link to="#createMachine" /> if NULL is specified

for the @a settingsFile argument there, which means that API should use

a recommended default file name.</li>

<li>It can be called manually by a client software before creating a machine,

e.g. if that client wants to pre-create the machine directory to create

virtual hard disks in that directory together with the new machine

settings file. In that case, the file name should be stripped from the

full settings file path returned by this function to obtain the

machine directory.</li>

</ul>

See <link to="IMachine::name"/> and <link to="#createMachine"/> for more

details about the machine name.

If @a baseFolder is a @c null or empty string (which is recommended), the

default machine settings folder

(see <link to="ISystemProperties::defaultMachineFolder" />) will be used as

a base folder for the created machine, resulting in a file name like

"/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder

will be used.

This method does not access the host disks. In particular, it does not check

for whether a machine of this name already exists.

</desc>

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

<desc>Suggested machine name.</desc>

</param>

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

<desc>Base machine folder (optional).</desc>

</param>

<param name="file" type="wstring" dir="return">

<desc>Fully qualified path where the machine would be created.</desc>

</param>

</method>

<method name="createMachine">

<desc>

Creates a new virtual machine by creating a machine settings file at

the given location.

VirtualBox machine settings files use a custom XML dialect. Starting

with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced,

and machine files can be created at arbitrary locations.

However, it is is recommended that machines be created in the default

machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see

<link to="ISystemProperties::defaultMachineFolder" />). If you specify

NULL for the @a settingsFile argument, <link to="#composeMachineFilename" />

is called automatically to have such a recommended name composed based

on the machine name given in the @a name argument.

If the resulting settings file already exists, this method will fail,

unless @a forceOverwrite is set.

The new machine is created unregistered, with the initial configuration

set according to the specified guest OS type. A typical sequence of

actions to create a new virtual machine is as follows:

<ol>

<li>

Call this method to have a new machine created. The returned machine

object will be "mutable" allowing to change any machine property.

</li>

<li>

Configure the machine using the appropriate attributes and methods.

</li>

<li>

Call <link to="IMachine::saveSettings" /> to write the settings

to the machine's XML settings file. The configuration of the newly

created machine will not be saved to disk until this method is

called.

</li>

<li>

Call <link to="#registerMachine" /> to add the machine to the list

of machines known to VirtualBox.

</li>

</ol>

The specified guest OS type identifier must match an ID of one of known

guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>

array.

Optionally, you may specify an UUID of to assign to the created machine.

However, this is not recommended and you should normally pass an empty

(@c null) UUID to this method so that a new UUID will be automatically

generated for every created machine. You can use UUID

00000000-0000-0000-0000-000000000000 as @c null value.

<note>

There is no way to change the name of the settings file or

subfolder of the created machine directly.

</note>

<result name="VBOX_E_OBJECT_NOT_FOUND">

@a osTypeId is invalid.

</result>

<result name="VBOX_E_FILE_ERROR">

Resulting settings file name is invalid or the settings file already

exists or could not be created due to an I/O error.

</result>

<result name="E_INVALIDARG">

@a name is empty or @c null.

</result>

</desc>

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

<desc>Fully qualified path where the settings file should be created,

or NULL for a default folder and file based on the @a name argument

(see <link to="#composeMachineFilename" />).</desc>

</param>

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

<desc>Machine name.</desc>

</param>

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

<desc>Guest OS Type ID.</desc>

</param>

<param name="id" type="uuid" mod="string" dir="in">

<desc>Machine UUID (optional).</desc>

</param>

<param name="forceOverwrite" type="boolean" dir="in">

<desc>If true, an existing machine settings file will be overwritten.</desc>

</param>

<param name="machine" type="IMachine" dir="return">

<desc>Created machine object.</desc>

</param>

</method>

<method name="openMachine">

<desc>

Opens a virtual machine from the existing settings file.

The opened machine remains unregistered until you call

<link to="#registerMachine"/>.

The specified settings file name must be fully qualified.

The file must exist and be a valid machine XML settings file

whose contents will be used to construct the machine object.

<result name="VBOX_E_FILE_ERROR">

Settings file name invalid, not found or sharing violation.

</result>

</desc>

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

<desc>

Name of the machine settings file.

</desc>

</param>

<param name="machine" type="IMachine" dir="return">

<desc>Opened machine object.</desc>

</param>

<note>

<link to="IMachine::settingsModified"/> will return

@c false for the created machine, until any of machine settings

are changed.

</note>

</method>

<method name="registerMachine">

<desc>

Registers the machine previously created using

<link to="#createMachine"/> or opened using

<link to="#openMachine"/> within this VirtualBox installation. After

successful method invocation, the

<link to="IMachineRegisteredEvent"/> event is fired.

<note>

This method implicitly calls <link to="IMachine::saveSettings"/>

to save all current machine settings before registering it.

</note>

<result name="VBOX_E_OBJECT_NOT_FOUND">

No matching virtual machine found.

</result>

<result name="VBOX_E_INVALID_OBJECT_STATE">

Virtual machine was not created within this VirtualBox instance.

</result>

</desc>

<param name="machine" type="IMachine" dir="in"/>

</method>

<method name="findMachine">

<desc>

Attempts to find a virtual machine given its name or UUID.

<note>Inaccessible machines cannot be found by name, only by UUID, because their name

cannot safely be determined.</note>

<result name="VBOX_E_OBJECT_NOT_FOUND">

Could not find registered machine matching @a nameOrId.

</result>

</desc>

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

<desc>What to search for. This can either be the UUID or the name of a virtual machine.</desc>

</param>

<param name="machine" type="IMachine" dir="return">

<desc>Machine object, if found.</desc>

</param>

</method>

<method name="createAppliance">

<desc>

Creates a new appliance object, which represents an appliance in the Open Virtual Machine

Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export

machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.

</desc>

<param name="appliance" type="IAppliance" dir="return">

<desc>New appliance.</desc>

</param>

</method>

<method name="createHardDisk">

<desc>

Creates a new base medium object that will use the given storage

format and location for medium data.

Note that the actual storage unit is not created by this method. In

order to do it, and before you are able to attach the created medium

to virtual machines, you must call one of the following methods to

allocate a format-specific storage unit at the specified location:

<ul>

<li><link to="IMedium::createBaseStorage"/></li>

<li><link to="IMedium::createDiffStorage"/></li>

</ul>

Some medium attributes, such as <link to="IMedium::id"/>, may

remain uninitialized until the medium storage unit is successfully

created by one of the above methods.

After the storage unit is successfully created, it will be

accessible through the <link to="#findMedium"/> method and can

be found in the <link to="#hardDisks"/> array.

The list of all storage formats supported by this VirtualBox

installation can be obtained using

<link to="ISystemProperties::mediumFormats"/>. If the @a format

attribute is empty or @c null then the default storage format

specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will

be used for creating a storage unit of the medium.

Note that the format of the location string is storage format specific.

See <link to="IMedium::location"/> and IMedium for more details.

<result name="VBOX_E_OBJECT_NOT_FOUND">

@a format identifier is invalid. See

<link to="ISystemProperties::mediumFormats"/>.

</result>

<result name="VBOX_E_FILE_ERROR">

@a location is a not valid file name (for file-based formats only).

</result>

</desc>

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

<desc>

Identifier of the storage format to use for the new medium.

</desc>

</param>

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

<desc>

Location of the storage unit for the new medium.

</desc>

</param>

<param name="medium" type="IMedium" dir="return">

<desc>Created medium object.</desc>

</param>

</method>

<method name="openMedium">

<desc>

Opens a medium from an existing storage location.

Once a medium has been opened, it can be passed to other VirtualBox

methods, in particular to <link to="IMachine::attachDevice" />.

Depending on the given device type, the file at the storage location

must be in one of the media formats understood by VirtualBox:

<ul>

<li>With a "HardDisk" device type, the file must be a hard disk image

in one of the formats supported by VirtualBox (see

<link to="ISystemProperties::mediumFormats" />).

After this method succeeds, if the medium is a base medium, it

will be added to the <link to="#hardDisks"/> array attribute. </li>

<li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image.

After this method succeeds, the medium will be added to the

<link to="#DVDImages"/> array attribute.</li>

<li>With a "Floppy" device type, the file must be an RAW floppy image.

After this method succeeds, the medium will be added to the

<link to="#floppyImages"/> array attribute.</li>

</ul>

After having been opened, the medium can be found by the <link to="#findMedium"/>

method and can be attached to virtual machines. See <link to="IMedium" /> for more details.

The UUID of the newly opened medium will either be retrieved from the

storage location, if the format supports it (e.g. for hard disk images),

or a new UUID will be randomly generated (e.g. for ISO and RAW files).

If for some reason you need to change the medium's UUID, use

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

If a differencing hard disk medium is to be opened by this method, the

operation will succeed only if its parent medium and all ancestors,

if any, are already known to this VirtualBox installation (for example,

were opened by this method before).

This method attempts to guess the storage format of the specified medium

by reading medium data at the specified location.

If @a accessMode is ReadWrite (which it should be for hard disks and floppies),

the image is opened for read/write access and must have according permissions,

as VirtualBox may actually write status information into the disk's metadata

sections.

Note that write access is required for all typical hard disk usage in VirtualBox,

since VirtualBox may need to write metadata such as a UUID into the image.

The only exception is opening a source image temporarily for copying and

cloning (see <link to="IMedium::cloneTo" /> when the image will be closed

again soon.

The format of the location string is storage format specific. See

<link to="IMedium::location"/> and IMedium for more details.

<result name="VBOX_E_FILE_ERROR">

Invalid medium storage file location or could not find the medium

at the specified location.

</result>

<result name="VBOX_E_IPRT_ERROR">

Could not get medium storage format.

</result>

<result name="E_INVALIDARG">

Invalid medium storage format.

</result>

<result name="VBOX_E_INVALID_OBJECT_STATE">

Medium has already been added to a media registry.

</result>

</desc>

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

<desc>

Location of the storage unit that contains medium data in one of

the supported storage formats.

</desc>

</param>

<param name="deviceType" type="DeviceType" dir="in">

<desc>

Must be one of "HardDisk", "DVD" or "Floppy".

</desc>

</param>

<param name="accessMode" type="AccessMode" dir="in">

<desc>Whether to open the image in read/write or read-only mode. For

a "DVD" device type, this is ignored and read-only mode is always assumed.</desc>

</param>

<param name="medium" type="IMedium" dir="return">

<desc>Opened medium object.</desc>

</param>

</method>

<method name="findMedium">

<desc>

Returns a medium of the given type that uses the given fully qualified

location or UUID to store medium data.

The given medium must be known to this VirtualBox installation, i.e.

it must be previously created by <link to="#createHardDisk"/> or opened

by <link to="#openMedium"/>.

The search is done by comparing the value of the @a location argument to

the <link to="IMedium::location"/> and <link to="IMedium::id" />

attributes of each known medium.

On case sensitive file systems, a case sensitive comparison is performed,

otherwise the case of symbols in the file path is ignored.

<result name="VBOX_E_OBJECT_NOT_FOUND">

No medium object matching @a location found.

</result>

</desc>

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

<desc>What to search for. This can either be the UUID or the location string of an open medium.</desc>

</param>

<param name="type" type="DeviceType" dir="in">

<desc>Device type (must be HardDisk, DVD or Floppy)</desc>

</param>

<param name="medium" type="IMedium" dir="return">

<desc>Medium object, if found.</desc>

</param>

</method>

<method name="getGuestOSType">

<desc>

Returns an object describing the specified guest OS type.

The requested guest OS type is specified using a string which is a

mnemonic identifier of the guest operating system, such as

<tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a

particular virtual machine can be read or set using the

<link to="IMachine::OSTypeId"/> attribute.

The <link to="IVirtualBox::guestOSTypes"/> collection contains all

available guest OS type objects. Each object has an

<link to="IGuestOSType::id"/> attribute which contains an identifier of

the guest OS this object describes.

<result name="E_INVALIDARG">

@a id is not a valid Guest OS type.

</result>

</desc>

<param name="id" type="uuid" mod="string" dir="in">

<desc>Guest OS type ID string.</desc>

</param>

<param name="type" type="IGuestOSType" dir="return">

<desc>Guest OS type object.</desc>

</param>

</method>

<method name="createSharedFolder">

<desc>

Creates a new global shared folder by associating the given logical

name with the given host path, adds it to the collection of shared

folders and starts sharing it. Refer to the description of

<link to="ISharedFolder"/> to read more about logical names.

<note>

In the current implementation, this operation is not

implemented.

</note>

</desc>

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

<desc>Unique logical name of the shared folder.</desc>

</param>

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

<desc>Full path to the shared folder in the host file system.</desc>

</param>

<param name="writable" type="boolean" dir="in">

<desc>Whether the share is writable or readonly</desc>

</param>

<param name="automount" type="boolean" dir="in">

<desc>Whether the share gets automatically mounted by the guest

or not.</desc>

</param>

</method>

<method name="removeSharedFolder">

<desc>

Removes the global shared folder with the given name previously

created by <link to="#createSharedFolder"/> from the collection of

shared folders and stops sharing it.

<note>

In the current implementation, this operation is not

implemented.

</note>

</desc>

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

<desc>Logical name of the shared folder to remove.</desc>

</param>

</method>

<method name="getExtraDataKeys">

<desc>

Returns an array representing the global extra data keys which currently

have values defined.

</desc>

<param name="value" type="wstring" dir="return" safearray="yes">

<desc>Array of extra data keys.</desc>

</param>

</method>

<method name="getExtraData">

<desc>

Returns associated global extra data.

If the requested data @a key does not exist, this function will

succeed and return an empty string in the @a value argument.

<result name="VBOX_E_FILE_ERROR">

Settings file not accessible.

</result>

<result name="VBOX_E_XML_ERROR">

Could not parse the settings file.

</result>

</desc>

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

<desc>Name of the data key to get.</desc>

</param>

<param name="value" type="wstring" dir="return">

<desc>Value of the requested data key.</desc>

</param>

</method>

<method name="setExtraData">

<desc>

Sets associated global extra data.

If you pass @c null or empty string as a key @a value, the given @a key

will be deleted.

<note>

Before performing the actual data change, this method will ask all

registered event listener using the

<link to="IExtraDataCanChangeEvent"/>

notification for a permission. If one of the listeners refuses the

new value, the change will not be performed.

</note>

<note>

On success, the

<link to="IExtraDataChangedEvent"/> notification

is called to inform all registered listeners about a successful data

change.

</note>

<result name="VBOX_E_FILE_ERROR">

Settings file not accessible.

</result>

<result name="VBOX_E_XML_ERROR">

Could not parse the settings file.

</result>

<result name="E_ACCESSDENIED">

Modification request refused.

</result>

</desc>

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

<desc>Name of the data key to set.</desc>

</param>

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

<desc>Value to assign to the key.</desc>

</param>

</method>

<!--method name="createDHCPServerForInterface">

<method name="createDHCPServer">

<desc>

Creates a dhcp server settings to be used for the given internal network name

<result name="E_INVALIDARG">

Host network interface @a name already exists.

</result>

</desc>

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

<desc>server name</desc>

</param>

<param name="server" type="IDHCPServer" dir="return">

<desc>Dhcp server settings</desc>

</param>

</method>

<method name="findDHCPServerByNetworkName">

<desc>

Searches a dhcp server settings to be used for the given internal network name

<result name="E_INVALIDARG">

Host network interface @a name already exists.

</result>

</desc>

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

<desc>server name</desc>

</param>

<param name="server" type="IDHCPServer" dir="return">

<desc>Dhcp server settings</desc>

</param>

</method>

<!--method name="findDHCPServerForInterface">

<method name="removeDHCPServer">

<desc>

Removes the dhcp server settings

<result name="E_INVALIDARG">

Host network interface @a name already exists.

</result>

</desc>

<param name="server" type="IDHCPServer" dir="in">

<desc>Dhcp server settings to be removed</desc>

</param>

</method>

<method name="checkFirmwarePresent">

<desc>

Check if this VirtualBox installation has a firmware

of the given type available, either system-wide or per-user.

Optionally, this may return a hint where this firmware can be

downloaded from.

</desc>

<param name="firmwareType" type="FirmwareType" dir="in">

<desc>

Type of firmware to check.

</desc>

</param>

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

<desc>Expected version number, usually empty string (presently ignored).</desc>

</param>

<param name="url" type="wstring" dir="out">

<desc>

Suggested URL to download this firmware from.

</desc>

</param>

<param name="file" type="wstring" dir="out">

<desc>

Filename of firmware, only valid if result == TRUE.

</desc>

</param>

<param name="result" type="boolean" dir="return">

<desc>If firmware of this type and version is available.</desc>

</param>

</method>

</interface>

<!--

<enum

name="VFSType"

uuid="813999ba-b949-48a8-9230-aadc6285e2f2"

>

<desc>

Virtual file systems supported by VFSExplorer.

</desc>

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

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

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

<const name="WebDav" value="4" />

</enum>

<enum

name="VFSFileType"

uuid="714333cd-44e2-415f-a245-d378fa9b1242"

>

<desc>

File types known by VFSExplorer.

</desc>

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

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

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

<const name="Directory" value="4" />

<const name="DevBlock" value="5" />

<const name="File" value="6" />

<const name="SymLink" value="7" />

<const name="Socket" value="8" />

<const name="WhiteOut" value="9" />

</enum>

<interface

name="IVFSExplorer" extends="$unknown"

uuid="003d7f92-d38e-487f-b790-8c5e8631cb2f"

wsmap="managed"

>

<desc>

The VFSExplorer interface unifies access to different file system

types. This includes local file systems as well remote file systems like

S3. For a list of supported types see <link to="VFSType" />.

An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.

</desc>

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

<desc>Returns the current path in the virtual file system.</desc>

</attribute>

<attribute name="type" type="VFSType" readonly="yes">

<desc>Returns the file system type which is currently in use.</desc>

</attribute>

<method name="update">

<desc>Updates the internal list of files/directories from the

current directory level. Use <link to="#entryList" /> to get the full list

after a call to this method.</desc>

<param name="aProgress" type="IProgress" dir="return">

<desc>Progress object to track the operation completion.</desc>

</param>

</method>

<method name="cd">

<desc>Change the current directory level.</desc>

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

<desc>The name of the directory to go in.</desc>

</param>

<param name="aProgress" type="IProgress" dir="return">

<desc>Progress object to track the operation completion.</desc>

</param>

</method>

<method name="cdUp">

<desc>Go one directory upwards from the current directory level.</desc>

<param name="aProgress" type="IProgress" dir="return">

<desc>Progress object to track the operation completion.</desc>

</param>

</method>

<method name="entryList">

<desc>Returns a list of files/directories after a call to <link

to="#update" />. The user is responsible for keeping this internal

list up do date.</desc>

<param name="aNames" type="wstring" safearray="yes" dir="out">

<desc>The list of names for the entries.</desc>

</param>

<param name="aTypes" type="unsigned long" safearray="yes" dir="out">

<desc>The list of types for the entries.</desc>

</param>

<param name="aSizes" type="unsigned long" safearray="yes" dir="out">

<desc>The list of sizes (in bytes) for the entries.</desc>

</param>

<param name="aModes" type="unsigned long" safearray="yes" dir="out">

<desc>The list of file modes (in octal form) for the entries.</desc>

</param>

</method>

<method name="exists">

<desc>Checks if the given file list exists in the current directory

level.</desc>

<param name="aNames" type="wstring" safearray="yes" dir="in">

<desc>The names to check.</desc>

</param>

<param name="aExists" type="wstring" safearray="yes" dir="return">

<desc>The names which exist.</desc>

</param>

</method>

<method name="remove">

<desc>Deletes the given files in the current directory level.</desc>

<param name="aNames" type="wstring" safearray="yes" dir="in">

<desc>The names to remove.</desc>

</param>

<param name="aProgress" type="IProgress" dir="return">

<desc>Progress object to track the operation completion.</desc>

</param>

</method>

</interface>

<!--

<interface

name="IAppliance" extends="$unknown"

uuid="7b148032-4124-4f46-b56a-b48ac1273f5a"

wsmap="managed"

>

<desc>

Represents a platform-independent appliance in OVF format. An instance of this is returned

by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export

virtual machines within an appliance with VirtualBox.

The OVF standard suggests two different physical file formats:

<ol>

<li>If the appliance is distributed as a set of files, there must be at least one XML descriptor

file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If

this descriptor file references other files such as disk images, as OVF appliances typically

do, those additional files must be in the same directory as the descriptor file.</li>

<li>If the appliance is distributed as a single file, it must be in TAR format and have the

<tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor

files and optionally other files.

At this time, VirtualBox does not not yet support the packed (TAR) variant; support will

be added with a later version.</li>

</ol>

<b>Importing</b> an OVF appliance into VirtualBox as instances of

<link to="IMachine" /> involves the following sequence of API calls:

<ol>

<li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.

</li>

<li>On the new object, call <link to="#read" /> with the full path of the OVF file you

would like to import. So long as this file is syntactically valid, this will succeed

and fill the appliance object with the parsed data from the OVF file.

</li>

<li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the

contents of the IAppliance attributes accordingly. These can be inspected by a

VirtualBox front-end such as the GUI, and the suggestions can be displayed to the

user. In particular, the <link to="#virtualSystemDescriptions" /> array contains

instances of <link to="IVirtualSystemDescription" /> which represent the virtual

systems (machines) in the OVF, which in turn describe the virtual hardware prescribed

by the OVF (network and hardware adapters, virtual disk images, memory size and so on).

The GUI can then give the user the option to confirm and/or change these suggestions.

</li>

<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each

virtual system (machine) to override the suggestions made by the interpret() routine.

</li>

<li>Finally, call <link to="#importMachines" /> to create virtual machines in

VirtualBox as instances of <link to="IMachine" /> that match the information in the

virtual system descriptions. After this call succeeded, the UUIDs of the machines created

can be found in the <link to="#machines" /> array attribute.

</li>

</ol>

<b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:

<ol>

<li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create

an empty IAppliance object.

</li>

<li>For each machine you would like to export, call <link to="IMachine::export" />

with the IAppliance object you just created. Each such call creates one instance of

<link to="IVirtualSystemDescription" /> inside the appliance.

</li>

<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each

virtual system (machine) to override the suggestions made by the export() routine.

</li>

<li>Finally, call <link to="#write" /> with a path specification to have the OVF

file written.</li>

</ol>

</desc>

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

<desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or

the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or

<link to="#write" /> (for export).

This attribute is empty until one of these methods has been called.

</desc>

</attribute>

<attribute name="disks" type="wstring" readonly="yes" safearray="yes">

<desc>

Array of virtual disk definitions. One such description exists for each

disk definition in the OVF; each string array item represents one such piece of

disk information, with the information fields separated by tab (\\t) characters.

The caller should be prepared for additional fields being appended to

this string in future versions of VirtualBox and therefore check for

the number of tabs in the strings returned.

In the current version, the following eight fields are returned per string

in the array:

<ol>

<li>Disk ID (unique string identifier given to disk)</li>

<li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>

<li>Populated size (optional unsigned integer indicating the current size of the

disk; can be approximate; -1 if unspecified)</li>

<li>Format (string identifying the disk format, typically

"http://www.vmware.com/specifications/vmdk.html#sparse")</li>

<li>Reference (where to find the disk image, typically a file name; if empty,

then the disk should be created on import)</li>

<li>Image size (optional unsigned integer indicating the size of the image,

which need not necessarily be the same as the values specified above, since

the image may be compressed or sparse; -1 if not specified)</li>

<li>Chunk size (optional unsigned integer if the image is split into chunks;

presently unsupported and always -1)</li>

<li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>

</ol>

</desc>

</attribute>

<attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">

<desc> Array of virtual system descriptions. One such description is created

for each virtual system (machine) found in the OVF.

This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />

(for export) has been called.

</desc>

</attribute>

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

<desc>

Contains the UUIDs of the machines created from the information in this appliances. This is only

relevant for the import case, and will only contain data after a call to <link to="#importMachines" />

succeeded.

</desc>

</attribute>

<method name="read">

<desc>

Reads an OVF file into the appliance object.

This method succeeds if the OVF is syntactically valid and, by itself, without errors. The

mere fact that this method returns successfully does not mean that VirtualBox supports all

features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.

</desc>

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

<desc>

Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending

on whether the appliance is distributed as a set of files or as a single file, respectively).

</desc>

</param>

<param name="aProgress" type="IProgress" dir="return">

<desc>Progress object to track the operation completion.</desc>

</param>

</method>

<method name="interpret">

<desc>

Interprets the OVF data that was read when the appliance was constructed. After

calling this method, one can inspect the

<link to="#virtualSystemDescriptions" /> array attribute, which will then contain

one <link to="IVirtualSystemDescription" /> for each virtual machine found in

the appliance.

Calling this method is the second step of importing an appliance into VirtualBox;

see <link to="IAppliance" /> for an overview.

After calling this method, one should call <link to="#getWarnings" /> to find out

if problems were encountered during the processing which might later lead to

errors.

</desc>

</method>

<method name="importMachines">

<desc>

Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />

and other interfaces that match the information contained in the appliance as

closely as possible, as represented by the import instructions in the

<link to="#virtualSystemDescriptions" /> array.

Calling this method is the final step of importing an appliance into VirtualBox;

see <link to="IAppliance" /> for an overview.

Since importing the appliance will most probably involve copying and converting

disk images, which can take a long time, this method operates asynchronously and

returns an IProgress object to allow the caller to monitor the progress.

After the import succeeded, the UUIDs of the IMachine instances created can be

retrieved from the <link to="#machines" /> array attribute.

</desc>

<param name="aProgress" type="IProgress" dir="return">

<desc>Progress object to track the operation completion.</desc>

</param>

</method>

<method name="createVFSExplorer">

<desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>

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

<desc>The URI describing the file system to use.</desc>

</param>

<param name="aExplorer" type="IVFSExplorer" dir="return">

<desc></desc>

</param>

</method>

<method name="write">

<desc>

Writes the contents of the appliance exports into a new OVF file.

Calling this method is the final step of exporting an appliance from VirtualBox;

see <link to="IAppliance" /> for an overview.

Since exporting the appliance will most probably involve copying and converting

disk images, which can take a long time, this method operates asynchronously and

returns an IProgress object to allow the caller to monitor the progress.

</desc>

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

<desc>

Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";

future versions of VirtualBox may support additional formats.

</desc>

</param>

<param name="manifest" type="boolean" dir="in">

<desc>

Indicate if the optional manifest file (.mf) should be written. The manifest file

is used for integrity checks prior import.

</desc>

</param>

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

<desc>

Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending

on whether the appliance is distributed as a set of files or as a single file, respectively).

</desc>

</param>

<param name="progress" type="IProgress" dir="return">

<desc>Progress object to track the operation completion.</desc>

</param>

</method>

<method name="getWarnings">

<desc>Returns textual warnings which occurred during execution of <link to="#interpret" />.</desc>

<param name="aWarnings" type="wstring" dir="return" safearray="yes">

<desc></desc>

</param>

</method>

</interface>

<enum

name="VirtualSystemDescriptionType"

uuid="c0f8f135-3a1d-417d-afa6-b38b95a91f90"

>

<desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of

a configuration value.</desc>

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

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

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

<const name="Product" value="4" />

<const name="Vendor" value="5" />

<const name="Version" value="6" />

<const name="ProductUrl" value="7" />

<const name="VendorUrl" value="8" />

<const name="Description" value="9" />

<const name="License" value="10" />

<const name="Miscellaneous" value="11" />

<const name="CPU" value="12" />

<const name="Memory" value="13" />

<const name="HardDiskControllerIDE" value="14" />

<const name="HardDiskControllerSATA" value="15" />

<const name="HardDiskControllerSCSI" value="16" />

<const name="HardDiskControllerSAS" value="17" />

<const name="HardDiskImage" value="18" />

<const name="Floppy" value="19" />

<const name="CDROM" value="20" />

<const name="NetworkAdapter" value="21" />

<const name="USBController" value="22" />

<const name="SoundCard" value="23" />

</enum>

<enum

name="VirtualSystemDescriptionValueType"

uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"

>

<desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value

type to fetch.</desc>

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

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

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

<const name="ExtraConfig" value="4" />

</enum>

<interface

name="IVirtualSystemDescription" extends="$unknown"

uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"

wsmap="managed"

>

<desc>Represents one virtual system (machine) in an appliance. This interface is used in

the <link to="IAppliance::virtualSystemDescriptions" /> array. After

<link to="IAppliance::interpret" /> has been called, that array contains information

about how the virtual systems described in the OVF should best be imported into

VirtualBox virtual machines. See <link to="IAppliance" /> for the steps required to

import an OVF into VirtualBox.

</desc>

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

<desc>Return the number of virtual system description entries.</desc>

</attribute>

<method name="getDescription">

<desc>Returns information about the virtual system as arrays of instruction items. In each array, the

items with the same indices correspond and jointly represent an import instruction for VirtualBox.

The list below identifies the value sets that are possible depending on the

<link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,

the array item with the same index in @a aOvfValues[] will contain the original value as contained

in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]

will contain a suggested value to be used for VirtualBox. Depending on the description type,

the @a aExtraConfigValues[] array item may also be used.

<ul>

<li>

"OS": the guest operating system type. There must be exactly one such array item on import. The

corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.

This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding

item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF.

</li>

<li>

"Name": the name to give to the new virtual machine. There can be at most one such array item;

if none is present on import, then an automatic name will be created from the operating system

type. The corresponding item im @a aOvfValues[] will contain the suggested virtual machine name

from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox

<link to="IMachine" /> name that does not exist yet.

</li>

<li>

"Description": an arbitrary description.

</li>

<li>

"License": the EULA section from the OVF, if present. It is the responsibility of the calling

code to display such a license for agreement; the Main API does not enforce any such policy.

</li>

<li>

Miscellaneous: reserved for future use.

</li>

<li>

"CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.

</li>

<li>

"Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none

is present on import, then VirtualBox will set a meaningful default based on the operating system

type.

</li>

<li>

"HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.

An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify

the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox

writes into the OVF.

The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"

type can use to specify which hard disk controller a virtual disk should be connected to.

Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"

in traditional terminology, whereas the IDE storage controller that VirtualBox supports in

its virtual machines supports four channels (primary master, primary slave, secondary master,

secondary slave) and thus maps to two IDE controllers in the OVF sense.

</li>

<li>

"HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This

has no value in @a aOvfValues[] or @a aVBoxValues[].

The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).

</li>

<li>

"HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.

The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or

"LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller

whereas VirtualBox considers it a class of storage controllers of its own; see

<link to="StorageControllerType" />).

The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).

</li>

<li>

"HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an

arbitrary number of these items, one for each virtual disk image that accompanies the OVF.

The array item in @a aOvfValues[] will contain the file specification from the OVF file (without

a path since the image file should be in the same location as the OVF file itself), whereas the

item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the

hard disk image. This means that on import the image will be copied and converted from the

"ovf" location to the "vbox" location; on export, this will be handled the other way round.

The matching item in the @a aExtraConfigValues[] array must contain a string of the following

format: "controller=&lt;index&gt;;channel=&lt;c&gt;"

In this string, &lt;index&gt; must be an integer specifying the hard disk controller to connect

the image to. That number must be the index of an array item with one of the hard disk controller

types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).

In addition, &lt;c&gt; must specify the channel to use on that controller. For IDE controllers,

this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions

before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but

no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.

</li>

<li>

"CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same

attachment information as with "HardDiskImage" items.

</li>

<li>

"CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same

attachment information as with "HardDiskImage" items.

</li>

<li>

"NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware

for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string

of the "type=&lt;X&gt;" format, where &lt;X&gt; must be either "NAT" or "Bridged".

</li>

<li>

"USBController": a USB controller. There can be at most one such item. If and only if such an

item ispresent, USB support will be enabled for the new virtual machine.

</li>

<li>

"SoundCard": a sound card. There can be at most one such item. If and only if such an item is

present, sound support will be enabled for the new virtual machine. Note that the virtual

machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which

may be different from the virtual soundcard expected by the appliance.

</li>

</ul>

</desc>

<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">

<desc></desc>

</param>

<param name="aRefs" type="wstring" dir="out" safearray="yes">

<desc></desc>

</param>

<param name="aOvfValues" type="wstring" dir="out" safearray="yes">

<desc></desc>

</param>

<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">

<desc></desc>

</param>

<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">

<desc></desc>

</param>

</method>

<method name="getDescriptionByType">

<desc>This is the same as <link to="#getDescription" /> except that you can specify which types

should be returned.</desc>

<param name="aType" type="VirtualSystemDescriptionType" dir="in">

<desc></desc>

</param>

<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">

<desc></desc>

</param>

<param name="aRefs" type="wstring" dir="out" safearray="yes">

<desc></desc>

</param>

<param name="aOvfValues" type="wstring" dir="out" safearray="yes">

<desc></desc>

</param>

<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">

<desc></desc>

</param>

<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">

<desc></desc>

</param>

</method>

<method name="getValuesByType">

<desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which

value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible

values.</desc>

<param name="aType" type="VirtualSystemDescriptionType" dir="in">

<desc></desc>

</param>

<param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">

<desc></desc>

</param>

<param name="aValues" type="wstring" dir="return" safearray="yes">

<desc></desc>

</param>

</method>

<method name="setFinalValues">

<desc>

This method allows the appliance's user to change the configuration for the virtual

system descriptions. For each array item returned from <link to="#getDescription" />,

you must pass in one boolean value and one configuration value.

Each item in the boolean array determines whether the particular configuration item

should be enabled.

You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,

HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController

and SoundCard.

For the "vbox" and "extra configuration" values, if you pass in the same arrays

as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription(),

the configuration remains unchanged. Please see the documentation for getDescription()

for valid configuration values for the individual array item types. If the

corresponding item in the aEnabled array is @c false, the configuration value is ignored.

</desc>

<param name="aEnabled" type="boolean" dir="in" safearray="yes">

<desc></desc>

</param>

<param name="aVBoxValues" type="wstring" dir="in" safearray="yes">

<desc></desc>

</param>

<param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">

<desc></desc>

</param>

</method>

<method name="addDescription">

<desc>

This method adds an additional description entry to the stack of already

available descriptions for this virtual system. This is handy for writing

values which aren't directly supported by VirtualBox. One example would

be the License type of <link to="VirtualSystemDescriptionType" />.

</desc>

<param name="aType" type="VirtualSystemDescriptionType" dir="in">

<desc></desc>

</param>

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

<desc></desc>

</param>

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

<desc></desc>

</param>

</method>

</interface>

<!--

<interface

name="IInternalMachineControl" extends="$unknown"

uuid="8e723ab0-812c-5662-dd8e-7ebc89637acf"

internal="yes"

wsmap="suppress"

>

<method name="setRemoveSavedStateFile">

<desc>

Updates the flag whether the saved state file is removed on a

machine state change from Saved to PoweredOff.

</desc>

<param name="aRemove" type="boolean" dir="in"/>

</method>

<method name="updateState">

<desc>

Updates the VM state.

<note>

This operation will also update the settings file with the correct

information about the saved state file and delete this file from disk

when appropriate.

</note>

</desc>

<param name="state" type="MachineState" dir="in"/>

</method>

<method name="getIPCId">

<param name="id" type="wstring" dir="return"/>

</method>

<method name="beginPowerUp">

<desc>

Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and

gives it the progress object that should be part of any pending

<link to="IMachine::launchVMProcess"/> operations. The progress

object may be called back to reflect an early cancelation, so some care

have to be taken with respect to any cancelation callbacks. The console

object will call <link to="IInternalMachineControl::endPowerUp"/>

to signal the completion of the progress object.

</desc>

<param name="aProgress" type="IProgress" dir="in" />

</method>

<method name="endPowerUp">

<desc>

Tells VBoxSVC that <link to="IConsole::powerUp"/> has completed.

This method may query status information from the progress object it

received in <link to="IInternalMachineControl::beginPowerUp"/> and copy

it over to any in-progress <link to="IMachine::launchVMProcess"/>

call in order to complete that progress object.

</desc>

<param name="result" type="long" dir="in"/>

</method>

<method name="beginPoweringDown">

<desc>

Called by the VM process to inform the server it wants to

stop the VM execution and power down.

</desc>

<param name="progress" type="IProgress" dir="out">

<desc>

Progress object created by VBoxSVC to wait until

the VM is powered down.

</desc>

</param>

</method>

<method name="endPoweringDown">

<desc>

Called by the VM process to inform the server that powering

down previously requested by #beginPoweringDown is either

successfully finished or there was a failure.

<result name="VBOX_E_FILE_ERROR">

Settings file not accessible.

</result>

<result name="VBOX_E_XML_ERROR">

Could not parse the settings file.

</result>

</desc>

<param name="result" type="long" dir="in">

<desc>@c S_OK to indicate success.

</desc>

</param>

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

<desc>@c human readable error message in case of failure.

</desc>

</param>

</method>

<method name="runUSBDeviceFilters">

<desc>

Asks the server to run USB devices filters of the associated

machine against the given USB device and tell if there is

a match.

<note>

Intended to be used only for remote USB devices. Local

ones don't require to call this method (this is done

implicitly by the Host and USBProxyService).

</note>

</desc>

<param name="device" type="IUSBDevice" dir="in"/>

<param name="matched" type="boolean" dir="out"/>

<param name="maskedInterfaces" type="unsigned long" dir="out"/>

</method>

<method name="captureUSBDevice">

<desc>

Requests a capture of the given host USB device.

When the request is completed, the VM process will

get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>

notification.

</desc>

<param name="id" type="uuid" mod="string" dir="in"/>

</method>

<method name="detachUSBDevice">

<desc>

Notification that a VM is going to detach (@a done = @c false) or has

already detached (@a done = @c true) the given USB device.

When the @a done = @c true request is completed, the VM process will

get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>

notification.

<note>

In the @a done = @c true case, the server must run its own filters

and filters of all VMs but this one on the detached device

as if it were just attached to the host computer.

</note>

</desc>

<param name="id" type="uuid" mod="string" dir="in"/>

<param name="done" type="boolean" dir="in"/>

</method>

<method name="autoCaptureUSBDevices">

<desc>

Requests a capture all matching USB devices attached to the host.

When the request is completed, the VM process will

get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>

notification per every captured device.

</desc>

</method>

<method name="detachAllUSBDevices">

<desc>

Notification that a VM that is being powered down. The done

parameter indicates whether which stage of the power down

we're at. When @a done = @c false the VM is announcing its

intentions, while when @a done = @c true the VM is reporting

what it has done.

<note>

In the @a done = @c true case, the server must run its own filters

and filters of all VMs but this one on all detach devices as

if they were just attached to the host computer.

</note>

</desc>

<param name="done" type="boolean" dir="in"/>

</method>

<method name="onSessionEnd">

<desc>

Triggered by the given session object when the session is about

to close normally.

</desc>

<param name="session" type="ISession" dir="in">

<desc>Session that is being closed</desc>

</param>

<param name="progress" type="IProgress" dir="return">

<desc>

Used to wait until the corresponding machine is actually

dissociated from the given session on the server.

Returned only when this session is a direct one.

</desc>

</param>

</method>

<method name="beginSavingState">

<desc>

Called by the VM process to inform the server it wants to

save the current state and stop the VM execution.

</desc>

<param name="progress" type="IProgress" dir="out">

<desc>

Progress object created by VBoxSVC to wait until

the state is saved.

</desc>

</param>

<param name="stateFilePath" type="wstring" dir="out">

<desc>

File path the VM process must save the execution state to.

</desc>

</param>

</method>

<method name="endSavingState">

<desc>

Called by the VM process to inform the server that saving

the state previously requested by #beginSavingState is either

successfully finished or there was a failure.

<result name="VBOX_E_FILE_ERROR">

Settings file not accessible.

</result>

<result name="VBOX_E_XML_ERROR">

Could not parse the settings file.

</result>

</desc>

<param name="result" type="long" dir="in">

<desc>@c S_OK to indicate success.

</desc>

</param>

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

<desc>@c human readable error message in case of failure.

</desc>

</param>

</method>

<method name="adoptSavedState">

<desc>

Gets called by IConsole::adoptSavedState.

<result name="VBOX_E_FILE_ERROR">

Invalid saved state file path.

</result>

</desc>

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

<desc>Path to the saved state file to adopt.</desc>

</param>

</method>

<method name="beginTakingSnapshot">

<desc>

Called from the VM process to request from the server to perform the

server-side actions of creating a snapshot (creating differencing images

and the snapshot object).

<result name="VBOX_E_FILE_ERROR">

Settings file not accessible.

</result>

<result name="VBOX_E_XML_ERROR">

Could not parse the settings file.

</result>

</desc>

<param name="initiator" type="IConsole" dir="in">

<desc>The console object that initiated this call.</desc>

</param>

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

<desc>Snapshot name.</desc>

</param>

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

<desc>Snapshot description.</desc>

</param>

<param name="consoleProgress" type="IProgress" dir="in">

<desc>

Progress object created by the VM process tracking the

snapshot's progress. This has the following sub-operations:

<ul>

<li>setting up (weight 1);</li>

<li>one for each medium attachment that needs a differencing image (weight 1 each);</li>

<li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>

<li>another one to save the VM state (if online, weight is VM memory size in MB);</li>

<li>finishing up (weight 1)</li>

</ul>

</desc>

</param>

<param name="fTakingSnapshotOnline" type="boolean" dir="in">

<desc>

Whether this is an online snapshot (i.e. the machine is running).

</desc>

</param>

<param name="stateFilePath" type="wstring" dir="out">

<desc>

File path the VM process must save the execution state to.

</desc>

</param>

</method>

<method name="endTakingSnapshot">

<desc>

Called by the VM process to inform the server that the snapshot

previously requested by #beginTakingSnapshot is either

successfully taken or there was a failure.

</desc>

<param name="success" type="boolean" dir="in">

<desc>@c true to indicate success and @c false otherwise</desc>

</param>

</method>

<method name="deleteSnapshot">

<desc>

Gets called by IConsole::deleteSnapshot.

<result name="VBOX_E_INVALID_OBJECT_STATE">

Snapshot has more than one child snapshot.

</result>

</desc>

<param name="initiator" type="IConsole" dir="in">

<desc>The console object that initiated this call.</desc>

</param>

<param name="id" type="uuid" mod="string" dir="in">

<desc>UUID of the snapshot to delete.</desc>

</param>

<param name="machineState" type="MachineState" dir="out">

<desc>New machine state after this operation is started.</desc>

</param>

<param name="progress" type="IProgress" dir="return">

<desc>Progress object to track the operation completion.</desc>

</param>

</method>

<method name="finishOnlineMergeMedium">

<desc>

Gets called by IConsole::onlineMergeMedium.

</desc>

<param name="mediumAttachment" type="IMediumAttachment" dir="in">

<desc>The medium attachment which needs to be cleaned up.</desc>

</param>

<param name="source" type="IMedium" dir="in">

<desc>Merge source medium.</desc>

</param>

<param name="target" type="IMedium" dir="in">

<desc>Merge target medium.</desc>

</param>

<param name="mergeForward" type="boolean" dir="in">

<desc>Merge direction.</desc>

</param>

<param name="parentForTarget" type="IMedium" dir="in">

<desc>For forward merges: new parent for target medium.</desc>

</param>

<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">

<desc>For backward merges: list of media which need their parent UUID

updated.</desc>

</param>

</method>

<method name="restoreSnapshot">

<desc>

Gets called by IConsole::RestoreSnapshot.

</desc>

<param name="initiator" type="IConsole" dir="in">

<desc>The console object that initiated this call.</desc>

</param>

<param name="snapshot" type="ISnapshot" dir="in">

<desc>The snapshot to restore the VM state from.</desc>

</param>