<?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,

the VBoxManage command-line interface and the VBoxVRDP server) 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

#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_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

#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

#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

</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, <tt>NULL</tt>). 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="TSBool"

uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"

>

<desc>

Boolean variable having a third state, default.

</desc>

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

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

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

</enum>

<enum

name="MachineState"

uuid="73bf04d0-7c4f-4684-9abf-d65a9ad74343"

>

<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::attachHardDisk2()"/>).

<pre>

+-----------------------------------(same sate 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 and performing one of the "discard..."

operations, respectively.

<pre>

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

| |

+-&gt; PoweredOff --+ |

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

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

+-&gt; PoweredOff --+

| |

| Aborted -----+--&gt;[discardSnapshot() ]-------------&gt; Discarding --+

| | [discardCurrentState()] |

+-&gt; Saved -------+ [discardCurrentSnapshotAndState()] |

| |

+---(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

<tt>true</tt>. The same relates to transient states for which

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

<tt>true</tt>.

</note>

</desc>

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

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

</const>

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

<desc>

The machine is not running.

</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.

</desc>

</const>

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

<desc>

The process running the machine has terminated abnormally.

</desc>

</const>

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

<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.

</note>

</desc>

</const>

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

<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.

</note>

</desc>

</const>

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

<desc>

Execution of the machine has reached the "Guru Meditation"

condition.

</desc>

</const>

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

<desc>

Machine is being started after powering it on from a

zero execution state.

</desc>

</const>

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

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

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

<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="Discarding" value="11">

<desc>

Snapshot of the machine is being discarded.

</desc>

</const>

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

<desc>

Lengthy setup operation is in progress.

</desc>

</const>

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

<desc>

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

</desc>

</const>

<const name="LastOnline" value="10" wsmap="suppress"> <!-- Restoring -->

<desc>

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

</desc>

</const>

<const name="FirstTransient" value="7" wsmap="suppress"> <!-- Starting -->

<desc>

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

</desc>

</const>

<const name="LastTransient" value="12" 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. See individual enumerator descriptions for the meaning for

every value.

</desc>

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

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

</const>

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

<desc>

The machine has no open sessions (<link to="IMachine::sessionState"/>);

the session is closed (<link to="ISession::state"/>)

</desc>

</const>

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

<desc>

The machine has an open direct session (<link to="IMachine::sessionState"/>);

the session is open (<link to="ISession::state"/>)

</desc>

</const>

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

<desc>

A new (direct) session is being opened for the machine

as a result of <link to="IVirtualBox::openRemoteSession()"/>

call (<link to="IMachine::sessionState"/>);

the session is currently being opened

as a result of <link to="IVirtualBox::openRemoteSession()"/>

call (<link to="ISession::state"/>)

</desc>

</const>

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

<desc>

The direct session is being closed (<link to="IMachine::sessionState"/>);

the session is being closed (<link to="ISession::state"/>)

</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="Direct" value="1">

<desc>

Direct session

(opened by <link to="IVirtualBox::openSession()"/>)

</desc>

</const>

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

<desc>

Remote session

(opened by <link to="IVirtualBox::openRemoteSession()"/>)

</desc>

</const>

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

<desc>

Existing session

(opened by <link to="IVirtualBox::openExistingSession()"/>)

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

uuid="715984a5-093c-43bb-aa42-a16ed16828dd"

>

<desc>Interface bus type for storage devices.</desc>

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

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

</const>

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

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

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

uuid="aa7c1d71-aafe-47a8-9608-27d2d337cf55"

>

<desc>

Statistics type for <link to="IGuest::getStatistic"/>.

</desc>

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

<desc>

Idle CPU load (0-100%) for last interval.

</desc>

</const>

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

<desc>

Kernel CPU load (0-100%) for last interval.

</desc>

</const>

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

<desc>

User CPU load (0-100%) for last interval.

</desc>

</const>

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

<desc>

Total number of threads in the system.

</desc>

</const>

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

<desc>

Total number of processes in the system.

</desc>

</const>

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

<desc>

Total number of handles in the system.

</desc>

</const>

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

<desc>

Memory load (0-100%).

</desc>

</const>

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

<desc>

Total physical memory in megabytes.

</desc>

</const>

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

<desc>

Free physical memory in megabytes.

</desc>

</const>

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

<desc>

Ballooned physical memory in megabytes.

</desc>

</const>

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

<desc>

Total amount of memory in the committed state in megabytes.

</desc>

</const>

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

<desc>

Total amount of memory used by the guest OS's kernel in megabytes.

</desc>

</const>

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

<desc>

Total amount of paged memory used by the guest OS's kernel in megabytes.

</desc>

</const>

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

<desc>

Total amount of non-paged memory used by the guest OS's kernel in megabytes.

</desc>

</const>

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

<desc>

Total amount of memory used by the guest OS's system cache in megabytes.

</desc>

</const>

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

<desc>

Pagefile size in megabytes.

</desc>

</const>

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

<desc>

Statistics sample number

</desc>

</const>

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

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

uuid="445330e3-202a-4dab-854f-ce22e6cb9715"

>

<desc>

IDE controller type.

</desc>

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

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

</const>

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

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

</enum>

<enum

name="DriveState"

uuid="cb7233b7-c519-42a5-8310-1830953cacbc"

>

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

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

</const>

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

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

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

</enum>

<enum

name="ProcessorFeature"

uuid="b8353b35-705d-4796-9967-ebfb7ba54af4"

>

<desc>

CPU features.

</desc>

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

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

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

</enum>

<!--

<interface

name="IVirtualBoxErrorInfo" extends="$errorinfo"

uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"

supportsErrorInfo="no"

wsmap="suppress"

>

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

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

<desc>

UUID of the interface that defined the error.

<note>

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

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="IVirtualBoxCallback" extends="$unknown"

uuid="5516cc08-fb81-47a6-b184-031e7bbd2997"

wsmap="suppress"

>

<method name="onMachineStateChange">

<desc>

The execution state of the given machine has changed.

<see>IMachine::state</see>

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the machine this event relates to.</desc>

</param>

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

<desc>New execution state.</desc>

</param>

</method>

<method name="onMachineDataChange">

<desc>

Any of the settings of the given machine has changed.

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the machine this event relates to.</desc>

</param>

</method>

<method name="onExtraDataCanChange">

<desc>

Notification when someone tries to change extra data for

either the given machine or (if null) global extra data.

This gives the chance to veto against changes.

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>

ID of the machine this event relates to

(null ID for global extra data change requests).

</desc>

</param>

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

<desc>

Extra data key for the attempted write.

</desc>

</param>

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

<desc>

Extra data value for the given key.

</desc>

</param>

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

<desc>

Optional error message describing the reason of the

veto (ignored if this notification returns @c true).

</desc>

</param>

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

<desc>

Flag to indicate whether the callee agrees (@c true)

or vetoes against the change (@c false).

</desc>

</param>

</method>

<method name="onExtraDataChange">

<desc>

Notification when machine specific or global extra data

has changed.

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>

ID of the machine this event relates to.

Null for global extra data changes.

</desc>

</param>

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

<desc>

Extra data key that has changed.

</desc>

</param>

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

<desc>

Extra data value for the given key.

</desc>

</param>

</method>

<method name="onMediaRegistered">

<desc>

The given media was registered or unregistered

within this VirtualBox installation.

The @a mediaType parameter describes what type of

media the specified @a mediaId refers to. Possible

values are:

<ul>

<li><link to="DeviceType_HardDisk"/>: the media is a hard disk

that, if registered, can be obtained using the

<link to="IVirtualBox::getHardDisk2()"/> call.</li>

<li><link to="DeviceType_DVD"/>: the media is a CD/DVD image

that, if registered, can be obtained using the

<link to="IVirtualBox::getDVDImage()"/> call.</li>

<li><link to="DeviceType_Floppy"/>: the media is a Floppy image

that, if registered, can be obtained using the

<link to="IVirtualBox::getFloppyImage()"/> call.</li>

</ul>

Note that if this is a deregistration notification,

there is no way to access the object representing the

unregistered media. It is supposed that the

application will do required cleanup based on the @a

mediaId value.

</desc>

<param name="mediaId" type="uuid" dir="in">

<desc>ID of the media this event relates to.</desc>

</param>

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

<desc>Type of the media this event relates to.</desc>

</param>

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

<desc>

If true, the media was registered, otherwise it was

unregistered.

</desc>

</param>

</method>

<method name="onMachineRegistered">

<desc>

The given machine was registered or unregistered

within this VirtualBox installation.

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the machine this event relates to.</desc>

</param>

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

<desc>

If true, the machine was registered, otherwise it was

unregistered.

</desc>

</param>

</method>

<method name="onSessionStateChange">

<desc>

The state of the session for the given machine was changed.

<see>IMachine::sessionState</see>

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the machine this event relates to.</desc>

</param>

<param name="state" type="SessionState" dir="in">

<desc>New session state.</desc>

</param>

</method>

<method name="onSnapshotTaken">

<desc>

A new snapshot of the machine has been taken.

<see>ISnapshot</see>

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the machine this event relates to.</desc>

</param>

<param name="snapshotId" type="uuid" dir="in">

<desc>ID of the new snapshot.</desc>

</param>

</method>

<method name="onSnapshotDiscarded">

<desc>

Snapshot of the given machine has been discarded.

<note>

This notification is delivered <b>after</b> the snapshot

object has been uninitialized on the server (so that any

attempt to call its methods will return an error).

</note>

<see>ISnapshot</see>

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the machine this event relates to.</desc>

</param>

<param name="snapshotId" type="uuid" dir="in">

<desc>

ID of the discarded snapshot. <tt>null</tt> means the

current machine state has been discarded (restored from

the current snapshot).

</desc>

</param>

</method>

<method name="onSnapshotChange">

<desc>

Snapshot properties (name and/or description) have been changed.

<see>ISnapshot</see>

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the machine this event relates to.</desc>

</param>

<param name="snapshotId" type="uuid" dir="in">

<desc>ID of the changed snapshot.</desc>

</param>

</method>

<method name="onGuestPropertyChange">

<desc>

Notification when a guest property has changed.

</desc>

<param name="machineId" type="uuid" dir="in">

<desc>

ID of the machine this event relates to.

</desc>

</param>

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

<desc>

The name of the property that has changed.

</desc>

</param>

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

<desc>

The new property value.

</desc>

</param>

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

<desc>

The new property flags.

</desc>

</param>

</method>

</interface>

<interface

name="IVirtualBox" extends="$dispatched"

uuid="339abca2-f47a-4302-87f5-7bc324e6bbde"

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::machines2"/> 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="settingsFileVersion" type="wstring" readonly="yes">

<desc>

Current version of the format of the global VirtualBox settings file

(<tt>VirtualBox.xml</tt>).

The version string has the following format:

<pre>

x.y-platform

</pre>

where <tt>x</tt> and <tt>y</tt> are the major and the minor format

versions, and <tt>platform</tt> is the platform identifier.

The current version usually matches the value of the

<link to="#settingsFormatVersion"/> attribute unless the

settings file was created by an older version of VirtualBox and there

was a change of the settings file format since then.

Note that VirtualBox automatically converts settings files from older

versions to the most recent version when reading them (usually at

VirtualBox startup) but it doesn't save the changes back until

you call a method that implicitly saves settings (such as

<link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>

explicitly. Therefore, if the value of this attribute differs from the

value of <link to="#settingsFormatVersion"/>, then it

means that the settings file was converted but the result of the

conversion is not yet saved to disk.

The above feature may be used by interactive front-ends to inform users

about the settings file format change and offer them to explicitly save

all converted settings files (the global and VM-specific ones),

optionally create backup copies of the old settings files before saving,

etc.

<see>settingsFormatVersion, saveSettingsWithBackup()</see>

</desc>

</attribute>

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

<desc>

Most recent version of the settings file format.

The version string has the following format:

<pre>

x.y-platform

</pre>

where <tt>x</tt> and <tt>y</tt> are the major and the minor format

versions, and <tt>platform</tt> is the platform identifier.

VirtualBox uses this version of the format when saving settings files

(either as a result of method calls that require to save settings or as

a result of an explicit call to <link to="#saveSettings()"/>).

<see>settingsFileVersion</see>

</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="machines2" type="IMachine" readonly="yes" safearray="yes">

<desc>

Array of machine objects registered within this VirtualBox instance.

</desc>

</attribute>

<attribute name="hardDisks2" type="IHardDisk2" readonly="yes" safearray="yes">

<desc>

Array of hard disk objects known to this VirtualBox installation.

This array contains only base (root) hard disks. All differencing

hard disks of the given base hard disk can be enumerated using

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

</desc>

</attribute>

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

<desc>

Array of CD/DVD image objects registered with this VirtualBox instance.

</desc>

</attribute>

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

<desc>

Array of floppy image objects registered with this VirtualBox instance.

</desc>

</attribute>

<attribute name="progressOperations" type="IProgressCollection" readonly="yes"/>

<attribute name="guestOSTypes" type="IGuestOSTypeCollection" readonly="yes"/>

<attribute name="sharedFolders" type="ISharedFolderCollection" readonly="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>

<method name="createMachine">

<desc>

Creates a new virtual machine.

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>

You should specify valid name for the newly created machine when calling

this method. See the <link to="IMachine::name"/> attribute description

for more details about the machine name.

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.

Every machine has a <i>settings file</i> that is used to store

the machine configuration. This file is stored in a directory called the

<i>machine settings subfolder</i>. Both the settings subfolder and file

will have a name that corresponds to the name of the virtual machine.

You can specify where to create the machine setting subfolder using the

@a baseFolder argument. The base folder can be absolute (full path) or

relative to the <link to="IVirtualBox::homeFolder">VirtualBox home

directory</link>.

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

<link to="ISystemProperties::defaultMachineFolder">default machine

settings folder</link> will be used as a base folder for the created

machine. Otherwise the given base folder will be used. In either case,

the full path to the resulting settings file has the following

structure:

<pre>

&lt;base_folder&gt;/&lt;machine_name&gt;/&lt;machine_name&gt;.xml

</pre>

Note that if the resulting settings file already exists, this method

will fail with <link to="VBOX_E_FILE_ERROR"/>.

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

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

generated for every created machine.

<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 null.

</result>

</desc>

<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="baseFolder" type="wstring" dir="in">

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

</param>

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

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

</param>

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

<desc>Created machine object.</desc>

</param>

</method>

<method name="createLegacyMachine">

<desc>

Creates a new virtual machine in "legacy" mode, using the specified

settings file to store machine settings.

As opposed to machines created by <link to="#createMachine()"/>,

the settings file of the machine created in "legacy" mode is not

automatically renamed when the machine name is changed -- it will always

remain the same as specified in this method call.

The specified settings file name can be absolute (full path) or relative

to the <link to="IVirtualBox::homeFolder">VirtualBox home

directory</link>. If the file name doesn't contain an extension, the

default extension (.xml) will be appended.

Note that the configuration of the newly created machine is not

saved to disk (and therefore no settings file is created)

until <link to="IMachine::saveSettings()"/> is called. If the

specified settings file already exists, this method

will fail with <link to="VBOX_E_FILE_ERROR"/>..

See <link to="#createMachine()"/> for more information.

@deprecated This method may be removed later. Use <link

to="IVirtualBox::createMachine()"/> instead.

<note>

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

of the machine created in "legacy" mode.

</note>

<result name="VBOX_E_OBJECT_NOT_FOUND">

@a osTypeId is invalid.

</result>

<result name="VBOX_E_FILE_ERROR">

@a settingsFile 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 or @a settingsFile is empty or null.

</result>

</desc>

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

<desc>Machine name.</desc>

</param>

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

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

</param>

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

<desc>Name of the machine settings file.</desc>

</param>

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

<desc>Machine UUID (optional).</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 can be absolute

(full path) or relative to the <link to="IVirtualBox::homeFolder">

VirtualBox home directory</link>. This file must exist

and must be a valid machine settings file whose contents

will be used to construct the machine object.

@deprecated Will be removed soon.

<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

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="IVirtualBoxCallback::onMachineRegistered"/> signal is sent

to all registered callbacks.

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

<desc>

Attempts to find a virtual machine given its UUID.

To look up a machine by name, use <link to="IVirtualBox::findMachine" />

instead.

<result name="VBOX_E_OBJECT_NOT_FOUND">

Could not find registered machine matching @a id.

</result>

</desc>

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

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

</method>

<method name="findMachine">

<desc>

Attempts to find a virtual machine given its name.

To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />

instead.

<result name="VBOX_E_OBJECT_NOT_FOUND">

Could not find registered machine matching @a name.

</result>

</desc>

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

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

</method>

<method name="unregisterMachine">

<desc>

Unregisters the machine previously registered using

<link to="#registerMachine"/>. After successful method invocation, the

<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent

to all registered callbacks.

<note>

The specified machine must not be in the Saved state, have an open

(or a spawning) direct session associated with it, have snapshots or

have hard disks attached.

</note>

<note>

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

save all current machine settings before unregistering it.

</note>

<note>

If the given machine is inaccessible (see

<link to="IMachine::accessible"/>), it will be unregistered and

fully uninitialized right afterwards. As a result, the returned

machine object will be unusable and an attempt to call

<b>any</b> method will return the "Object not ready" error.

</note>

<result name="VBOX_E_OBJECT_NOT_FOUND">

Could not find registered machine matching @a id.

</result>

<result name="VBOX_E_INVALID_VM_STATE">

Machine is in Saved state.

</result>

<result name="VBOX_E_INVALID_OBJECT_STATE">

Machine has snapshot or open session or hard disk attached.

</result>

</desc>

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

<desc>UUID of the machine to unregister.</desc>

</param>

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

<desc>Unregistered machine object.</desc>

</param>

</method>

<method name="createHardDisk2">

<desc>

Creates a new base hard disk object that will use the given storage

format and location for hard disk 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 hard disk

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="IHardDisk2::createDynamicStorage()"/></li>

<li><link to="IHardDisk2::createFixedStorage()"/></li>

<li><link to="IHardDisk2::createDiffStorage()"/></li>

</ul>

Some hard disk attributes, such as <link to="IHardDisk2::id"/>, may

remain uninitialized until the hard disk storage unit is successfully

created by one of the above methods.

After the storage unit is successfully created, the hard disk gets

remembered by this VirtualBox installation and will be accessible

through <link to="#getHardDisk2()"/> and <link to="#findHardDisk2()"/>

methods. Remembered root (base) hard disks are also returned as part of

the <link to="#hardDisks2"/> array. See IHardDisk2 for more details.

The list of all storage formats supported by this VirtualBox

installation can be obtained using

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

attribute is empty or <tt>null</tt> then the default storage format

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

be used for creating a storage unit of the hard disk.

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

See <link to="IMedium::location"/>, IHardDisk2 and

<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.

<result name="VBOX_E_OBJECT_NOT_FOUND">

@a format identifier is invalid. See

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

</result>

<result name="VBOX_E_FILE_ERROR">

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

</result>

<result name="E_INVALIDARG">

@a format is a null or empty string.

</result>

</desc>

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

<desc>

Identifier of the storage format to use for the new hard disk.

</desc>

</param>

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

<desc>

Location of the storage unit for the new hard disk.

</desc>

</param>

<param name="hardDisk" type="IHardDisk2" dir="return">

<desc>Created hard disk object.</desc>

</param>

</method>

<method name="openHardDisk2">

<desc>

Opens a hard disk from an existing location.

After the hard disk is successfully opened by this method, it gets

remembered by (known to) this VirtualBox installation and will be

accessible through <link to="#getHardDisk2()"/> and

<link to="#findHardDisk2()"/> methods. Remembered root (base) hard disks

are also returned as part of the <link to="#hardDisks2"/> array and can

be attached to virtual machines. See IHardDisk2 for more details.

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

operation will succeed only if its parent hard disk and all ancestors,

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

were opened by this method before).

This method tries to guess the storage format of the specified hard disk

by reading hard disk data at the specified location.

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

See <link to="IMedium::location"/>, IHardDisk2 and

<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.

<result name="VBOX_E_FILE_ERROR">

Invalid hard disk storage file location.

</result>

<result name="VBOX_E_IPRT_ERROR">

Could not get hard disk storage format.

</result>

<result name="E_INVALIDARG">

Invalid hard disk storage format.

</result>

</desc>

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

<desc>

Location of the storage unit that contains hard disk data in one of

the supported storage formats.

</desc>

</param>

<param name="hardDisk" type="IHardDisk2" dir="return">

<desc>Opened hard disk object.</desc>

</param>

</method>

<method name="getHardDisk2" const="yes">

<desc>

Returns a hard disk with the given UUID.

The hard disk with the given UUID must be known to this VirtualBox

installation, i.e. it must be previously created by

<link to="#createHardDisk2()"/> or opened by <link

to="#openHardDisk2()"/>, or attached to some known virtual machine.

<result name="VBOX_E_OBJECT_NOT_FOUND">

No hard disk object matching @a id found.

</result>

</desc>

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

<desc>UUID of the hard disk to look for.</desc>

</param>

<param name="hardDisk" type="IHardDisk2" dir="return">

<desc>Found hard disk object.</desc>

</param>

</method>

<method name="findHardDisk2">

<desc>

Returns a hard disk that uses the given location to store hard

disk data.

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

it must be previously created by

<link to="#createHardDisk2()"/> or opened by <link

to="#openHardDisk2()"/>, or attached to some known virtual machine.

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

the <link to="IHardDisk2::location"/> attribute of each known hard

disk.

For locations represented by file names in the host's file system, the

requested location can be a path relative to the

<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If

only a file name without any path is given, the

<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk

folder</link> will be prepended to the file name before searching. Note

that 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 hard disk object matching @a location found.

</result>

</desc>

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

<desc>Location string to search for.</desc>

</param>

<param name="hardDisk" type="IHardDisk2" dir="return">

<desc>Found hard disk object.</desc>

</param>

</method>

<method name="openDVDImage">

<desc>

Opens a CD/DVD image contained in the specified file of the supported

format and assigns it the given UUID.

After the image is successfully opened by this method, it gets

remembered by (known to) this VirtualBox installation and will be

accessible through <link to="#getDVDImage()"/> and

<link to="#findDVDImage()"/> methods. Remembered images are also

returned as part of the <link to="#DVDImages"/> array and can be mounted

to virtual machines. See IMedium for more details.

See <link to="IMedium::location"/> to get more details about the format

of the location string.

<note>

Currently only ISO 9960 CD/DVD images are supported by VirtualBox.

</note>

<result name="VBOX_E_INVALID_OBJECT_STATE">

CD/DVD image already exists in the media registry.

</result>

</desc>

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

<desc>

Full path to the file that contains a valid CD/DVD image.

</desc>

</param>

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

<desc>

UUID to assign to the given image within this VirtualBox installation.

If an empty (null) UUID is specified, the system will randomly

generate a new UUID.

</desc>

</param>

<param name="image" type="IDVDImage2" dir="return">

<desc>Opened CD/DVD image object.</desc>

</param>

</method>

<method name="getDVDImage">

<desc>

Returns a CD/DVD image with the given UUID.

The image with the given UUID must be known to this VirtualBox

installation, i.e. it must be previously opened by <link

to="#openDVDImage()"/>, or mounted to some known virtual machine.

<result name="VBOX_E_OBJECT_NOT_FOUND">

No matching DVD image found in the media registry.

</result>

</desc>

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

<desc>UUID of the image to look for.</desc>

</param>

<param name="image" type="IDVDImage2" dir="return">

<desc>Found CD/DVD image object.</desc>

</param>

</method>

<method name="findDVDImage">

<desc>

Returns a CD/DVD image with the given image location.

The image with the given UUID must be known to this VirtualBox

installation, i.e. it must be previously opened by <link

to="#openDVDImage()"/>, or mounted to some known virtual machine.

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

the <link to="IMedium::location"/> attribute of each known CD/DVD image.

The requested location can be a path relative to the

<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If

only a file name without any path is given, the

<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk

folder</link> will be prepended to the file name before searching. Note

that on case sensitive file systems, a case sensitive comparison is

performed, otherwise the case in the file path is ignored.

<result name="VBOX_E_FILE_ERROR">

Invalid image file location.

</result>

<result name="VBOX_E_OBJECT_NOT_FOUND">

No matching DVD image found in the media registry.

</result>

</desc>

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

<desc>CD/DVD image file path to look for.</desc>

</param>

<param name="image" type="IDVDImage2" dir="return">

<desc>Found CD/DVD image object.</desc>

</param>

</method>

<method name="openFloppyImage">

<desc>

Opens a floppy image contained in the specified file of the supported

format and assigns it the given UUID.

After the image is successfully opened by this method, it gets

remembered by (known to) this VirtualBox installation and will be

accessible through <link to="#getFloppyImage()"/> and

<link to="#findFloppyImage()"/> methods. Remembered images are also

returned as part of the <link to="#floppyImages"/> array and can be

mounted to virtual machines. See IMedium for more details.

See <link to="IMedium::location"/> to get more details about the format

of the location string.

<result name="VBOX_E_FILE_ERROR">

Floppy image specified by @a location not accessible.

</result>

<result name="VBOX_E_INVALID_OBJECT_STATE">

Floppy image already exists in the media registry.

</result>

<note>

Currently, only raw floppy images are supported by VirtualBox.

</note>

</desc>

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

<desc>

Full path to the file that contains a valid floppy image.

</desc>

</param>

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

<desc>

UUID to assign to the given image file within this VirtualBox

installation. If an empty (null) UUID is specified, the system will

randomly generate a new UUID.

</desc>

</param>

<param name="image" type="IFloppyImage2" dir="return">

<desc>Opened floppy image object.</desc>

</param>

</method>

<method name="getFloppyImage">

<desc>

Returns a floppy image with the given UUID.

The image with the given UUID must be known to this VirtualBox

installation, i.e. it must be previously opened by <link

to="#openFloppyImage()"/>, or mounted to some known virtual machine.

<result name="VBOX_E_OBJECT_NOT_FOUND">

No matching floppy image found in the media registry.

</result>

</desc>

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

<desc>UUID of the image to look for.</desc>

</param>

<param name="image" type="IFloppyImage2" dir="return">

<desc>Found floppy image object.</desc>

</param>

</method>

<method name="findFloppyImage">

<desc>

Returns a floppy image with the given image location.

The image with the given UUID must be known to this VirtualBox

installation, i.e. it must be previously opened by <link

to="#openFloppyImage()"/>, or mounted to some known virtual machine.

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

the <link to="IMedium::location"/> attribute of each known floppy image.

The requested location can be a path relative to the

<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If

only a file name without any path is given, the

<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk

folder</link> will be prepended to the file name before searching. Note

that 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_FILE_ERROR">

Invalid image file location.

</result>

<result name="VBOX_E_OBJECT_NOT_FOUND">

No matching floppy image found in the media registry.

</result>

</desc>

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

<desc>Floppy image file path to look for.</desc>

</param>

<param name="image" type="IFloppyImage2" dir="return">

<desc>Found floppy image object.</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="wstring" 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>

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

<desc>

Returns the global extra data key name following the supplied key.

An error is returned if the supplied @a key does not exist. @c NULL is

returned in @a nextKey if the supplied key is the last key. When

supplying @c NULL for the @a key, the first key item is returned in @a

nextKey (if there is any). @a nextValue is an optional parameter and

if supplied, the next key's value is returned in it.

<result name="VBOX_E_OBJECT_NOT_FOUND">

Extra data @a key not found.

</result>

</desc>

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

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

</param>

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

<desc>Name of the next data key.</desc>

</param>

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

<desc>Value of the next data key.</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 @c NULL 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 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 callbacks using the

<link to="IVirtualBoxCallback::onExtraDataCanChange()"/>

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

new value, the change will not be performed.

</note>

<note>

On success, the

<link to="IVirtualBoxCallback::onExtraDataChange()"/> notification

is called to inform all registered callbacks 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="openSession">

<desc>

Opens a new direct session with the given virtual machine.

A direct session acts as a local lock on the given VM.

There can be only one direct session open at a time for every

virtual machine, protecting the VM from being manipulated by

conflicting actions from different processes. Only after a

direct session has been opened, one can change all VM settings

and execute the VM in the process space of the session object.

Sessions therefore can be compared to mutex semaphores that

lock a given VM for modification and execution.

See <link to="ISession">ISession</link> for details.

<note>Unless you are writing a new VM frontend, you will not

want to execute a VM in the current process. To spawn a new

process that executes a VM, use

<link to="IVirtualBox::openRemoteSession" />

instead.</note>

Upon successful return, the session object can be used to

get access to the machine and to the VM console.

In VirtualBox terminology, the machine becomes "mutable" after

a session has been opened. Note that the "mutable" machine

object, on which you may invoke IMachine methods to change its

settings, will be a different object from the immutable IMachine

objects returned by various IVirtualBox methods. To obtain a

mutable IMachine object (upon which you can invoke settings methods),

use the <link to="ISession::machine" /> attribute.

One must always call <link to="ISession::close" /> to release the

lock on the machine, or the machine's state will eventually be

set to "Aborted".

In other words, to change settings on a machine, the following

sequence is typically performed:

<ol>

<li>Call this method (openSession) to have a machine locked for

the current session.</li>

<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>

<li>Change the settings of the machine.</li>

<li>Call <link to="IMachine::saveSettings" />.</li>

<li>Close the session by calling <link to="ISession::close()"/>.</li>

</ol>

<result name="E_UNEXPECTED">

Virtual machine not registered.

</result>

<result name="E_ACCESSDENIED">

Process not started by OpenRemoteSession.

</result>

<result name="VBOX_E_OBJECT_NOT_FOUND">

No matching virtual machine found.

</result>

<result name="VBOX_E_INVALID_OBJECT_STATE">

Session already open or being opened.

</result>

<result name="VBOX_E_VM_ERROR">

Failed to assign machine to session.

</result>

</desc>

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

<desc>

Session object that will represent the opened session after

successful method invocation. This object must not represent

the already open session.

<note>

This session will be automatically closed if the

VirtualBox server is terminated for some reason.

</note>

</desc>

</param>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the virtual machine to open a session with.</desc>

</param>

</method>

<method name="openRemoteSession">

<desc>

Spawns a new process that executes a virtual machine (called a

"remote session").

Opening a remote session causes the VirtualBox server to start a new

process that opens a direct session with the given VM. As a result, the

VM is locked by that direct session in the new process, preventing

conflicting changes from other processes. Since sessions act as locks

that such prevent conflicting changes, one cannot open a remote session

for a VM that already has another open session (direct or remote), or

is currently in the process of opening one (see <link

to="IMachine::sessionState"/>).

While the remote session still provides some level of control over the

VM execution to the caller (using the <link to="IConsole" /> interface),

not all VM settings are available for modification within the remote

session context.

This operation can take some time (a new VM is started in a new process,

for which memory and other resources need to be set up). Because of this,

an <link to="IProgress" /> is returned to allow the caller to wait for this

asynchronous operation to be completed. Until then, the remote session

object remains in the closed state, and accessing the machine or its

console through it is invalid. It is recommended to use

<link to="IProgress::waitForCompletion" /> or similar calls to wait for

completion.

As with all <link to="ISession" /> objects, it is recommended to call

<link to="ISession::close" /> on the local session object once openRemoteSession()

has been called. However, the session's state (see <link to="ISession::state" />)

will not return to "Closed" until the remote session has also closed (i.e.

until the VM is no longer running). In that case, however, the state of

the session will automatically change back to "Closed".

Currently supported session types (values of the @a type

argument) are:

<ul>

<li><tt>gui</tt>: VirtualBox Qt GUI session</li>

<li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>

</ul>

The @a environment argument is a string containing definitions of

environment variables in the following format:

@code

NAME[=VALUE]\n

NAME[=VALUE]\n

...

@endcode

where <tt>\\n</tt> is the new line character. These environment

variables will be appended to the environment of the VirtualBox server

process. If an environment variable exists both in the server process

and in this list, the value from this list takes precedence over the

server's variable. If the value of the environment variable is

omitted, this variable will be removed from the resulting environment.

If the environment string is @c null, the server environment is

inherited by the started process as is.

<see>openExistingSession</see>

<result name="E_UNEXPECTED">

Virtual machine not registered.

</result>

<result name="E_INVALIDARG">

Invalid session type @a type.

</result>

<result name="VBOX_E_OBJECT_NOT_FOUND">

No machine matching @a machineId found.

</result>

<result name="VBOX_E_INVALID_OBJECT_STATE">

Session already open or being opened.

</result>

<result name="VBOX_E_IPRT_ERROR">

Launching process for machine failed.

</result>

<result name="VBOX_E_VM_ERROR">

Failed to assign machine to session.

</result>

</desc>

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

<desc>

Session object that will represent the opened remote session

after successful method invocation (this object must not

represent an already open session).

</desc>

</param>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the virtual machine to open a session with.</desc>

</param>

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

<desc>

Type of the remote session (case sensitive).

</desc>

</param>

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

<desc>

Environment to pass to the opened session (may be @c null).

</desc>

</param>

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

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

</param>

</method>

<method name="openExistingSession">

<desc>

Opens a new remote session with the virtual machine for

which a direct session is already open.

The remote session provides some level of control over the VM

execution (using the IConsole interface) to the caller; however,

within the remote session context, not all VM settings are available

for modification.

As opposed to <link to="#openRemoteSession()"/>, the number of

remote sessions opened this way is not limited by the API

<note>

It is an error to open a remote session with the machine that

doesn't have an open direct session.

</note>

<result name="E_UNEXPECTED">

Virtual machine not registered.

</result>

<result name="VBOX_E_OBJECT_NOT_FOUND">

No machine matching @a machineId found.

</result>

<result name="VBOX_E_INVALID_OBJECT_STATE">

Session already open or being opened.

</result>

<result name="VBOX_E_INVALID_SESSION_STATE">

Direct session state not Open.

</result>

<result name="VBOX_E_VM_ERROR">

Failed to get console object from direct session or assign

machine to session.

</result>

<see>openRemoteSession</see>

</desc>

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

<desc>

Session object that will represent the open remote session

after successful method invocation. This object must not

represent an already open session.

<note>

This session will be automatically closed when the peer

(direct) session dies or gets closed.

</note>

</desc>

</param>

<param name="machineId" type="uuid" dir="in">

<desc>ID of the virtual machine to open a session with.</desc>

</param>

</method>

<method name="registerCallback">

<desc>

Registers a new global VirtualBox callback. The methods of the given

callback object will be called by VirtualBox when an appropriate

event occurs.

<result name="E_INVALIDARG">

Registering a @c NULL @a callback is pretty pointless, ain't it?

<!-- See if someone is actually reading this and objects :-) -->

</result>

</desc>

<param name="callback" type="IVirtualBoxCallback" dir="in">

<desc>Callback object to register.</desc>

</param>

</method>

<method name="unregisterCallback">

<desc>

Unregisters the previously registered global VirtualBox callback.

<result name="E_INVALIDARG">

Specified @a callback not registered.

</result>

</desc>

<param name="callback" type="IVirtualBoxCallback" dir="in">

<desc>Callback object to unregister.</desc>

</param>

</method>

<method name="waitForPropertyChange">

<desc>

Blocks the caller until any of the properties represented by the @a

what argument changes the value or until the given timeout interval

expires.

The @a what argument is a comma separated list of property masks that

describe properties the caller is interested in. The property mask is

a string in the following format:

<pre>

[[group.]subgroup.]name

</pre>

where @c name is the property name and @c group, @c subgroup are zero

or more property group specifiers. Each element (group or name) in

the property mask may be either a Latin string or an asterisk symbol

(@c "*") which is used to match any string for the given element. A

property mask that doesn't contain asterisk symbols represents a

single fully qualified property name.

Groups in the fully qualified property name go from more generic (the

left-most part) to more specific (the right-most part). The first

element is usually a name of the object the property belongs to. The

second element may be either a property name, or a child object name,

or an index if the preceding element names an object which is one of

many objects of the same type. This way, property names form a

hierarchy of properties. Here are some examples of property names:

<table>

<tr>

<td><tt>VirtualBox.version</tt></td>

<td><link to="IVirtualBox::version"/> property</td>

</tr>

<tr>

<td><tt>Machine.&lt;UUID&gt;.name</tt></td>

<td><link to="IMachine::name"/> property of the machine with the

given UUID</td>

</tr>

</table>

Most property names directly correspond to the properties of objects

(components) provided by the VirtualBox library and may be used to

track changes to these properties. However, there may be

pseudo-property names that don't correspond to any existing object's

property directly, as well as there may be object properties that

don't have a corresponding property name that is understood by this

method, and therefore changes to such properties cannot be

tracked. See individual object's property descriptions to get a

fully qualified property name that can be used with this method (if

any).

There is a special property mask @c "*" (i.e. a string consisting of a

single asterisk symbol) that can be used to match all properties.

Below are more examples of property masks:

<table>

<tr>

<td><tt>VirtualBox.*</tt></td>

<td>Track all properties of the VirtualBox object</td>

</tr>

<tr>

<td><tt>Machine.*.name</tt></td>

<td>Track changes to the <link to="IMachine::name"/> property of

all registered virtual machines</td>

</tr>

</table>

<note>

This function is not implemented in the current version of the

product.

</note>

</desc>

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

<desc>Comma separated list of property masks.</desc>

</param>

<param name="timeout" type="unsigned long" dir="in">

<desc>

Wait timeout in milliseconds.

Specify -1 for an indefinite wait.

</desc>

</param>

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

<desc>

Comma separated list of properties that have been changed and caused

this method to return to the caller.

</desc>

</param>

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

<desc>Reserved, not currently used.</desc>

</param>

</method>

<method name="saveSettings">

<desc>

Saves the global settings to the global settings file

(<link to="#settingsFilePath"/>).

This method is only useful for explicitly saving the global settings

file after it has been auto-converted from the old format to the most

recent format (see <link to="#settingsFileVersion"/> for details).

Normally, the global settings file is implicitly saved when a global

setting is changed.

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

</method>

<method name="saveSettingsWithBackup">

<desc>

Creates a backup copy of the global settings file

(<link to="#settingsFilePath"/>) in case of auto-conversion, and then

calls <link to="#saveSettings()"/>.

Note that the backup copy is created <b>only</b> if the settings file

auto-conversion took place (see <link to="#settingsFileVersion"/> for

details). Otherwise, this call is fully equivalent to

<link to="#saveSettings()"/> and no backup copying is done.

The backup copy is created in the same directory where the original

settings file is located. It is given the following file name:

<pre>

original.xml.x.y-platform.bak

</pre>

where <tt>original.xml</tt> is the original settings file name

(excluding path), and <tt>x.y-platform</tt> is the version of the old

format of the settings file (before auto-conversion).

If the given backup file already exists, this method will try to add the

<tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from

0 to 9) and copy it again until it succeeds. If all suffixes are

