<?xml version="1.0" ?>

<idl>

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

// currenty, nsISupportsImpl.h lacks the below-like macros

#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_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_QUERY_INTERFACE2_CI(_class, _i1, _i2) \

NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)

#endif

</cpp>

</if>

<library

name="VirtualBox"

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

version="1.3"

desc="innotek VirtualBox Type Library"

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

supportsErrorInfo="yes"

>

<!--

<enum

name="TSBool"

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

>

<desc>

Boolean variable having a third state, default.

</desc>

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

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

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

</enum>

<enum

name="MachineState"

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

>

<desc>

Virtual machine execution state. This enumeration represents possible

values of the <link to="IMachine::state"/> attribute.

</desc>

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

<desc><tt>null</tt> 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.

<note>

No any machine settings can be altered when the machine

is in this state.

</note>

</desc>

</const>

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

<desc>

A process that run the machine has abnormally terminated.

Other than that, this value is equivalent to #PoweredOff.

</desc>

</const>

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

<desc>

The machine is currently being executed.

<note>

This value can be used in comparison expressions:

all state values below it describe a virtual machine that is

not currently being executed (i.e., it is completely out of

action).

</note>

<note>

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

aforementioned comparisons valid, this state must immediately

preceed the Paused state.

</note>

</desc>

</const>

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

<desc>

The execution of the machine has been paused.

<note>

This value can be used in comparison expressions: all state values

above it represent unstable states of the running virtual

machine. Unless explicitly stated otherwise, no machine settings can

be altered when it is in one of the unstable sates.

</note>

<note>

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

aforementioned comparisons valid, this state must immediately

follow the Running state.

</note>

</desc>

</const>

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

<desc>

The execution of the machine has reached the Guru Meditaion

condition. This condition indicates an internal VMM 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).

</desc>

</const>

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

<desc>

The machine is being started after

<link to="IConsole::powerUp">powering it on</link> from a

zero execution state.

</desc>

</const>

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

<desc>

The machine is being normally stopped

(after explicitly <link to="IConsole::powerDown">powering it off</link>,

or after the guest OS has initiated a shutdown sequence).

</desc>

</const>

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

<desc>

The machine is saving its execution state to a file as a

result of calling <link to="IConsole::saveState"/> or an online

snapshot of the machine is being taken using

<link to="IConsole::takeSnapshot"/>.

</desc>

</const>

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

<desc>

The execution state of the machine is being restored from a file

after <link to="IConsole::powerUp">powering it on</link> from

a saved execution state.

</desc>

</const>

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

<desc>

A snapshot of the machine is being discarded after calling

<link to="IConsole::discardSnapshot"/> or its current state is

being discarded after <link to="IConsole::discardCurrentState"/>.

</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. Idividual value descriptions contain the appropriate

meaning for every case.

</desc>

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

<desc><tt>null</tt> 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><tt>null</tt> 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>

<tt>null</tt> value which may also mean "no device".

<note>

This value is not allowed for

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

</note>

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

uuid="FC56E4B6-B195-48e2-A5E1-A667B0D9F809"

>

<desc>

Usage type constants for

<link to="IVirtualBox::getDVDImageUsage"/> and

<link to="IVirtualBox::getFloppyImageUsage"/>.

</desc>

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

<desc><tt>null</tt> value. Never used by the API.</desc>

</const>

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

<desc>

Scopes the VMs that use the resource permanently

(the information about this usage is stored in the VM

settings file).

</desc>

</const>

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

<desc>

Scopes the VMs that are temporarily using the resource

(the information about the usage is not yet saved in the VM

settings file). Temporary usage can take place only in the

context of an open session.

</desc>

</const>

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

<desc>

Combines Permanent and Temporary.

</desc>

</const>

</enum>

<enum

name="StorageBus"

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

>

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

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

<desc><tt>null</tt> value. Never used by the API.</desc>

</const>

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

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

</enum>

<enum

name="ClipboardMode"

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

>

<desc>

Host-Guest clipboard interchange mode.

</desc>

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

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

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

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

</enum>

<enum

name="Scope"

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

>

<desc>

Scope of the operation.

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

argument scope.

</desc>

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

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

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

</enum>

<enum

name="GuestStatisticType"

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

>

<desc>

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

</desc>

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

<desc>

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

</desc>

</const>

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

<desc>

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

</desc>

</const>

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

<desc>

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

</desc>

</const>

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

<desc>

Total number of threads in the system.

</desc>

</const>

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

<desc>

Total number of processes in the system.

</desc>

</const>

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

<desc>

Total number of handles in the system.

</desc>

</const>

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

<desc>

Memory load (0-100%).

</desc>

</const>

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

<desc>

Total physical memory in megabytes.

</desc>

</const>

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

<desc>

Free physical memory in megabytes.

</desc>

</const>

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

<desc>

Ballooned physical memory in megabytes.

</desc>

</const>

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

<desc>

Total amount of memory in the committed state in megabytes.

</desc>

</const>

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

<desc>

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

</desc>

</const>

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

<desc>

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

</desc>

</const>

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

<desc>

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

</desc>

</const>

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

<desc>

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

</desc>

</const>

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

<desc>

Pagefile size in megabytes.

</desc>

</const>

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

<desc>

Statistics sample number

</desc>

</const>

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

</enum>

<enum

name="BIOSBootMenuMode"

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

>

<desc>

BIOS boot menu mode.

</desc>

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

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

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

</enum>

<enum

name="IDEControllerType"

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

>

<desc>

IDE controller type.

</desc>

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

<desc><tt>null</tt> value. Never used by the API.</desc>

</const>

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

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

</enum>

<enum

name="DriveState"

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

>

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

<desc><tt>null</tt> value. Never used by the API.</desc>

</const>

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

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

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

</enum>

<!--

<interface

name="IVirtualBoxErrorInfo" extends="$errorinfo"

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

supportsErrorInfo="no"

wsmap="suppress"

>

<desc>

The IVirtualBoxErrorInfo interface represents extended error information.

Extended error information can be set by VirtualBox components after

unsuccessful or partially successful method invocation. This information

can be retrievefd by the calling party as an IVirtualBoxErrorInfo object

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

In MS COM, this interface extends the IErrorInfo interface,

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

