<?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, @c null). Note that when pointers representing input

arguments (such as strings) are invalid, E_INVALIDARG is returned.

</td>

</tr>

<tr><td>E_ACCESSDENIED</td>

<td>

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

public COM object cannot be fully controlled by the implementation,

VirtualBox maintains the readiness state for all objects it creates and

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

deactivated by VirtualBox and is not functioning any more.

</td>

</tr>

<tr><td>E_OUTOFMEMORY</td>

<td>

Returned when a memory allocation operation fails.

</td>

</tr>

</table>

</desc>

</descGroup>

<!--

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

<desc>

Object corresponding to the supplied arguments does not exist.

</desc>

</result>

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

<desc>

Current virtual machine state prevents the operation.

</desc>

</result>

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

<desc>

Virtual machine error occurred attempting the operation.

</desc>

</result>

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

<desc>

File not accessible or erroneous file contents.

</desc>

</result>

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

<desc>

Runtime subsystem error.

</desc>

</result>

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

<desc>

Pluggable Device Manager error.

</desc>

</result>

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

<desc>

Current object state prohibits operation.

</desc>

</result>

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

<desc>

Host operating system related error.

</desc>

</result>

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

<desc>

Requested operation is not supported.

</desc>

</result>

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

<desc>

Invalid XML found.

</desc>

</result>

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

<desc>

Current session state prohibits operation.

</desc>

</result>

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

<desc>

Object being in use prohibits operation.

</desc>

</result>

<!--

<descGroup/>

<!--

<enum

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

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

>

<desc>

Access mode for opening files.

</desc>

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

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

</enum>

<enum

name="MachineState"

uuid="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::attachHardDisk"/>).

<pre>

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

| |

+-&gt; PoweredOff --+ |

| | |

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

| |

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

</pre>

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

powered off virtual machine and performing one of the "discard..."

operations, respectively.

<pre>

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

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

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

@c true.

</note>

</desc>

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

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

</const>

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

<desc>

The machine is not running.

</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="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="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="bcae7fc3-3fd0-4bac-923c-ec1596c7bc83"

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

<desc>

Result code of the error.

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

by the method that provided this error information, but not

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

likely return E_NOINTERFACE upon unsuccessful component

instantiation attempt, but not the value the component factory

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

to make interface usable from scripting languages.

<note>

In MS COM, there is no equivalent.

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

</note>

</desc>

</attribute>

<attribute name="interfaceID" type="uuid" 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="2990059f-5bc8-4635-8415-658917cd3186"

wsmap="suppress"

>

<method name="onMachineStateChange">

<desc>

The execution state of the given machine has changed.

<see>IMachine::state</see>

</desc>

<param name="machineId" type="wstring" 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="wstring" 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 @c null) global extra data.

This gives the chance to veto against changes.

</desc>

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

<desc>

ID of the machine this event relates to