occupied, or if any other copy error occurs, this method will return a

failure.

If the copy operation succeeds, the @a bakFileName return argument will

receive a full path to the created backup file (for informational

purposes). Note that this will happen even if the subsequent

<link to="#saveSettings()"/> call performed by this method after the

copy operation, fails.

<note>

The VirtualBox API never calls this method. It is intended purely for

the purposes of creating backup copies of the settings files by

front-ends before saving the results of the automatically performed

settings conversion to disk.

</note>

<see>settingsFileVersion</see>

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

Could not copy the settings file.

</result>

</desc>

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

<desc>Full path to the created backup copy.</desc>

</param>

</method>

</interface>

<!--

<enumerator

name="IMachineEnumerator" type="IMachine"

uuid="1b554149-be0a-4465-9252-9ff8f420af55"

/>

<collection

name="IMachineCollection" type="IMachine" enumerator="IMachineEnumerator"

uuid="FD443EC1-3007-4F5B-9282-D72760A66916"

readonly="yes"

/>

<interface

name="IInternalMachineControl" extends="$unknown"

uuid="4042ddf2-93d3-4749-8517-dde3f17ea630"

internal="yes"

wsmap="suppress"

>

<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="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" dir="in"/>

</method>

<method name="detachUSBDevice">

<desc>

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

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

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

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