it provides a set of common attributes to retrieve error

information.

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

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

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

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

information about all errors happened during method invocation and deliver

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

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

through a single IVirtualBoxErrorInfo object set after method invocation.

Note that errors are stored to a chain in the reverse order, i.e. the

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

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

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

in the chain).

</desc>

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

<desc>

Result code of the error.

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

by the method that provided this error information, but not

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

likely return E_NOINTERFACE upon unsuccessful component

instantiation attempt, but not the value the component factory

returned.

<note>

In MS COM, there is no equivalent.

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

</note>

</desc>

</attribute>

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

<desc>

UUID of the interface that defined the error.

<note>

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

In XPCOM, there is no equivalent.

</note>

</desc>

</attribute>

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

<desc>

Name of the component that generated the error.

<note>

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

In XPCOM, there is no equivalent.

</note>

</desc>

</attribute>

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

<desc>

Text description of the error.

<note>

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

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

</note>

</desc>

</attribute>

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

<desc>

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

<note>

In MS COM, there is no equivalent.

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

</note>

</desc>

</attribute>

</interface>

<!--

<interface

name="IVirtualBoxCallback" extends="$unknown"

uuid="ee95ffc2-b6c6-4ce8-9e9e-ceadbb5019fe"

wsmap="suppress"

>

<method name="onMachineStateChange">

<desc>

The execution state of the given machine has changed.

<see>IMachine::state</see>

</desc>

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

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

</param>

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

<desc>New execution state.</desc>

</param>

</method>

<method name="onMachineDataChange">

<desc>

Any of the settings of the given machine has changed.

</desc>

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

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

</param>

</method>

<method name="onExtraDataCanChange">

<desc>

Notification when someone tries to change extra data for

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

This gives the chance to veto against changes.

</desc>

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

<desc>

ID of the machine this event relates to

(null ID for global extra data change requests).

</desc>

</param>

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

<desc>

Extra data key for the attempted write.

</desc>

</param>

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

<desc>

Extra data value for the given key.

</desc>

</param>

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

<desc>

Optional error message describing the reason of the

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

</desc>

</param>

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

<desc>

Flag to indicate whether the callee agrees (@ true)

or vetoes against the change (@ false).

</desc>

</param>

</method>

<method name="onExtraDataChange">

<desc>

Notification when machine specific or global extra data

has changed.

</desc>

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

<desc>

ID of the machine this event relates to.

Null for global extra data changes.

</desc>

</param>

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

<desc>

Extra data key that has changed.

</desc>

</param>

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

<desc>

Extra data value for the given key.

</desc>

</param>

</method>

<method name="onMediaRegistered">

<desc>

The given media was registered or unregistered

within this VirtualBox installation.

The @a mediaType parameter describes what type of

media the specified @a mediaId refers to. Possible

values are:

- <link to="DeviceType::HardDisk"/>: the media is a hard disk

that, if registered, can be obtained using the

<link to="IVirtualBox::getHardDisk"/> call.

- <link to="DeviceType::DVD"/>: the media is a CD/DVD image

that, if registered, can be obtained using the

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

- <link to="DeviceType::Floppy"/>: the media is a Floppy image

that, if registered, can be obtained using the

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

Note that if this is a deregistration notification,

there is no way to access the object representing the

unregistered media. It is supposed that the

application will do required cleanup based on the @a

mediaId value.

</desc>

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

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

</param>

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

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

</param>

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

<desc>

If true, the media was registered, otherwise it was

unregistered.

</desc>

</param>

</method>

<method name="onMachineRegistered">

<desc>

The given machine was registered or unregistered

within this VirtualBox installation.

</desc>

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

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

</param>

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

<desc>

If true, the machine was registered, otherwise it was

unregistered.

</desc>

</param>

</method>

<method name="onSessionStateChange">

<desc>

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

<see>IMachine::sessionState</see>

</desc>

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

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

</param>

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

<desc>New session state.</desc>

</param>

</method>

<method name="onSnapshotTaken">

<desc>

A new snapshot of the machine has been taken.

<see>ISnapshot</see>

</desc>

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

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

</param>

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

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

</param>

</method>

<method name="onSnapshotDiscarded">

<desc>

Snapshot of the given machine has been discarded.

<note>

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

object has been uninitialized on the server (so that any

attempt to call its methods will return an error).

</note>

<see>ISnapshot</see>

</desc>

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

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

</param>

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

<desc>

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

current machine state has been discarded (restored from

the current snapshot).

</desc>

</param>

</method>

<method name="onSnapshotChange">

<desc>

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

<see>ISnapshot</see>

</desc>

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

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

</param>

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

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

</param>

</method>

</interface>

<interface

name="IVirtualBox" extends="$dispatched"

uuid="2d3b9ea7-25f5-4f07-a8e1-7dd7e0dcf667"

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

<desc>

Full path to the directory where the global settings file,

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

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

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

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

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

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

places where relative paths are allowed (unless otherwise

expressly indicated).

</desc>

</attribute>

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

<desc>

Full name of the global settings file.

The value of this property corresponds to the value of

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

</desc>

</attribute>

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

<desc>

Current version of the format of the global VirtualBox settings file

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

The version string has the following format:

<pre>

x.y-platform

</pre>

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

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

The current version usually matches the value of the

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

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

was a change of the settings file format since then.

Note that VirtualBox automatically converts settings files from older

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

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