(@c 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="wstring" 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::getHardDisk"/> 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="wstring" 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 @c 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="wstring" dir="in">

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

</param>

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

<desc>

If @c 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="wstring" 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="wstring" dir="in">

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

</param>

<param name="snapshotId" type="wstring" 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="wstring" dir="in">

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

</param>

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

<desc>

ID of the discarded snapshot. @c null 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="wstring" dir="in">

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

</param>

<param name="snapshotId" type="wstring" 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="wstring" 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="IDHCPServer" extends="$unknown"

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

wsmap="managed"

>

<desc>

The IDHCPServer interface represents the vbox dhcp server configuration.

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

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

</desc>

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

<desc>

specifies if the dhcp server is enabled

</desc>

</attribute>

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

<desc>

specifies server IP

</desc>

</attribute>

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

<desc>

specifies server network mask

</desc>

</attribute>

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

<desc>

specifies internal network name the server is used for

</desc>

</attribute>

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

<desc>

specifies from IP adrres in server address range

</desc>

</attribute>

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

<desc>

specifies to IP adrres in server address range

</desc>

</attribute>

<method name="setConfiguration">

<desc>

configures the server

<result name="E_INVALIDARG">

invalid configuration supplied

</result>

</desc>

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

<desc>

server IP address

</desc>

</param>

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

<desc>

server network mask

</desc>

</param>

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

<desc>

server From IP address for address range

</desc>

</param>

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

<desc>

server To IP address for address range

</desc>

</param>

</method>

<method name="start">

<desc>

Starts DHCP server process.

<result name="E_FAIL">

Failed to start the process.

</result>

</desc>

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

<desc>

Name of internal network DHCP server should attach to.

</desc>

</param>

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

<desc>

Name of internal network trunk.

</desc>

</param>

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

<desc>

Type of internal network trunk.

</desc>

</param>

</method>

<method name="stop">

<desc>

Stops DHCP server process.

<result name="E_FAIL">

Failed to stop the process.

</result>

</desc>

</method>

</interface>

<interface

name="IVirtualBox" extends="$dispatched"

uuid="3f4ab53a-199b-4526-a91a-93ff62e456b8"

wsmap="managed"

>

<desc>

The IVirtualBox interface represents the main interface exposed by the

product that provides virtual machine management.

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

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

IVirtualBox is implemented as a singleton and actually lives in the

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

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

host, regardless of which frontend started them.

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

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

</desc>

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

<desc>

A string representing the version number of the product. The

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

last number represents the build number and will frequently change.

</desc>

</attribute>

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

<desc>

The internal build revision number of the product.

</desc>

</attribute>

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

<desc>

A string representing the package type of this product. The

format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,

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

is either GENERIC, UBUNTU_606, UBUNTU_710, or something like

this.

</desc>

</attribute>

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

<desc>

Full path to the directory where the global settings file,

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

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

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

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

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

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

places where relative paths are allowed (unless otherwise

expressly indicated).

</desc>

</attribute>

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

<desc>

Full name of the global settings file.

The value of this property corresponds to the value of

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

</desc>

</attribute>

<attribute name="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 @c x and @c y are the major and the minor format

versions, and @c platform 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 @c x and @c y are the major and the minor format

versions, and @c platform 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="machines" type="IMachine" readonly="yes" safearray="yes">

<desc>

Array of machine objects registered within this VirtualBox instance.

</desc>

</attribute>

<attribute name="hardDisks" type="IHardDisk" 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="IHardDisk::children"/>.

</desc>

</attribute>

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

<desc>

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

</desc>

</attribute>

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

<desc>

Array of floppy image objects registered with this VirtualBox instance.

</desc>

</attribute>

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

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

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

<desc>

Collection of global shared folders. Global shared folders are

available to all virtual machines.

New shared folders are added to the collection using

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

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

<note>

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

implemented and therefore this collection is always empty.

</note>

</desc>

</attribute>

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

<desc>

Associated performance collector object.

</desc>

</attribute>

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

<desc>

dhcp server settings.

</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 @c 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

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

generated for every created machine. You can use UUID

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

<note>

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

subfolder of the created machine directly.

</note>

<result name="VBOX_E_OBJECT_NOT_FOUND">

@a osTypeId is invalid.

</result>

<result name="VBOX_E_FILE_ERROR">

Resulting settings file name is invalid or the settings file already

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

</result>

<result name="E_INVALIDARG">

@a name is empty or @c null.

</result>

</desc>

<param name="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="wstring" 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 @c 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="wstring" 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

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

are changed.

</note>

</method>

<method name="registerMachine">

<desc>

Registers the machine previously created using

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

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

successful method invocation, the

<link to="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="wstring" 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="wstring" 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="createAppliance">

<desc>

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

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

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

</desc>

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

<desc>New appliance.</desc>

</param>

</method>

<method name="createHardDisk">

<desc>

Creates a new base 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="IHardDisk::createBaseStorage"/></li>

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

</ul>

Some hard disk attributes, such as <link to="IHardDisk::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="#getHardDisk"/> and <link to="#findHardDisk"/>

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

the <link to="#hardDisks"/> array. See IHardDisk 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 @c null 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"/>, IHardDisk 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>

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

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

</param>

</method>

<method name="openHardDisk">

<desc>

Opens a hard disk from an existing location, optionally replacing

the image UUID and/or parent UUID.

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="#getHardDisk"/> and

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

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

be attached to virtual machines. See IHardDisk 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.

If @a write is ReadWrite (which it should be), the image is opened for

read/write access and must have according permissions, as VirtualBox

may actually write status information into the disk's metadata sections.

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

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

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

cloning when the image will quickly be closed again.

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

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

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

<result name="VBOX_E_FILE_ERROR">

Invalid hard disk storage file location or could not find the hard

disk at the specified 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="accessMode" type="AccessMode" dir="in">

<desc>

Determines whether to open the image in read/write or read-only mode.

</desc>

</param>

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

<desc>

Select whether a new image UUID is set or not.

</desc>

</param>

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

<desc>

New UUID for the image. If an empty string is passed, then a new

UUID is automatically created. Specifying a zero UUIDs is not valid.

</desc>

</param>

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

<desc>

Select whether a new parent UUID is set or not.

</desc>

</param>

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

<desc>

New parent UUID for the image. If an empty string is passed, then a

new UUID is automatically created, provided @a setParentId is

@c true. A zero UUID is valid.

</desc>

</param>

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

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

</param>

</method>

<method name="getHardDisk" 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="#createHardDisk"/> or opened by <link

to="#openHardDisk"/>, 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="wstring" dir="in">

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

</param>

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

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

</param>

</method>

<method name="findHardDisk">

<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="#createHardDisk"/> or opened by <link

to="#openHardDisk"/>, or attached to some known virtual machine.

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

the <link to="IHardDisk::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="IHardDisk" 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_FILE_ERROR">

Invalid CD/DVD image file location or could not find the CD/DVD

image at the specified location.

</result>

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

<desc>

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

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

generate a new UUID.

</desc>

</param>

<param name="image" type="IDVDImage" 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="wstring" dir="in">

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

</param>

<param name="image" type="IDVDImage" 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="IDVDImage" 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">

Invalid floppy image file location or could not find the floppy

image at the specified location.

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

<desc>

UUID to assign to the given image file within this VirtualBox

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

randomly generate a new UUID.

</desc>

</param>

<param name="image" type="IFloppyImage" 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="wstring" dir="in">

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

</param>

<param name="image" type="IFloppyImage" 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="IFloppyImage" 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. An empty

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

supplying @c null or an empty string 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 an empty string in the @a value argument.

<result name="VBOX_E_FILE_ERROR">

Settings file not accessible.

</result>

<result name="VBOX_E_XML_ERROR">

Could not parse the settings file.

</result>

</desc>

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

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

</param>

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

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

</param>

</method>

<method name="setExtraData">

<desc>

Sets associated global extra data.

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

will be deleted.

<note>

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

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

<li><tt>"sdl"</tt>: VirtualBox SDL GUI 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 or emprty, 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="wstring" 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="wstring" 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">

A @c null callback cannot be registered.

</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="IVirtualBox::settingsFilePath"/>) in case of auto-conversion,