notification.

<note>

In the done = 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" 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 done = false the VM is announcing its

intentions, while when done = true the VM is reporting

what it has done.

<note>

In the done = 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="in">

<desc>

Progress object created by the VM process 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="success" type="boolean" dir="in">

<desc><tt>true</tt> to indicate success and <tt>false</tt>

otherwise.

</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 by the VM process to inform the server it wants to

take a snapshot.

<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="progress" type="IProgress" dir="in">

<desc>

Progress object created by the VM process to wait until

the state is saved (only for online snapshots).

</desc>

</param>

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

<desc>

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

</desc>

</param>

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

<desc>

Progress object created by the server process to wait until

the snapshot is taken (VDI diff creation, etc.).

</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><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>

</param>

</method>

<method name="discardSnapshot">

<desc>

Gets called by IConsole::discardSnapshot.

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

<desc>UUID of the snapshot to discard.</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="discardCurrentState">

<desc>

Gets called by IConsole::discardCurrentState.

<result name="VBOX_E_INVALID_OBJECT_STATE">

Virtual machine does not have any snapshot.

</result>

</desc>

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

<desc>The console object that initiated this call.</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="discardCurrentSnapshotAndState">

<desc>

Gets called by IConsole::discardCurrentSnapshotAndState.

<result name="VBOX_E_INVALID_OBJECT_STATE">