you call a method that implicitly saves settings (such as

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

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

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

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

conversion is not yet saved to disk.

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

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

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

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

etc.

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

</desc>

</attribute>

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

<desc>

Most recent version of the settings file format.

The version string has the following format:

<pre>

x.y-platform

</pre>

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

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

VirtualBox uses this version of the format when saving settings files

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

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

<see>settingsFileVersion</see>

</desc>

</attribute>

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

<desc>Associated host object.</desc>

</attribute>

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

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

</attribute>

<attribute name="machines" type="IMachineCollection" readonly="yes">

<desc>

Collection of machine objects registered within this VirtualBox

instance.

</desc>

</attribute>

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

<desc>

Array of machine objects registered within this VirtualBox instance.

</desc>

</attribute>

<attribute name="hardDisks" type="IHardDiskCollection" readonly="yes">

<desc>

Collection of hard disk objects registered within this VirtualBox

instance.

This collection contains only "top-level" (basic or independent) hard

disk images, but not differencing ones. All differencing images of the

given top-level image (i.e. all its children) can be enumerated using

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

</desc>

</attribute>

<attribute name="DVDImages" type="IDVDImageCollection" readonly="yes"/>

<attribute name="FloppyImages" type="IFloppyImageCollection" readonly="yes"/>

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

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

<attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">

<desc>

Collection of global shared folders. Global shared folders are

available to all virtual machines.

New shared folders are added to the collection using

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

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

<note>

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

implemented and therefore this collection is always empty.

</note>

</desc>

</attribute>

<method name="createMachine">

<desc>

Creates a new virtual machine.

The new machine will have "empty" default settings and will not

yet be registered. The typical sequence to create a virtual machine

is therefore something like this:

<ol>

<li>Call this method (IVirtualBox::createMachine) to have a new

machine created. The machine object returned is "mutable", i.e.

automatically locked for the current session, as if

<link to="#openSession" /> had been called on it.</li>

<li>Assign meaningful settings to the new machine by calling the

respective methods.</li>

<li>Call <link to="IMachine::saveSettings" /> to have the settings written

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

created machine will not be saved to disk (and the settings subfolder

and file, as described below, will not be created) until this method

is called.</li>

<li>Call <link to="#registerMachine" /> to have the

machine show up in the list of machines registered with VirtualBox.</li>

</ol>

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

the machine configuration. This file is stored in the directory

called <i>machine settings subfolder</i>. Unless specified otherwise,

both the subfolder and the settings file will have a name that

corresponds to the name of the virtual machine. You can specify

where to create the machine settings 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 null or empty string is given as the base folder (which is

recommended), the <link to="ISystemProperties::defaultMachineFolder">

default machine settings folder</link> will be used as the base

folder to create the machine settings subfolder and file. In

any case, the full path to the settings file will look like:

<pre>

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

</pre>

Optionally the UUID of the machine can be predefined. If this is

not desired (i.e. a new UUID should be generated), pass just an

empty or null UUID.

You should also specify a valid name for the machine.

See the <link to="IMachine::name"/> property

description for more details about the machine name.

The created machine remains

unregistered until you call <link to="#registerMachine()"/>.

<note>

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

subfolder of the created machine directly.

</note>

</desc>

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

<desc>

Name of the folder where to create the machine settings

subfolder containing the settings file.

</desc>

</param>

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

<desc>Machine name.</desc>

</param>

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

<desc>

UUID of the newly created VM, when non-null or non-empty.

Otherwise a UUID is automatically generated.

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

Optionally the UUID of the machine can be predefined. If this is

not desired (i.e. a new UUID should be generated), pass just an

empty or null UUID.

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,

<link to="IMachine::saveSettings()"/> will return an error.

You should also specify a valid name for the machine.

See the <link to="IMachine::name"/> property

description for more details about the machine name.

The created machine remains

unregistered until you call <link to="#registerMachine()"/>.

@deprecated This method may be removed later. It is better

to use <link to="IVirtualBox::createMachine()"/>.

<note>

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

of the created machine.

</note>

</desc>

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

<desc>

Name of the file where to store machine settings.

</desc>

</param>

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

<desc>Machine name.</desc>

</param>

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

<desc>

UUID of the newly created VM, when non-null or non-empty.

Otherwise a UUID is automatically generated.

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

</desc>

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

<desc>

Name of the machine settings file.

</desc>

</param>

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

<desc>Opened machine object.</desc>

</param>

<note>

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

false for the created machine, until any of machine settigs

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>

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

</desc>

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

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

</method>

<method name="findMachine">

<desc>

Attempts to find a virtual machine given its name.

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

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

</desc>

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

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

</param>

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

<desc>Unregistered machine object.</desc>

</param>

</method>

<method name="createHardDisk">

<desc>

Creates a new unregistered hard disk that will use the given

storage type.

Most properties of the created hard disk object are

uninitialized. Valid values must be assigned to them (and probalby

some actions performed) to make the actual usage of this hard disk

(<link to="#registerHardDisk()">register</link>, attach to a virtual

machine, etc.). See the description of <link to="IHardDisk"/> and

descriptions of storage type specific interfaces for more information.

<note>

For hard disks using

the <link

to="HardDiskStorageType::VirtualDiskImage">VirtualDiskImage</link>

storage type, an image file is not actually created until you call

<link to="IVirtualDiskImage::createDynamicImage()"/> or

<link to="IVirtualDiskImage::createFixedImage()"/>.

</note>

</desc>

<param name="storageType" type="HardDiskStorageType" dir="in">

<desc>Storage type of the hard disk image to create.</desc>

</param>

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

<desc>Created hard disk object of the given storage type.</desc>

</param>

</method>

<method name="openHardDisk">

<desc>

Opens a hard disk from an existing location.

This method tries to guess the

<link to="HardDiskStorageType">hard disk storage type</link> from the

format of the location string and from the contents of the resource the

location points to. Currently, a <i>file path</i> is the only

supported format for the location string which must point to either a

VDI file or to a VMDK file. On success, an IHardDisk object will be

returned that also implements the corresponding interface

(IVirtualDiskImage or IVMDKImage, respectively). The

<link to="IHardDisk::storageType"/> property may also be used to

determine the storage type of the returned object (instead of trying

to query one of these interfaces).

<note>

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

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

directory</link>. If only a file name without any path is given,

the <link to="ISystemProperties::defaultVDIFolder"> default VDI

folder</link> will be used as a path to the image file.

</note>

The opened hard disk remains unregistered

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

</desc>

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

<desc>

Location of the resource that contains a valid hard disk.

</desc>

</param>

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

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

</param>

</method>

<method name="openVirtualDiskImage">

<desc>

Opens a hard disk from an existing Virtual Disk Image file.

The opened hard disk remains unregistered

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

@deprecated Use <link to="IVirtualBox::openHardDisk()"/> instead.

<note>Opening differencing images is not supported.</note>

<note>The specified file path can be absolute (full path) or

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

home directory</link>. If only a file name without any path is

given, the <link to="ISystemProperties::defaultVDIFolder">

default VDI folder</link> will be used as a path to the image

file.</note>

</desc>

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

<desc>

Name of the file that contains a valid Virtual Disk Image.

</desc>

</param>

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

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

</param>

</method>

<method name="registerHardDisk">

<desc>

Registers the given hard disk within this VirtualBox

installation. The hard disk must not be registered, must be

<link to="IHardDisk::accessible"/> and must not be a

differencing hard disk, otherwise the registration will fail.

</desc>

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

<desc>Hard disk object to register.</desc>

</param>

</method>

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

<desc>

Returns the registered hard disk with the given UUID.

</desc>

<param name="id" type="uuid" 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 registered hard disk that uses the given location to

store data. The search is done by comparing the

value of the @a location argument to the

<link to="IHardDisk::location"/> attribute of each registered

hard disk.

For locations repesented by file paths (such as VDI and VMDK

images), the specified location can be either an absolute file

path or a path relative to

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

directory</link>. If only a file name without any path is

given, the <link to="ISystemProperties::defaultVDIFolder">

default VDI folder</link> will be used as a path to construct

the absolute image file name to search for. Note that on host

systems with case sensitive filesystems, a case sensitive

comparison is performed, otherwise the case of symbols in the

file path is ignored.

</desc>

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

<desc>Hard disk location specification to search for.</desc>

</param>

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

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

</param>

</method>

<method name="findVirtualDiskImage">

<desc>

Returns a registered hard disk that uses the given image file.

@deprecated Use <link to="IVirtualBox::findHardDisk()"/> instead.

<note>The specified file path can be absolute (full path) or

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

home directory</link>. If only a file name without any path is

given, the <link to="ISystemProperties::defaultVDIFolder">

default VDI folder</link> will be used as a path to the image

file.</note>

<note>On host systems with case sensitive filesystems, a case

sensitive comparison is performed, otherwise the case of symbols

in the file path is ignored.</note>

</desc>

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

<desc>Virtual Disk Image file path to look for.</desc>

</param>

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

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

</param>

</method>

<method name="unregisterHardDisk">

<desc>

Unregisters a hard disk previously registered using

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

<note>

The specified hard disk must not be attached to any of

the existing virtual machines and must not have children

(differencing) hard disks.

</note>

</desc>

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

<desc>UUID of the hard disk to unregister.</desc>

</param>

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

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

</param>

</method>

<method name="openDVDImage">

<desc>

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

the supported format and assigns it the given UUID. The opened

image remains unregistered

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

</desc>

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

<desc>

Full name of the file that contains a valid

CD/DVD image. Currently, only ISO images are supported.

<note>

The specified file name can be absolute or relative

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

VirtualBox home directory</link>.

</note>

</desc>

</param>

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

<desc>

UUID to assign to the given image file within this

VirtualBox installation. If an empty (null) UUID is

specified, the system will randomly generate an UUID.

</desc>

</param>

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

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

</param>

</method>

<method name="registerDVDImage">

<desc>

Registers a CD/DVD image within this VirtualBox

installation. The image must not be registered and must not

be associated with the same image file as any of the already

registered images, otherwise the registration will fail.

</desc>

<param name="image" type="IDVDImage" dir="in">

<desc>CD/DVD image object to register.</desc>

</param>

</method>

<method name="getDVDImage">

<desc>

Returns a registered CD/DVD image with the given UUID.

</desc>

<param name="id" type="uuid" 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 registered CD/DVD image with the given image file.

<note>

On host systems with case sensitive filesystems, a case

sensitive comparison is performed, otherwise the case of

symbols in the file path is ignored.

</note>

</desc>

<param name="filePath" 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="getDVDImageUsage">

<desc>

Returns the list of of UUIDs of all virtual machines that use

the given CD/DVD image.

</desc>

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

<desc>UUID of the image to get the usage information for.</desc>

</param>

<param name="usage" type="ResourceUsage" dir="in">

<desc>Type of the usage (permanent, temporary or all).</desc>

</param>

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

<desc>

List of UUIDs of all machines that use the given image

in the way specified by the usage parameter.

The list is returned as a string containing UUIDs separated

by spaces. A null string means that the image is not used.

<note>

When the usage type is <link to="ResourceUsage::All"/> and the image

is used by the VM both permanently and temporarily, the VM's UUID

will be present only once in the list.

</note>

</desc>

</param>

</method>

<method name="unregisterDVDImage">

<desc>

Unregisters the CD/DVD image previously registered using

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

<note>

The specified image must not be mounted to any of

the existing virtual machines.

</note>

</desc>

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

<desc>UUID of the CD/DVD image to unregister.</desc>

</param>

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

<desc>Unregistered 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. The opened

image remains unregistered

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

</desc>

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

<desc>

Full name of the file that contains a valid

floppy image.

<note>

The specified file name can be absolute or relative

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

VirtualBox home directory</link>.

</note>

</desc>

</param>

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

<desc>

UUID to assign to the given image file within this

VirtualBox installation. If an empty (null) UUID is

specified, the system will randomly generate an UUID.

</desc>

</param>

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

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

</param>

</method>

<method name="registerFloppyImage">

<desc>

Registers a floppy image within this VirtualBox

installation. The image must not be registered and must not

be associated with the same image file as any of the already

registered images, otherwise the registration will fail.

</desc>

<param name="image" type="IFloppyImage" dir="in">

<desc>Floppy image object to register.</desc>

</param>

</method>

<method name="getFloppyImage">

<desc>

Returns a registered floppy image with the given UUID.

</desc>

<param name="id" type="uuid" 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 registered floppy image with the given image file.

<note>

On host systems with case sensitive filesystems, a case

sensitive comparison is performed, otherwise the case of

symbols in the file path is ignored.

</note>

</desc>

<param name="filePath" 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="getFloppyImageUsage">

<desc>

Returns the list of of UUIDs of all virtual machines that use

the given floppy image.

</desc>

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

<desc>UUID of the image to get the usage information for.</desc>

</param>

<param name="usage" type="ResourceUsage" dir="in">

<desc>Type of the usage (permanent, temporary or all).</desc>

</param>

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

<desc>

List of UUIDs of all machines that use the given image

in the way specified by the usage parameter.

The list is returned as a string containing UUIDs separated

by spaces. A null string means that the image is not used.

<note>

When the usage type is <link to="ResourceUsage::All"/> and the image

is used by the VM both permanently and temporarily, the VM's UUID

will be present only once in the list.

</note>

</desc>

</param>

</method>

<method name="unregisterFloppyImage">

<desc>

Unregisters the floppy image previously registered using

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

<note>

The specified image must not be mounted to any of

the existing virtual machines.

</note>

</desc>

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

<desc>UUID of the floppy image to unregister.</desc>

</param>

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

<desc>Unregistered image object.</desc>

</param>

</method>

<method name="getGuestOSType">

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

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

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

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

</desc>

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

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

</param>

</method>

<method name="getNextExtraDataKey">

<desc>

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

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

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

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

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

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

</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 reuqested data @a key does not exist, this function will

succeed and return @c NULL in the @a value argument.

</desc>

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

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

</param>

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

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

</param>

</method>

<method name="setExtraData">

<desc>

Sets associated global extra data.

If you pass @c NULL as a key @a vaule, 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>

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

Within the direct session context, it is possible to change

all VM settings, as well as to execute the VM in the process

space of the session object. There can be only one direct

session open at a time for every virtual machine. In VirtualBox

terminology, the machine becomes "mutable" after a session has

been opened.

Upon successful return, the session object can be used to

get access to the machine and to the VM console.

Note that the "mutable" machine object, on which you may want

to 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 "machine" attribute of the ISession object which represents

your open session.

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 ISession::machine.</li>

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

<li>Call IMachine::saveSettings.</li>

<li>Close the session by calling <link to="#close" />.</li>

</ol>

</desc>

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

<desc>

Session object that will represent the opened session after

successful method invocation. This object must not represent

the already open session.

<note>

This session will be automatically closed if the

VirtualBox server is terminated for some reason.

</note>

</desc>

</param>

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

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

</param>

</method>

<method name="openRemoteSession">

<desc>

Opens a new remote session with the given virtual

machine.

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

process that opens a direct session with the given VM. The remote

session provides some level of control over the VM execution to the

caller (using the IConsole interface); however, within the remote

session context, not all VM settings are available for modification.

This operation can take some time, so the progress object

is returned to let the caller be informed when the session is

actually open. Until then, the remote session object remains in

the closed state and accessing the machine or its console through

it is invalid.

Currently supported session types (values of the @a type

argument) are:

<ul>

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

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

</ul>

The @a environment argument is a string containing definitions of

environment variables in the following format:

@code

NAME[=VALUE]\n

NAME[=VALUE]\n

...

@endcode

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

variables will be appended to the environment of the VirtualBox server

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

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

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

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

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

inherited by the started process as is.

<note>

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

that already has an open direct session or waits until the

previous request to open the remote session is completed

(see <link to="IMachine::sessionState"/>).

</note>

<note>

The opened @a session will be automatically closed when

the corresponding direct session dies or gets closed.

</note>

<see>openExistingSession</see>

</desc>

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

<desc>

Session object that will represent the opened remote session

after successful method invocation (this object must not

represent an already open session).

</desc>

</param>

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

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

</param>

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

<desc>

Type of the remote session (case sensitive).

</desc>

</param>

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

<desc>

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

</desc>

</param>

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

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

</param>

</method>

<method name="openExistingSession">

<desc>

Opens a new remote session with the virtual machine for

which a direct session is already open.

The remote session provides some level of control over the VM

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

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

for modification.

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

remote sessions opened this way is not limited by the API

<note>

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

doesn't have an open direct session.

</note>

<see>openRemoteSession</see>

</desc>

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

<desc>

Session object that will represent the open remote session

after successful method invocation. This object must not

represent an already open session.

<note>

This session will be automatically closed when the peer

(direct) session dies or gets closed.

</note>

</desc>

</param>

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

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

</param>

</method>

<method name="registerCallback">

<desc>

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

callback object will be called by VirtualBox when an appropriate

event occurs.

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

</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 propertiy masks that

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

a string in the following format:

@code

[[group.]subgroup.]name

@endcode

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

or 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 preceeding 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 descrcriptions 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>

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

</desc>

</method>

<method name="saveSettingsWithBackup">

<desc>

Creates a backup copy of the global settings file

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

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

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

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

details). Otherwise, this call is fully equivalent to

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

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

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