and then calls <link to="IVirtualBox::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="IVirtualBox::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 @c N 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>

<!--method name="createDHCPServerForInterface">

<method name="createDHCPServer">

<desc>

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

<result name="E_INVALIDARG">

Host network interface @a name already exists.

</result>

</desc>

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

<desc>server name</desc>

</param>

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

<desc>Dhcp server settings</desc>

</param>

</method>

<method name="findDHCPServerByNetworkName">

<desc>

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

<result name="E_INVALIDARG">

Host network interface @a name already exists.

</result>

</desc>

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

<desc>server name</desc>

</param>

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

<desc>Dhcp server settings</desc>

</param>

</method>

<!--method name="findDHCPServerForInterface">

<method name="removeDHCPServer">

<desc>

Removes the dhcp server settings

<result name="E_INVALIDARG">

Host network interface @a name already exists.

</result>

</desc>

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

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

</param>

</method>

</interface>

<!--

<enum

name="VFSType"

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

>

<desc>

Virtual file systems supported by VFSExplorer.

</desc>

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

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

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

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

</enum>

<enum

name="VFSFileType"

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

>

<desc>

File types known by VFSExplorer.

</desc>

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

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

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

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

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

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

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

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

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

</enum>

<interface

name="IVFSExplorer" extends="$unknown"