Virtual machine does not have any snapshot.

</result>

</desc>

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

<desc>The console object that initiated this call.</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="pullGuestProperties">

<desc>

Get the list of the guest properties matching a set of patterns along

with their values, time stamps and flags and give responsibility for

managing properties to the console.

</desc>

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

<desc>

The names of the properties returned.

</desc>

</param>

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

<desc>

The values of the properties returned. The array entries match the

corresponding entries in the @a name array.

</desc>

</param>

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

<desc>

The time stamps of the properties returned. The array entries match

the corresponding entries in the @a name array.

</desc>

</param>

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

<desc>

The flags of the properties returned. The array entries match the

corresponding entries in the @a name array.

</desc>

</param>

</method>

<method name="pushGuestProperties">

<desc>

Set the list of the guest properties matching a set of patterns along

with their values, time stamps and flags and return responsibility for

managing properties to IMachine.

</desc>

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

<desc>

The names of the properties.

</desc>

</param>

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

<desc>

The values of the properties. The array entries match the

corresponding entries in the @a name array.

</desc>

</param>

<param name="timestamp" type="unsigned long long" dir="in" safearray="yes">

<desc>

The time stamps of the properties. The array entries match

the corresponding entries in the @a name array.

</desc>

</param>

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

<desc>

The flags of the properties. The array entries match the