<pre>

original.xml.x.y-platform.bak

</pre>

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

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

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

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

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

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

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

failure.

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

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

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

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

copy operation, fails.

<note>

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

the purposes of creating backup copies of the settings files by

front-ends before saving the results of the automatically performed

settings conversion to disk.

</note>

<see>settingsFileVersion</see>

</desc>

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

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

</param>

</method>

</interface>

<!--

<enumerator

name="IMachineEnumerator" type="IMachine"

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

/>

<collection

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

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

readonly="yes"

/>

<interface

name="IInternalMachineControl" extends="$unknown"

uuid="1063893c-4c38-4304-aee9-73e072c181cc"

internal="yes"

wsmap="suppress"

>

<method name="updateState">

<desc>

Updates the VM state.

<note>

This operation will also update the settings file with

the correct information about the saved state file

and delete this file from disk when appropriate.

</note>

</desc>

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

</method>

<method name="getIPCId">

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

</method>

<method name="runUSBDeviceFilters">

<desc>

Asks the server to run USB devices filters of the associated

machine against the given USB device and tell if there is

a match.

<note>

Intended to be used only for remote USB devices. Local

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

implicitly by the Host and USBProxyService).

</note>

</desc>

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

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

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

</method>

<method name="captureUSBDevice">

<desc>