uuid="2bb864a1-02a3-4474-a1d4-fb5f23b742e1"

wsmap="managed"

>

<desc>

The VFSExplorer interface unifies access to different file system

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

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

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

</desc>

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

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

</attribute>

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

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

</attribute>

<method name="update">

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

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

after a call to this method.</desc>

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

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

</param>

</method>

<method name="cd">

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

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

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

</param>

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

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

</param>

</method>

<method name="cdUp">

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

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

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

</param>

</method>

<method name="entryList">

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

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

list up do date.</desc>

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

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

</param>

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

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

</param>

</method>

<method name="exists">

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

level.</desc>

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

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

</param>

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

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

</param>

</method>

<method name="remove">

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

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

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

</param>

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

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

</param>

</method>

</interface>

<!--

<enum

name="CIMOSType"

uuid="86ef5f8c-18b2-4db8-a314-33721b59f89b"

>

<desc>

OVF operating system values according to CIM V2.20 (as of Nov 2008); http://www.dmtf.org/standards/cim/cim_schema_v220

</desc>

<const name="CIMOS_Unknown" value="0" /> <!-- "Unknown" -->

<const name="CIMOS_Other" value="1" /> <!-- "Other" -->

<const name="CIMOS_MACOS" value="2" /> <!-- "MACOS" -->

<const name="CIMOS_ATTUNIX" value="3" /> <!-- "ATTUNIX" -->

<const name="CIMOS_DGUX" value="4" /> <!-- "DGUX" -->

<const name="CIMOS_DECNT" value="5" /> <!-- "DECNT" -->

<const name="CIMOS_Tru64UNIX" value="6" /> <!-- "Tru64 UNIX" -->

<const name="CIMOS_OpenVMS" value="7" /> <!-- "OpenVMS" -->

<const name="CIMOS_HPUX" value="8" /> <!-- "HPUX" -->

<const name="CIMOS_AIX" value="9" /> <!-- "AIX" -->

<const name="CIMOS_MVS" value="10" /> <!-- "MVS" -->

<const name="CIMOS_OS400" value="11" /> <!-- "OS400" -->

<const name="CIMOS_OS2" value="12" /> <!-- "OS/2" -->

<const name="CIMOS_JavaVM" value="13" /> <!-- "JavaVM" -->

<const name="CIMOS_MSDOS" value="14" /> <!-- "MSDOS" -->

<const name="CIMOS_WIN3x" value="15" /> <!-- "WIN3x" -->

<const name="CIMOS_WIN95" value="16" /> <!-- "WIN95" -->

<const name="CIMOS_WIN98" value="17" /> <!-- "WIN98" -->

<const name="CIMOS_WINNT" value="18" /> <!-- "WINNT" -->

<const name="CIMOS_WINCE" value="19" /> <!-- "WINCE" -->

<const name="CIMOS_NCR3000" value="20" /> <!-- "NCR3000" -->

<const name="CIMOS_NetWare" value="21" /> <!-- "NetWare" -->

<const name="CIMOS_OSF" value="22" /> <!-- "OSF" -->

<const name="CIMOS_DCOS" value="23" /> <!-- "DC/OS" -->

<const name="CIMOS_ReliantUNIX" value="24" /> <!-- "Reliant UNIX" -->

<const name="CIMOS_SCOUnixWare" value="25" /> <!-- "SCO UnixWare" -->

<const name="CIMOS_SCOOpenServer" value="26" /> <!-- "SCO OpenServer" -->