corresponding entries in the @a name array.

</desc>

</param>

</method>

<method name="pushGuestProperty">

<desc>

Update a single guest property in IMachine.

</desc>

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

<desc>

The name of the property to be updated.

</desc>

</param>

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

<desc>

The value of the property.

</desc>

</param>

<param name="timestamp" type="unsigned long long" dir="in">

<desc>

The timestamp of the property.

</desc>

</param>

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

<desc>

The flags of the property.

</desc>

</param>

</method>

</interface>

<interface

name="IBIOSSettings" extends="$unknown"

uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"

wsmap="managed"

>

<desc>

The IBIOSSettings interface represents BIOS settings of the virtual

machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.

</desc>

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

<desc>Fade in flag for BIOS logo animation.</desc>

</attribute>

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

<desc>Fade out flag for BIOS logo animation.</desc>

</attribute>

<attribute name="logoDisplayTime" type="unsigned long">

<desc>BIOS logo display time in milliseconds (0 = default).</desc>

</attribute>

<attribute name="logoImagePath" type="wstring">

<desc>Local file system path for external BIOS image.</desc>

</attribute>

<attribute name="bootMenuMode" type="BIOSBootMenuMode">

<desc>Mode of the BIOS boot device menu.</desc>

</attribute>

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

<desc>ACPI support flag.</desc>