Requests a capture of the given host USB device.

When the request is completed, the VM process will

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

notification.

</desc>

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

</method>

<method name="detachUSBDevice">

<desc>

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

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

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

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

notification.

<note>

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

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

as if it were just attached to the host computer.

</note>

</desc>

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

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

</method>

<method name="autoCaptureUSBDevices">

<desc>

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

When the request is completed, the VM process will

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

notification per every captured device.

</desc>

</method>

<method name="detachAllUSBDevices">

<desc>

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

parameter indicates whether which stage of the power down

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

intentions, while when done = true the VM is reporting

what it has done.

<note>

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

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

if they were just attached to the host computer.

</note>

</desc>

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

</method>

<method name="onSessionEnd">

<desc>

Triggered by the given session object when the session is about

to close normally.

</desc>

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

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

</param>

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

<desc>

Used to wait until the corresponding machine is actually

deassociated from the given session on the server.

Returned only when this session is a direct one.

</desc>

</param>

</method>

<method name="beginSavingState">

<desc>

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

save the current state and stop the VM execution.

</desc>

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

<desc>

Progress object created by the VM process to wait until

the state is saved.

</desc>

</param>

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

<desc>

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

</desc>

</param>

</method>

<method name="endSavingState">

<desc>

Called by the VM process to inform the server that saving