<const name="CIMOS_Sequent" value="27" /> <!-- "Sequent" -->

<const name="CIMOS_IRIX" value="28" /> <!-- "IRIX" -->

<const name="CIMOS_Solaris" value="29" /> <!-- "Solaris" -->

<const name="CIMOS_SunOS" value="30" /> <!-- "SunOS" -->

<const name="CIMOS_U6000" value="31" /> <!-- "U6000" -->

<const name="CIMOS_ASERIES" value="32" /> <!-- "ASERIES" -->

<const name="CIMOS_HPNonStopOS" value="33" /> <!-- "HP NonStop OS" -->

<const name="CIMOS_HPNonStopOSS" value="34" /> <!-- "HP NonStop OSS" -->

<const name="CIMOS_BS2000" value="35" /> <!-- "BS2000" -->

<const name="CIMOS_LINUX" value="36" /> <!-- "LINUX" -->

<const name="CIMOS_Lynx" value="37" /> <!-- "Lynx" -->

<const name="CIMOS_XENIX" value="38" /> <!-- "XENIX" -->

<const name="CIMOS_VM" value="39" /> <!-- "VM" -->

<const name="CIMOS_InteractiveUNIX" value="40" /> <!-- "Interactive UNIX" -->

<const name="CIMOS_BSDUNIX" value="41" /> <!-- "BSDUNIX" -->

<const name="CIMOS_FreeBSD" value="42" /> <!-- "FreeBSD" -->

<const name="CIMOS_NetBSD" value="43" /> <!-- "NetBSD" -->

<const name="CIMOS_GNUHurd" value="44" /> <!-- "GNU Hurd" -->

<const name="CIMOS_OS9" value="45" /> <!-- "OS9" -->

<const name="CIMOS_MACHKernel" value="46" /> <!-- "MACH Kernel" -->

<const name="CIMOS_Inferno" value="47" /> <!-- "Inferno" -->

<const name="CIMOS_QNX" value="48" /> <!-- "QNX" -->

<const name="CIMOS_EPOC" value="49" /> <!-- "EPOC" -->

<const name="CIMOS_IxWorks" value="50" /> <!-- "IxWorks" -->

<const name="CIMOS_VxWorks" value="51" /> <!-- "VxWorks" -->

<const name="CIMOS_MiNT" value="52" /> <!-- "MiNT" -->

<const name="CIMOS_BeOS" value="53" /> <!-- "BeOS" -->

<const name="CIMOS_HPMPE" value="54" /> <!-- "HP MPE" -->

<const name="CIMOS_NextStep" value="55" /> <!-- "NextStep" -->

<const name="CIMOS_PalmPilot" value="56" /> <!-- "PalmPilot" -->

<const name="CIMOS_Rhapsody" value="57" /> <!-- "Rhapsody" -->

<const name="CIMOS_Windows2000" value="58" /> <!-- "Windows 2000" -->

<const name="CIMOS_Dedicated" value="59" /> <!-- "Dedicated" -->

<const name="CIMOS_OS390" value="60" /> <!-- "OS/390" -->

<const name="CIMOS_VSE" value="61" /> <!-- "VSE" -->

<const name="CIMOS_TPF" value="62" /> <!-- "TPF" -->

<const name="CIMOS_WindowsMe" value="63" /> <!-- "Windows (R) Me" -->

<const name="CIMOS_CalderaOpenUNIX" value="64" /> <!-- "Caldera Open UNIX" -->

<const name="CIMOS_OpenBSD" value="65" /> <!-- "OpenBSD" -->

<const name="CIMOS_NotApplicable" value="66" /> <!-- "Not Applicable" -->

<const name="CIMOS_WindowsXP" value="67" /> <!-- "Windows XP" -->

<const name="CIMOS_zOS" value="68" /> <!-- "z/OS" -->

<const name="CIMOS_MicrosoftWindowsServer2003" value="69" /> <!-- "Microsoft Windows Server 2003" -->