</attribute>

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

<desc>

IO APIC support flag. If set, VirtualBox will provide an IO APIC

and support IRQs above 15.

</desc>

</attribute>

<attribute name="timeOffset" type="long long">

<desc>

Offset in milliseconds from the host system time. This allows for

guests running with a different system date/time than the host.

It is equivalent to setting the system date/time in the BIOS except

it is not an absolute value but a relative one. Guest Additions

time synchronization honors this offset.

</desc>

</attribute>

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

<desc>

PXE debug logging flag. If set, VirtualBox will write extensive

PXE trace information to the release log.

</desc>

</attribute>

<attribute name="IDEControllerType" type="IDEControllerType">

<desc>

Type of the virtual IDE controller. Depending on this value,

VirtualBox will provide different virtual IDE hardware

devices to the guest.

</desc>

</attribute>

</interface>

<interface

name="IMachine" extends="$unknown"

uuid="ea6fb7ea-1993-4642-b113-f29eb39e0df0"

wsmap="managed"

>

<desc>

The IMachine interface represents a virtual machine, or guest, created

in VirtualBox.

This interface is used in two contexts. First of all, a collection of

objects implementing this interface is stored in the

<link to="IVirtualBox::machines2"/> attribute which lists all the virtual

machines that are currently registered with this VirtualBox