the state previously requested by #beginSavingState is either

successfully finished or there was a failure.

</desc>

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

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

</param>

</method>

<method name="adoptSavedState">

<desc>

Gets called by IConsole::adoptSavedState.

</desc>

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

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

</param>

</method>

<method name="beginTakingSnapshot">

<desc>

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

take a snapshot.

</desc>

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

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

</param>

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

<desc>Snapshot name</desc>

</param>

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

<desc>Snapshot description</desc>

</param>

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

<desc>

Progress object created by the VM process to wait until

the state is saved (only for online snapshots).

</desc>

</param>

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

<desc>

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

</desc>

</param>

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

<desc>

Progress object created by the server process to wait until

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

</desc>

</param>

</method>

<method name="endTakingSnapshot">

<desc>

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

previously requested by #beginTakingSnapshot is either

successfully taken or there was a failure.

</desc>

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

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

</param>

</method>

<method name="discardSnapshot">

<desc>

Gets called by IConsole::discardSnapshot.

</desc>

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

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

</param>

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

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

</param>

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

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

</param>

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

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

</param>

</method>

<method name="discardCurrentState">

<desc>

Gets called by IConsole::discardCurrentState.

</desc>

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

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

</param>

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

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

</param>

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

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

</param>

</method>

<method name="discardCurrentSnapshotAndState">

<desc>

Gets called by IConsole::discardCurrentSnapshotAndState.

</desc>

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

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

</param>

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

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

</param>

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

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

</param>

</method>

</interface>

<interface

name="IBIOSSettings" extends="$unknown"

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

wsmap="struct"

>

<desc>

The IBIOSSettings interface represents BIOS settings of the virtual

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

<note>With the COM API, this is an interface like all the others. With the webservice,

this is mapped to a structure, so querying the attribute will not return an object,

but a complete structure.</note>

</desc>

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

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

</attribute>

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

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

</attribute>

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

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

</attribute>

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

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

</attribute>

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

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

</attribute>

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

<desc>ACPI support flag.</desc>

</attribute>

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

<desc>

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

and support IRQs above 15.

</desc>

</attribute>

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

<desc>

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

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

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

than it's not an absolute value but a relative one. Guest Additions

time synchronization also honors this offset.

</desc>

</attribute>

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

<desc>

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

PXE trace information to the release log.

</desc>

</attribute>

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

<desc>

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

VirtualBox will provide different virtual IDE hardware

devices to the guest.

</desc>

</attribute>

</interface>

<interface

name="IMachine" extends="$unknown"

uuid="4f6b4977-95fd-40b1-8391-fc165c040635"

wsmap="managed"

>

<desc>

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

in VirtualBox.

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

objects implementing this interface is stored in the

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

machines that are currently registered with this VirtualBox

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

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

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

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

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

machine and provide methods to change various aspects of the virtual

machine's configuration. For machine objects stored in the

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

read-only unless explicitely stated otherwise in individual attribute

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

for this machine must be opened using one of

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

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

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

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

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

can be applied to the returned object using IMachine attributes and

methods. See the ISession interface description for more information

about sessions.

Note that the IMachine interface does not provide methods to control

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

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

interface. Refer to the IConsole interface description to get more

information about this topic.

<see>ISession, IConsole</see>

</desc>

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

<desc>Associated parent obect.</desc>

</attribute>

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

<desc>

Whether this virtual machine is currently accessible or not.

The machine is considered to be inaccessible when:

<ul>

<li>It is a registered virtual machine, and

</li>

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

located on a network share that is not accessible during

VirtualBox startup, or becomes inaccessible later, or if

the settings file can be read but is invalid).

</li>

</ul>

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

Every time this property is read, the accessibility state of

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

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

detailed error information describing the reason of

inaccessibility.

When the machine is inaccessible, only the following properties

can be used on it:

<ul>

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

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

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

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

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

</ul>

An attempt to access any other property or method will return

an error.

The only possible action you can perform on an inaccessible

machine is to unregister it using the

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

for the accessibility state once more by querying this

property).

<note>

In the current implementation, once this property returns

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

later, even if its settings file cannot be successfully

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

server is restarted). This limitation may be removed in

future releases.

</note>

</desc>

</attribute>

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

<desc>

Error information describing the reason of machine

inaccessibility.

Reading this property is only valid after the last call to

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

machine is currently unaccessible). Otherwise, a null

IVirtualBoxErrorInfo object will be returned.

</desc>

</attribute>

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

<desc>

Name of the virtual machine.

Besides being used for human-readable identification purposes

everywhere in VirtualBox, the virtual machine name is also used

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

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

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

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

change. The containing subdirectory will be also renamed, but

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

itself prior to changing this property (for backward compatibility

with previous API releases). The above implies the following

limitations:

<ul>

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

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

file name characters according to the rules of the file

system used to store VirtualBox configuration.</li>

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

if they use the same subdirectory for storing the machine

settings files.</li>

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

or if any file in the directory containing the settings file

is being used by another running machine or by any other

process in the host operating system at a time when

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

</li>

</ul>

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

will return an appropriate error message explaining the exact

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

saved.

<note>

For "legacy" machines created using the

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

the above naming limitations do not apply because the

machine name does not affect the settings file name.

The settings file name remains the same as it was specified

during machine creation and never changes.

</note>

</desc>

</attribute>

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

<desc>

Description of the virtual machine.

The description attribute can contain any text and is

typically used to describe the hardware and software

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

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

</desc>

</attribute>

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

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

</attribute>

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

<desc>

User-defined identifier of the Guest OS type.

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

an IGuestOSType object representing details about the given

Guest OS type.

<note>

This value may differ from the value returned by

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

installed to the guest OS.