<const name="CIMOS_MicrosoftWindowsServer2003_64" value="70" /> <!-- "Microsoft Windows Server 2003 64-Bit" -->

<const name="CIMOS_WindowsXP_64" value="71" /> <!-- "Windows XP 64-Bit" -->

<const name="CIMOS_WindowsXPEmbedded" value="72" /> <!-- "Windows XP Embedded" -->

<const name="CIMOS_WindowsVista" value="73" /> <!-- "Windows Vista" -->

<const name="CIMOS_WindowsVista_64" value="74" /> <!-- "Windows Vista 64-Bit" -->

<const name="CIMOS_WindowsEmbeddedforPointofService" value="75" /> <!-- "Windows Embedded for Point of Service" -->

<const name="CIMOS_MicrosoftWindowsServer2008" value="76" /> <!-- "Microsoft Windows Server 2008" -->

<const name="CIMOS_MicrosoftWindowsServer2008_64" value="77" /> <!-- "Microsoft Windows Server 2008 64-Bit" -->

<const name="CIMOS_FreeBSD_64" value="78" /> <!-- "FreeBSD 64-Bit" -->

<const name="CIMOS_RedHatEnterpriseLinux" value="79" /> <!-- "RedHat Enterprise Linux" -->

<const name="CIMOS_RedHatEnterpriseLinux_64" value="80" /> <!-- "RedHat Enterprise Linux 64-Bit" -->

<const name="CIMOS_Solaris_64" value="81" /> <!-- "Solaris 64-Bit" -->

<const name="CIMOS_SUSE" value="82" /> <!-- "SUSE" -->

<const name="CIMOS_SUSE_64" value="83" /> <!-- "SUSE 64-Bit" -->

<const name="CIMOS_SLES" value="84" /> <!-- "SLES" -->

<const name="CIMOS_SLES_64" value="85" /> <!-- "SLES 64-Bit" -->

<const name="CIMOS_NovellOES" value="86" /> <!-- "Novell OES" -->

<const name="CIMOS_NovellLinuxDesktop" value="87" /> <!-- "Novell Linux Desktop" -->

<const name="CIMOS_SunJavaDesktopSystem" value="88" /> <!-- "Sun Java Desktop System" -->

<const name="CIMOS_Mandriva" value="89" /> <!-- "Mandriva" -->

<const name="CIMOS_Mandriva_64" value="90" /> <!-- "Mandriva 64-Bit" -->

<const name="CIMOS_TurboLinux" value="91" /> <!-- "TurboLinux" -->

<const name="CIMOS_TurboLinux_64" value="92" /> <!-- "TurboLinux 64-Bit" -->

<const name="CIMOS_Ubuntu" value="93" /> <!-- "Ubuntu" -->

<const name="CIMOS_Ubuntu_64" value="94" /> <!-- "Ubuntu 64-Bit" -->

<const name="CIMOS_Debian" value="95" /> <!-- "Debian" -->

<const name="CIMOS_Debian_64" value="96" /> <!-- "Debian 64-Bit" -->

<const name="CIMOS_Linux_2_4_x" value="97" /> <!-- "Linux 2.4.x" -->

<const name="CIMOS_Linux_2_4_x_64" value="98" /> <!-- "Linux 2.4.x 64-Bit" -->

<const name="CIMOS_Linux_2_6_x" value="99" /> <!-- "Linux 2.6.x" -->

<const name="CIMOS_Linux_2_6_x_64" value="100" /> <!-- "Linux 2.6.x 64-Bit" -->

<const name="CIMOS_Linux_64" value="101" /> <!-- "Linux 64-Bit" -->

<const name="CIMOS_Other_64" value="102" /> <!-- "Other 64-Bit" -->

</enum>

<enum

name="OVFResourceType"

uuid="646a78d7-6f04-49f4-82c4-75c28a75a4cd"

>

<desc>

OVF resource type (as listed with CIM_ResourceAllocationSettingData; see for example

http://msdn.microsoft.com/en-us/library/cc136877(VS.85).aspx).

</desc>

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