installation. Also, once a session has been opened for the given virtual

machine (e.g. the virtual machine is running), the machine object

associated with the open session can be queried from the session object;

see <link to="ISession"/> for details.

The main role of this interface is to expose the settings of the virtual

machine and provide methods to change various aspects of the virtual

machine's configuration. For machine objects stored in the

<link to="IVirtualBox::machines2"/> collection, all attributes are

read-only unless explicitly stated otherwise in individual attribute

and method descriptions. In order to change a machine setting, a session

for this machine must be opened using one of

<link to="IVirtualBox::openSession"/>,

<link to="IVirtualBox::openRemoteSession"/> or

<link to="IVirtualBox::openExistingSession"/> methods. After the

session has been successfully opened, a mutable machine object needs to

be queried from the session object and then the desired settings changes

can be applied to the returned object using IMachine attributes and

methods. See the ISession interface description for more information

about sessions.

Note that the IMachine interface does not provide methods to control

virtual machine execution (such as start the machine, or power it

down) -- these methods are grouped in a separate IConsole

interface. Refer to the IConsole interface description to get more

information about this topic.

<see>ISession, IConsole</see>

</desc>

<attribute name="parent" type="IVirtualBox" readonly="yes">

<desc>Associated parent object.</desc>

</attribute>

<attribute name="accessible" type="boolean" readonly="yes">