</note>

</desc>

</attribute>

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

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

</attribute>

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

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

</attribute>

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

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

</attribute>

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

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

</attribute>

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

<desc>

Number of virtual monitors.

<note>

Only effective on Windows XP and later guests with

Guest Additions installed.

</note>

</desc>

</attribute>

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

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

</attribute>

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

<desc>

This setting determines whether VirtualBox will try to make use of

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

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

they will not be used.

</desc>

</attribute>

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

<desc>

Full path to the directory used to store snapshot data

(difrerencing hard disks and saved state files) of this machine.

The initial value of this property is

<tt>&lt;</tt><link to="#settingsFilePath">

path_to_settings_file</link><tt>&gt;/&lt;</tt>

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

<tt>&gt;</tt>.

Currently, it is an error to try to change this property on

a machine that has snapshots (because this would require to

move possibly large files to a different location).

A separate method will be available for this purpose later.

<note>

Setting this property to <tt>null</tt> will restore the

initial value.

</note>

<note>

When setting this property, the specified path can be

absolute (full path) or relative to the directory where the

<link to="#settingsFilePath">machine settings file</link>

is located. When reading this property, a full path is

always returned.

</note>

<note>

The specified path may not exist, it will be created

when necessary.

</note>

</desc>

</attribute>

<attribute name="VRDPServer" type="IVRDPServer" readonly="yes">

<desc>VRDP server object.</desc>

</attribute>

<attribute name="hardDiskAttachments" type="IHardDiskAttachmentCollection" readonly="yes">

<desc>Collection of hard disks attached to the machine.</desc>

</attribute>

<attribute name="DVDDrive" type="IDVDDrive" readonly="yes">

<desc>Associated DVD drive object.</desc>

</attribute>

<attribute name="FloppyDrive" type="IFloppyDrive" readonly="yes">

<desc>Associated floppy drive object.</desc>

</attribute>

<attribute name="USBController" type="IUSBController" readonly="yes">

<desc>

Associated USB controller object.

<note>

This method may set a @ref com_warnings "warning result code".

</note>

<note>

If USB functionality is not avaliable in the given edition of

VirtualBox, this method will set the result code to @c E_NOTIMPL.

</note>

</desc>

</attribute>

<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">

<desc>Associated audio adapter, always present.</desc>

</attribute>

<attribute name="SATAController" type="ISATAController" readonly="yes">

<desc>

Associated SATA controller object.

</desc>

</attribute>

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

<desc>

Full name of the file containing machine settings data.

</desc>

</attribute>

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

<desc>

Current version of the format of the settings file of this machine

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

The version string has the following format:

<pre>

x.y-platform

</pre>

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

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

The current version usually matches the value of the

<link to="IVirtualBox::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="IVirtualBox::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 bacup copies of the old settings files before saving,

etc.

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

</desc>

</attribute>

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

<desc>

Whether the settings of this machine have been modified

(but neither yet saved nor discarded).

<note>

Reading this property is only valid on instances returned

by <link to="ISession::machine"/> and on new machines

created by <link to="IVirtualBox::createMachine"/> or opened

by <link to="IVirtualBox::openMachine"/> but not

yet registered, or on unregistered machines after calling

<link to="IVirtualBox::unregisterMachine"/>. For all other

cases, the settigs can never be modified.

</note>

<note>

For newly created unregistered machines, the value of this

property is always TRUE until <link to="#saveSettings()"/>

is called (no matter if any machine settings have been

changed after the creation or not). For opened machines

the value is set to FALSE (and then follows to normal rules).

</note>

</desc>

</attribute>

<attribute name="sessionState" type="SessionState" readonly="yes">

<desc>Current session state for this machine.</desc>

</attribute>

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

<desc>

Type of the session. If <link to="#sessionState"/> is

SessionSpawning or SessionOpen, this attribute contains the

same value as passed to the

<link to="IVirtualBox::openRemoteSession()"/> method in the @a

type parameter. If the session was opened directly using

<link to="IVirtualBox::openSession()"/>, or if

<link to="#sessionState"/> is SessionClosed, the value of this

attribute is @c null.

</desc>

</attribute>

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

<desc>

Identifier of the session process. This attribute contains the

platform-dependent identifier of the process that has opened a

direct session for this machine using the

<link to="IVirtualBox::openSession()"/> call. The returned value

is only valid if <link to="#sessionState"/> is SessionOpen or

SessionClosing (i.e. a session is currently open or being

closed) by the time this property is read.

</desc>

</attribute>

<attribute name="state" type="MachineState" readonly="yes">

<desc>Current execution state of this machine.</desc>

</attribute>

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

<desc>

Time stamp of the last execution state change,

in milliseconds since 1970-01-01 UTC.

</desc>

</attribute>

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

<desc>

Full path to the file that stores the execution state of

the machine when it is in the <link to="MachineState::Saved"/>

state.

<note>

When the machine is not in the Saved state, this attribute

<tt>null</tt>.

</note>

</desc>

</attribute>

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

<desc>

Full path to the folder that stores a set of rotated log files

recorded during machine execution. The most recent log file is

named <tt>VBox.log</tt>, the previous log file is

named <tt>VBox.log.1</tt> and so on (upto <tt>VBox.log.3</tt>

in the current version).

</desc>

</attribute>

<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">

<desc>

Current snapshot of this machine.

<note>

A <tt>null</tt> object is returned if the machine doesn't

have snapshots.

</note>

<see><link to="ISnapshot"/></see>

</desc>

</attribute>

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

<desc>

Number of snapshots taken on this machine. Zero means the

machine doesn't have any snapshots.

</desc>

</attribute>

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

<desc>

Returns <tt>true</tt> if the current state of the machine is not

identical to the state stored in the current snapshot.

The current state is identical to the current snapshot right

after one of the following calls are made:

<ul>

<li><link to="IConsole::discardCurrentState"/> or

<link to="IConsole::discardCurrentSnapshotAndState"/>

</li>

<li><link to="IConsole::takeSnapshot"/> (issued on a

powered off or saved machine, for which

<link to="#settingsModified"/> returns <tt>false</tt>)

</li>

<li><link to="IMachine::setCurrentSnapshot"/>

</li>

</ul>

The current state remains identical until one of the following

happens:

<ul>

<li>settings of the machine are changed</li>

<li>the saved state is discarded</li>

<li>the current snapshot is discarded</li>

<li>an attempt to execute the machine is made</li>

</ul>

<note>

For machines that don't have snapshots, this property is

always <tt>false</tt>.

</note>

</desc>

</attribute>

<attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">

<desc>

Collection of shared folders for this machine (permanent shared

folders). These folders are shared automatically at machine startup

and available only to the guest OS installed within this machine.

New shared folders are added to the collection using

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

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

</desc>

</attribute>

<attribute name="clipboardMode" type="ClipboardMode">

<desc>

Synchronization mode between the host OS clipboard

and the guest OS clipboard.

</desc>

</attribute>

<method name="setBootOrder">

<desc>

Puts the given device to the specified position in

the boot order.

To indicate that no device is associated with the given position,

<link to="DeviceType::Null"/> should be used.

@todo setHardDiskBootOrder(), setNetworkBootOrder()

</desc>

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

<desc>

Position in the boot order (<tt>1</tt> to the total number of

devices the machine can boot from, as returned by

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

</desc>

</param>

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

<desc>

The type of the device used to boot at the given position.

</desc>

</param>

</method>

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

<desc>

Returns the device type that occupies the specified

position in the boot order.

@todo [remove?]

If the machine can have more than one device of the returned type

(such as hard disks), then a separate method should be used to

retrieve the individual device that occupies the given position.

If here are no devices at the given position, then

<link to="DeviceType::Null"/> is returned.

@todo getHardDiskBootOrder(), getNetworkBootOrder()

</desc>

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

<desc>

Position in the boot order (<tt>1</tt> to the total number of

devices the machine can boot from, as returned by

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

</desc>

</param>

<param name="device" type="DeviceType" dir="return">

<desc>

Device at the given position.

</desc>

</param>

</method>

<method name="attachHardDisk">

<desc>

Attaches a virtual hard disk identified by the given UUID to the

given device slot of the given channel on the given bus. The

specified device slot must not have another disk attached and the

given hard disk must not be already attached to this machine.

See <link to="IHardDisk"/> for detailed information about

attaching hard disks.

<note>You cannot attach a hard disk to a running machine. Also,

you cannot attach a hard disk to a newly created machine until

it is registered.</note>

<note>Attaching a hard disk to a machine creates a <i>lazy</i>

attachment. In particular, no differeincing images are

actually created until <link to="#saveSettings()"/> is called to

commit all changed settings.</note>

</desc>

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

<desc>UUID of the hard disk to attach.</desc>

</param>

<param name="bus" type="StorageBus" dir="in">

<desc>Type of storage bus to use (IDE or SATA).</desc>

</param>

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

<desc>Channel to attach the hard disk to. For IDE controllers,

this can either be 0 or 1, for the primary or secondary controller,

respectively.</desc>

</param>

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

<desc>Device slot in the given channel to attach the hard disk to.

For IDE devices, within each channel (0 or 1), this can again be

0 or 1, for master or slave, respectively.</desc>

</param>

</method>

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

<desc>

Returns the hard disk attached to the

given controller under the specified device number.

</desc>

<param name="bus" type="StorageBus" dir="in"/>

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

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

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

</method>

<method name="detachHardDisk">

<desc>

Detaches the hard disk drive attached to the given device slot

of the given controller.

See <link to="IHardDisk"/> for detailed information about

attaching hard disks.

<note>You cannot detach a hard disk from a running

machine.</note>

<note>

Detaching a hard disk from a machine creates a <i>lazy</i>

detachment. In particular, if the detached hard disk is a

differencing hard disk, it is not actually deleted until

<link to="#saveSettings()"/> is called to commit all changed settings.

Keep in mind, that doing <link to="#saveSettings()"/> will

<b>physically delete</b> all detached differencing hard disks,

so be careful.

</note>

</desc>

<param name="bus" type="StorageBus" dir="in">

<desc>Bus to dettach the hard disk from.</desc>

</param>

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

<desc>Channel number to dettach the hard disk from.</desc>

</param>

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

<desc>Device slot number to dettach the hard disk from.</desc>

</param>

</method>

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

<desc>

Returns the network adapter associated with the given slot.

Slots are numbered sequentially, starting with zero. The total

number of adapters per every machine is defined by the

<link to="ISystemProperties::networkAdapterCount"/> property,

so the maximum slot number is one less than that property's value.

</desc>

<param name="slot" type="unsigned long" dir="in"/>

<param name="adapter" type="INetworkAdapter" dir="return"/>

</method>

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

<desc>

Returns the serial port associated with the given slot.

Slots are numbered sequentially, starting with zero. The total

number of serial ports per every machine is defined by the

<link to="ISystemProperties::serialPortCount"/> property,

so the maximum slot number is one less than that property's value.

</desc>

<param name="slot" type="unsigned long" dir="in"/>

<param name="port" type="ISerialPort" dir="return"/>

</method>

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

<desc>

Returns the parallel port associated with the given slot.

Slots are numbered sequentially, starting with zero. The total

number of parallel ports per every machine is defined by the

<link to="ISystemProperties::parallelPortCount"/> property,

so the maximum slot number is one less than that property's value.

</desc>

<param name="slot" type="unsigned long" dir="in"/>

<param name="port" type="IParallelPort" dir="return"/>

</method>

<method name="getNextExtraDataKey">

<desc>

Returns the machine-specific extra data key name following the

supplied key.

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

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

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

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

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

</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 machine-specific extra data.

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

succeed and return @c NULL in the @a value argument.

</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 machine-specific extra data.

If you pass @c NULL as a key @a vaule, 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>

<note>

This method can be called outside the machine session and therefore

it's a caller's responsibility to handle possible race conditions

when several clients change the same key at the same time.

</note>

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

<desc>

Saves any changes to machine settings made since the session

has been opened or a new machine has been created, or since the

last call to <link to="#saveSettings()"/> or <link to="#discardSettings()"/>.

For registered machines, new settings become visible to all

other VirtualBox clients after successful invocation of this

method.

<note>

The method sends <link to="IVirtualBoxCallback::onMachineDataChange()"/>

notification event after the configuration has been successfully

saved (only for registered machines).

</note>

<note>