<desc>

Whether this virtual machine is currently accessible or not.

The machine is considered to be inaccessible when:

<ul>

<li>It is a registered virtual machine, and

</li>

<li>Its settings file is inaccessible (for example, it is

located on a network share that is not accessible during

VirtualBox startup, or becomes inaccessible later, or if

the settings file can be read but is invalid).

</li>

</ul>

Otherwise, the value of this property is always <tt>true</tt>.

Every time this property is read, the accessibility state of

this machine is re-evaluated. If the returned value is |false|,

the <link to="#accessError"/> property may be used to get the

detailed error information describing the reason of

inaccessibility.

When the machine is inaccessible, only the following properties

can be used on it:

<ul>

<li><link to="#parent"/></li>

<li><link to="#id"/></li>

<li><link to="#settingsFilePath"/></li>

<li><link to="#accessible"/></li>

<li><link to="#accessError"/></li>

</ul>

An attempt to access any other property or method will return

an error.

The only possible action you can perform on an inaccessible

machine is to unregister it using the

<link to="IVirtualBox::unregisterMachine"/> call (or, to check

for the accessibility state once more by querying this

property).

<note>

In the current implementation, once this property returns

<tt>true</tt>, the machine will never become inaccessible

later, even if its settings file cannot be successfully

read/written any more (at least, until the VirtualBox

server is restarted). This limitation may be removed in

future releases.

</note>

</desc>

</attribute>

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

<desc>

Error information describing the reason of machine

inaccessibility.

Reading this property is only valid after the last call to

<link to="#accessible"/> returned <tt>false</tt> (i.e. the

machine is currently unaccessible). Otherwise, a null

IVirtualBoxErrorInfo object will be returned.

</desc>

</attribute>

<attribute name="name" type="wstring">

<desc>

Name of the virtual machine.

Besides being used for human-readable identification purposes

everywhere in VirtualBox, the virtual machine name is also used

as a name of the machine's settings file and as a name of the

subdirectory this settings file resides in. Thus, every time you

change the value of this property, the settings file will be

renamed once you call <link to="#saveSettings()"/> to confirm the

change. The containing subdirectory will be also renamed, but

only if it has exactly the same name as the settings file

itself prior to changing this property (for backward compatibility

with previous API releases). The above implies the following

limitations:

<ul>

<li>The machine name cannot be empty.</li>

<li>The machine name can contain only characters that are valid

file name characters according to the rules of the file

system used to store VirtualBox configuration.</li>

<li>You cannot have two or more machines with the same name

if they use the same subdirectory for storing the machine

settings files.</li>

<li>You cannot change the name of the machine if it is running,

or if any file in the directory containing the settings file

is being used by another running machine or by any other

process in the host operating system at a time when

<link to="#saveSettings()"/> is called.

</li>

</ul>

If any of the above limitations are hit, <link to="#saveSettings()"/>

will return an appropriate error message explaining the exact

reason and the changes you made to this machine will not be

saved.

<note>

For "legacy" machines created using the

<link to="IVirtualBox::createLegacyMachine()"/> call,

the above naming limitations do not apply because the

machine name does not affect the settings file name.

The settings file name remains the same as it was specified

during machine creation and never changes.

</note>

</desc>

</attribute>

<attribute name="description" type="wstring">

<desc>

Description of the virtual machine.

The description attribute can contain any text and is

typically used to describe the hardware and software

configuration of the virtual machine in detail (i.e. network

settings, versions of the installed software and so on).

</desc>

</attribute>

<attribute name="id" type="uuid" readonly="yes">

<desc>UUID of the virtual machine.</desc>

</attribute>

<attribute name="OSTypeId" type="wstring">

<desc>

User-defined identifier of the Guest OS type.

You may use <link to="IVirtualBox::getGuestOSType"/> to obtain

an IGuestOSType object representing details about the given

Guest OS type.

<note>

This value may differ from the value returned by

<link to="IGuest::OSTypeId"/> if Guest Additions are

installed to the guest OS.

</note>

</desc>

</attribute>

<attribute name="HardwareVersion" type="wstring">

<desc>Hardware version identifier. Internal use only for now.</desc>

</attribute>

<attribute name="CPUCount" type="unsigned long">

<desc>Number of virtual CPUs in the VM. In the current version of the product, this is always 1.</desc>

</attribute>

<attribute name="memorySize" type="unsigned long">

<desc>System memory size in megabytes.</desc>

</attribute>

<attribute name="memoryBalloonSize" type="unsigned long">

<desc>Initial memory balloon size in megabytes.</desc>

</attribute>

<attribute name="statisticsUpdateInterval" type="unsigned long">

<desc>Initial interval to update guest statistics in seconds.</desc>

</attribute>

<attribute name="VRAMSize" type="unsigned long">

<desc>Video memory size in megabytes.</desc>

</attribute>

<attribute name="accelerate3DEnabled" type="boolean" default="false">

<desc>

This setting determines whether VirtualBox allows guests to make use

of the 3D graphics support available on the host. Currently limited

to OpenGL only. </desc>

</attribute>

<attribute name="monitorCount" type="unsigned long">

<desc>

Number of virtual monitors.

<note>

Only effective on Windows XP and later guests with

Guest Additions installed.

</note>

</desc>

</attribute>

<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">

<desc>Object containing all BIOS settings.</desc>

</attribute>

<attribute name="HWVirtExEnabled" type="TSBool">

<desc>

This setting determines whether VirtualBox will try to make use of

the host CPU's hardware virtualization extensions such as Intel VT-x

and AMD-V. Note that in case such extensions are not available,

they will not be used.

</desc>

</attribute>

<attribute name="HWVirtExNestedPagingEnabled" type="boolean" default="false">

<desc>

This setting determines whether VirtualBox will try to make use of

the nested paging extension of Intel VT-x and AMD-V. Note that in case

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

</desc>

</attribute>

<attribute name="HWVirtExVPIDEnabled" type="boolean" default="false">

<desc>

This setting determines whether VirtualBox will try to make use of

the VPID extension of Intel VT-x. Note that in case such extensions are

not available, they will not be used.

</desc>

</attribute>

<attribute name="PAEEnabled" type="boolean" default="false">

<desc>