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

<module

name="VirtualBox"

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

version="1.0"

desc="InnoTek VirtualBox Machine Type Library"

supportsErrorInfo="yes"

>

<!--

<enum

name="TriStateBool"

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

>

<desc>

This represents a 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="b8bb15f7-4fa2-4e84-87a8-b4677dd87deb"

>

<desc>

Virtual machine execution state. This enumeration represents possible

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

</desc>

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

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

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

virtual machine. No any settings can be altered when the

VM is in one of the unstable sates.

</note>

</desc>

</const>

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

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

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

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

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

<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="InvalidSessionState" value="0"/>

<const name="SessionClosed" 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="SessionOpen" 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="SessionSpawning" 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="SessionClosing" 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="InvalidSessionType" value="0"/>

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

<desc>

Direct session

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

</desc>

</const>

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

<desc>

Remote session

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

</desc>

</const>

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

<desc>

Existing session

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

</desc>

</const>

</enum>

<enum

name="DeviceType"

uuid="8B7F8ADE-E8F7-42a4-9661-9F5092C4DB4C"

>

<desc>

Device type.

</desc>

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

<desc>

No Device. This value is not used by

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

</desc>

</const>

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

<desc>Floppy device.</desc>

</const>

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

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

</const>

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

<desc>Hard disk device.</desc>

</const>

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

<desc>Network device.</desc>

</const>

</enum>

<enum

name="DeviceActivity"

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

>

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

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

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

<const name="DeviceWriting" 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="InvalidUsage" value="0"/>

<const name="PermanentUsage" 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="TemporaryUsage" 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="AllUsage" value="3">

<desc>

Combines PermanentUsage and TemporaryUsage.

</desc>

</const>

</enum>

<enum

name="DiskControllerType"

uuid="1115b810-2ee7-4ebd-8b39-92e98c9a2b48"

>

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

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

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

</enum>

<enum

name="ClipboardMode"

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

>

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

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

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

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

</enum>

<!--

<interface

name="IVirtualBoxErrorInfo" extends="$errorinfo"

uuid="37EDE76D-6E16-4CE4-9D48-2C5A87AFFEA2"

supportsErrorInfo="no"

>

<desc>

The IVirtualBoxErrorInfo interface represents extended error information

that can be set by components after unsuccessful method invocation and

returned to the client in addition to the 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.

</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 to 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 to 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 to IErrorInfo::GetSource.

In XPCOM, there is no eqiuvalent.

</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 to nsIException::message.

</note>

</desc>

</attribute>

</interface>

<!--

<interface

name="IVirtualBoxCallback" extends="$unknown"

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

>

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

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

<desc>

The given machine was registered within this VirtualBox

installation or unregistered, as described by the

boolean argument.

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

deregistered.

</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="E1D95593-F579-4F47-B489-0B67181014E1"

>

<desc>

The main interface exposed by the product that provides

virtual machine management.

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

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

<desc>

A 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 globally shared folders. These folders

are shared automatically upon VirtualBox server startup and

available only to every virtual machine.

New folders to share are added to the collection using

<link to="#createSharedFolder"/>. An existing shared folder can

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

</desc>

</attribute>

<method name="createMachine">

<desc>

Creates a new virtual machine.

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>. Both the subfolder

and the settings file have the same 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>

Note that the configuration of the newly created machine is not

saved to disk (and therefore no settings subfolder and file are

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

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="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 authomatically renamed when the machine name is

changed -- it will always remain the same as specified in this

method call.

The specified settings file name can be absolute

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

VirtualBox home directory</link>. If the file name doesn't

contain an extension, the default extension (.xml) will be

appended.

Note that the configuration of the newly created machine is not

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

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

specified settings file already exists,

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

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

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

</method>

<method name="findMachine">

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

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

<desc>

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

<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::AllUsage"/>

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::AllUsage"/>

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

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

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

</method>

<method name="createSharedFolder">

<desc>

Creates a new 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

about logical name unicity.

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

</method>

<method name="removeSharedFolder">

<desc>

Removes a 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 extra data key name following the supplied key.

An error is returned if the supplied key does not exist.

NULL is returned if the supplied key is the last key.

When supplying NULL for the key, the first item is returned.

NextValue is an optional parameter and if supplied, the next

key's value is returned as well.

</desc>

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

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

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

</method>

<method name="getExtraData">

<desc>Returns associated extra data.</desc>

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

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

</method>

<method name="setExtraData">

<desc>Sets associated extra data.</desc>

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

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

</method>

<method name="openSession">

<desc>

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

<p>Upon successful return, the session object can be used to

get access to the machine and to the VM console.

</p>

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

<p>Opens a new remote session with the given virtual

machine. Opening the remote session causes the 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 (using the IConsole interface) to the caller. Within

the remote session context, it is not possible to change any

static VM settings (such as name, HDD configuration, etc.).</p>

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

</p>

<note>

It is impossible 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>

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

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

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

<desc>

Type of the remote session (case sensitive). Currently

supported values are:

<ul>

<li><tt>gui</tt>: Qt-based VM session</li>

<li><tt>rdp</tt>: VRDP server session</li>

</ul>

</desc>

</param>

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

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

</param>

</method>

<method name="openExistingSession">

<desc>

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

the remote session context, it is not possible to change any

static VM settings (such as name, HDD configuration, etc.).</p>

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

remote sessions opened this way is not limited by the API.</p>

<note>

It is impossible 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">

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

</method>

<method name="unregisterCallback">

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

</method>

</interface>

<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F">

<interface name="IVirtualBox" default="yes"/>

</class>

<!--

<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="F466BF2E-BD6B-4af0-9C08-46DD42B28A44"

internal="yes"

>

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

<desc>

Returns the full name of the directory where to store

log files created during this machine's executoin.

</desc>

<param name="logFolder" 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="return"/>

</method>

<method name="captureUSBDevice">

<desc>

Requests a capture of the given host USB device, and returns

the captured device (as IUSBDevice) to the caller.

<note>

The server must mark the device as USBDeviceCaptured

during this call.

This method must return extended error info in case of any

eroror (<link to="IConsole::detachUSBDevice()"/>) relies

on this.

</note>

</desc>

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

<param name="hostDevice" type="IUSBDevice" dir="return"/>

</method>

<method name="releaseUSBDevice">

<desc>

Releases the given USB device.

<note>

The server must run its own filters and filters of all VMs

but this one on the given device as if it were just attached

to the host computer.

</note>

</desc>

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

</method>

<method name="autoCaptureUSBDevices">

<desc>

Queries the list of available devices that must be auto-captured

according to this VM's filters. Devices returned as IUSBDevice

instances.

<note>

The server must mark all returned devices as USBDeviceCaptured

during this call.

</note>

</desc>

<param name="hostDevices" type="IUSBDeviceCollection" dir="return"/>

</method>

<method name="releaseAllUSBDevices">

<desc>

Releases all USB devices that are captured by this VM because

the VM has been terminated.

<note>

The server must run its own filters and filters of all VMs

but this one on all released devices as if they were just

attached to the host computer.

</note>

</desc>

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

<enum

name="BIOSBootMenuMode"

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

>

<desc>

This represents the BIOS boot menu state.

</desc>

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

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

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

</enum>

<interface

name="IBIOSSettings" extends="$unknown"

uuid="00fff9d7-983e-462d-a1aa-4cc26de4f0d4"

>

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

</interface>

<interface

name="IMachine" extends="$unknown"

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

>

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

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

</attribute>

<attribute name="OSType" type="IGuestOSType">

<desc>

Guest OS type configured by the user.

<note>

This value may differ from the value returned by

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

installed to the guest OS.

</note>

</desc>

</attribute>

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

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

</attribute>

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

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

</attribute>

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

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

</attribute>

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

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

</attribute>

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

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

</attribute>

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

<desc>

Full name of the file containing machine settings data.

</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="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="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. These folders

are shared automatically upon machine startup and available only

to the guest OS installed within this machine.

New folders to share are added to the collection using

<link to="#createSharedFolder"/>. An existing shared folder 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.

@todo [remove?]

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

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

specify the boot order for individual devices. Using this method

in such cases will put the first device in the group

(for example, a hard disk attached as Master on the primary

IDE controller) to the given position.

To indicate that no any device is associated with the

given position, <link to="DeviceType::NoDevice"/> 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::NoDevice"/> 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 controller. The specified device

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

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

</param>

<param name="controller" type="DiskControllerType" dir="in">

<desc>Controller to attach the hard disk to.</desc>

</param>

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

<desc>Device slot to attach the hard disk to.</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="controller" type="DiskControllerType" dir="in"/>

<param name="deviceNumber" 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="controller" type="DiskControllerType" dir="in">

<desc>Controller to dettach the hard disk from.</desc>

</param>

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

<desc>Device slot 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="getNextExtraDataKey">

<desc>

Returns the extra data key name following the supplied key.

An error is returned if the supplied key does not exist.

NULL is returned if the supplied key is the last key.

When supplying NULL for the key, the first item is returned.

NextValue is an optional parameter and if supplied, the next

key's value is returned as well.

</desc>

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

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

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

</method>

<method name="getExtraData">

<desc>Returns associated extra data.</desc>

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

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

</method>

<method name="setExtraData">

<desc>Sets associated extra data.</desc>

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

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

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

Calling this method is only valid on instances returned

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

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

yet registered, or on unregistered machines after calling

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

</note>

</desc>

</method>

<method name="discardSettings">

<desc>

Discards any changes to the machine settings made since the session

has been opened or since the last call to <link to="#saveSettings"/>

or <link to="#discardSettings"/>.

<note>

Calling this method 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"/>.

</note>

</desc>

</method>

<method name="deleteSettings">

<desc>

Deletes the settings file of this machine from disk.

The machine must not be registered in order for this operation

to succeed.

<note>

<link to="#settingsModified"/> will return TRUE after this

method successfully returns.

</note>

<note>

Calling this method 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"/>.

</note>

<note>

The deleted machine settings file can be restored (saved again)

by calling <link to="#saveSettings"/>.

</note>

</desc>

</method>

<method name="getSnapshot">

<desc>

Returns a snapshot of this machine with the given UUID.

A <tt>null</tt> UUID can be used to obtain the first snapshot

taken on this machine. This is useful if you want to traverse

the whole tree of snapshots starting from the root.

</desc>

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

<desc>UUID of the snapshot to get</desc>

</param>

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

<desc>Snapshot object with the given UUID.</desc>

</param>

</method>

<method name="findSnapshot">

<desc>

Returns a snapshot of this machine with the given name.

</desc>

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

<desc>Name of the snapshot to find</desc>

</param>

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

<desc>Snapshot object with the given name.</desc>

</param>

</method>

<method name="setCurrentSnapshot">

<desc>

Sets the current snapshot of this machine.

<note>

In the current implementation, this operation is not

implemented.

</note>

</desc>

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

<desc>UUID of the snapshot to set as the current snapshot.</desc>

</param>

</method>

<method name="createSharedFolder">

<desc>

Creates a new 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

about logical name unicity.

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

</method>

<method name="removeSharedFolder">

<desc>

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

</interface>

<!--

<interface

name="IConsoleCallback" extends="$unknown"

uuid="05D3DD3F-0550-4953-BB3C-4ECB3EBF7C2E"

>

<method name="onMousePointerShapeChange">

<desc>

Notification when the guest mouse pointer shape has

changed. The new shape data is given.

</desc>

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

<desc>

Flag whether the pointer is visible.

</desc>

</param>

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

<desc>

Flag whether the pointer has an alpha channel.

</desc>

</param>

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

<desc>

The pointer hot spot x coordinate.

</desc>

</param>

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

<desc>

The pointer hot spot y coordinate.

</desc>

</param>

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

<desc>

Width of the pointer shape in pixels.

</desc>

</param>

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

<desc>

Height of the pointer shape in pixels.

</desc>

</param>

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

<desc>

Address of the shape buffer.

The buffer contains 1 bpp (bits per pixel) AND mask followed by 32 bpp XOR (color) mask.

For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb).

For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.

AND mask presents for pointers with alpha channel, so if the callback does not

support alpha, the pointer could be displayed as a normal color pointer.

The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND mask,

therefore, is <tt>cbAnd = (width + 7) / 8 * height</tt>. The padding bits at the

end of any scanline are undefined.

The XOR mask follows the AND mask on the next 4 bytes aligned offset:

<tt>uint8_t *pXor = pAnd + (cbAnd + 3) &amp; ~3</tt>

Bytes in the gap between the AND and the XOR mask are undefined.

XOR mask scanlines have no gap between them and size of XOR mask is:

<tt>cXor = width * 4 * height</tt>.

<note>

If 'shape' is equal to 0, only pointer visibility is being changed.

</note>

</desc>

</param>

</method>

<method name="onMouseCapabilityChange">

<desc>

Notification when the mouse capabilities reported by the

guest have changed. The new capabilities are passed.

</desc>

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

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

</method>

<method name="onKeyboardLedsChange">

<desc>

Notification of the host if the guest executed the KBD_CMD_SET_LEDS

command to alter the state of the keyboard LEDs.

</desc>

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

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

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

</method>

<method name="onStateChange">

<desc>

Notification when the execution state of the machine has changed.

The new state will be given.

</desc>

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

</method>

<method name="onAdditionsStateChange">

<desc>

Notification when a Guest Additions property changes.

Interested callees should query IGuest's properties to

find out what has changed.

</desc>

</method>

<method name="onRuntimeError">

<desc>

Notification when an error happens during the virtual

machine execution.

There are three kinds of runtime errors:

<ul>

<li><i>fatal</i></li>

<li><i>non-fatal with retry</i></li>

<li><i>non-fatal without retry</i></li>

</ul>

<b>Fatal</b> errors are indicated by the @a fatal parameter set

to <tt>true</tt>. In case of fatal errors, the virtual machine

execution is always paused before calling this notification, and

the notification handler is supposed either to immediately save

the virtual machine state using <link to="IConsole::saveState()"/>

or power it off using <link to="IConsole::powerDown()"/>.

Resuming the execution can lead to unpredictable results.

<b>Non-fatal</b> errors are indicated by the

@a fatal parameter set to <tt>false</tt>. If the virtual machine

is in the Paused state by the time the error notification is

received, it means that the user can retry the machine

execution after attempting to solve the probem that caused the

error. In this case, the notification handler is supposed

to show an appropriate message to the user (depending on the

value of the @a id parameter) that offers several actions such

as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user

wants to retry, the notification handler should continue

the machine execution using the <link to="IConsole::resume()"/>

call. If the machine execution is not Paused during this

notification, then it means this notification is a warning (for

example, about a fatal condition that can happen very soon); no

any immediate action is required from the user, the machine

continues its normal execution.

Note that in either case the notification handler

<b>must not</b> perform any action directly on a thread

where this notification is called. Everything it is allowed to

do is to post a message to another thread that will then talk

to the user and take the corresponding action.

Currently, the following error identificators are known:

<ul>

<li>"HostMemoryLow"</li>

<li>"HostAudioNotResponding"</li>

<li>"VDIStorageFull"</li>

</ul>

<note>

This notification is not designed to be implemented by more

than one callback at a time. If you have multiple

IConsoleCallback instances registered on the given

IConsole object, make sure you just return S_OK from all but

one of them that does actual user notification and performs

necessary actions.

</note>

</desc>

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

<desc>Whether the error is fatal or not</desc>

</param>

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

<desc>Error identificator</desc>

</param>

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

<desc>Optional error message</desc>

</param>

</method>

</interface>

<interface

name="IRemoteDisplayInfo" extends="$unknown"

uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"

>

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

<desc>

Whether the remote display connection is active.

</desc>

</attribute>

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

<desc>

How many times a client connected.

</desc>

</attribute>

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

<desc>

When the last connection was established, in milliseconds since 1970-01-01 UTC.

</desc>

</attribute>

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

<desc>

When the last connection was terminated or the current time, if

connection is still active, in milliseconds since 1970-01-01 UTC.

</desc>

</attribute>

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

<desc>

How many bytes were sent in last or current, if still active, connection.

</desc>

</attribute>

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

<desc>

How many bytes were sent in all connections.

</desc>

</attribute>

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

<desc>

How many bytes were received in last or current, if still active, connection.

</desc>

</attribute>

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

<desc>

How many bytes were received in all connections.

</desc>

</attribute>

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

<desc>

Login user name supplied by the client.

</desc>

</attribute>

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

<desc>

Login domain name supplied by the client.

</desc>

</attribute>

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

<desc>

The client name supplied by the client.

</desc>

</attribute>

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

<desc>

The IP address of the client.

</desc>

</attribute>

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

<desc>

The client software version number.

</desc>

</attribute>

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

<desc>

Public key exchange method used when connection was established.

Values: 0 - RDP4 public key exchange scheme.

1 - X509 sertificates were sent to client.

</desc>

</attribute>

</interface>

<interface

name="IConsole" extends="$unknown"

uuid="1DEA5C4B-0753-4193-B909-22330F64EC45"

>

<attribute name="machine" type="IMachine" readonly="yes">

<desc>

Machine object this console is sessioned with.

<note>

This is a convenience property, it has the same value as

<link to="ISession::machine"/> of the corresponding session

object.

</note>

</desc>

</attribute>

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

<desc>

Current execution state of the machine.

<note>

This property always returns the same value as the corresponding

property of the IMachine object this console is sessioned with.

For the process, that owns (executes) the VM, this is the

preferrable way of quierying the VM state, because no IPC

calls are made.

</note>

</desc>

</attribute>

<attribute name="guest" type="IGuest" readonly="yes">

<desc>Guest object.</desc>

</attribute>

<attribute name="keyboard" type="IKeyboard" readonly="yes">

<desc>

Virtual keyboard object.

<note>

If the machine is not running, any attempt to use

the returned object will result in an error.

</note>

</desc>

</attribute>

<attribute name="mouse" type="IMouse" readonly="yes">

<desc>

Virtual mouse object.

<note>

If the machine is not running, any attempt to use

the returned object will result in an error.

</note>

</desc>

</attribute>

<attribute name="display" type="IDisplay" readonly="yes">

<desc>Virtual display object.

<note>

If the machine is not running, any attempt to use

the returned object will result in an error.

</note>

</desc>

</attribute>

<attribute name="debugger" type="IMachineDebugger" readonly="yes">

<desc>Debugging interface.</desc>

</attribute>

<attribute name="USBDevices" type="IUSBDeviceCollection" readonly="yes">

<desc>

Collection of USB devices currently attached to the virtual

USB controller.

<note>

The collection is empty if the machine is not running.

</note>

</desc>

</attribute>

<attribute name="remoteUSBDevices" type="IHostUSBDeviceCollection" readonly="yes">

<desc>

List of USB devices currently attached to the remote VRDP client.

Once a new device is physically attached to the remote host computer,

it appears in this list and remains there until detached.

</desc>

</attribute>

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

<desc>

Collection of shared folders for the current session.

This collection is initially empty and is cleared once the

session is closed. On other words, this collection represents

transient shares (as opposed to <link to="IMachine::sharedFolders"/>

that stores permanent shares stored in the settings file).

New folders to share are added to the collection using

<link to="#createSharedFolder"/>. An existing shared folder can

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

</desc>

</attribute>

<attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">

<desc>

Interface that provides information on Remote Display (VRDP) connection.

</desc>

</attribute>

<method name="powerUp">

<desc>

Starts the virtual machine execution using the current machine

state (i.e. its current execution state, current settings and

current hard disks).

If the machine is powered off or aborted, the execution will

start from the beginning (as if the real hardware were just

powered on).

If the machine is in the <link to="MachineState::Saved"/> state,

it will continue its execution the point where the state has

beem saved.

<see>#saveState</see>

</desc>

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

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

</param>

</method>

<method name="powerDown">

<desc>

Stops the virtual machine execution.

After this operation completes, the machine will go to the

PoweredOff state.

</desc>

</method>

<method name="reset">

<desc>Resets the virtual machine.</desc>

</method>

<method name="pause">

<desc>Pauses the virtual machine execution.</desc>

</method>

<method name="resume">

<desc>Resumes the virtual machine execution.</desc>

</method>

<method name="powerButton">

<desc>Send the ACPI power button event to the guest.</desc>

</method>

<method name="saveState">

<desc>

Saves the current execution state of a running virtual machine

and stops its executiuon.

After this operation completes, the machine will go to the

Saved state. Next time it is powered up, this state will

be restored and the machine will continue its execution from

the place where it was saved.

This operation differs from taking a snapshot to the effect

that it doesn't create new differencing hard disks. Also, once

the machine is powered up from the state saved using this method,

the saved state is deleted, so it will be impossible to return

to this state later.

<note>On success, this method implicitly calls <link

to="IMachine::saveSettings"/> to save all current machine

settings (including runtime changes to the DVD drive, etc.).

Together with the impossibility to change any VM settings when

it is in the Saved state, this guarantees the adequate hardware

configuration of the machine when it is restored from the saved

state file.</note>

<note>

The machine must be in the Running or Paused state, otherwise

the operation will fail.

</note>

<see><link to="#takeSnapshot"/></see>

</desc>

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

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

</param>

</method>

<method name="discardSavedState">

<desc>

Discards (deletes) the saved state of the virtual machine

previously created by <link to="#saveState"/>. Next time the

machine is powered up, a clean boot will occur.

<note>

This operation is equivalent to resetting or powering off

the machine without doing a proper shutdown in the guest OS.

</note>

</desc>

</method>

<method name="getDeviceActivity">

<desc>

Gets the current activity type of a given device or device group.

</desc>

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

<param name="activity" type="DeviceActivity" dir="return"/>

</method>

<method name="attachUSBDevice">

<desc>

Attaches a host USB device with the given UUID to the

USB controller of the virtual machine.

The device needs to be in one of the following states:

<link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,

<link to="USBDeviceState::USBDeviceAvailable">USBDeviceAvailable</link> or

<link to="USBDeviceState::USBDeviceHeld">USBDeviceHeld</link>,

otherwise an error is immediately returned.

When the device state is

<link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,

an error may also be returned if the host computer

refuses to release it for some reason.

<see>IUSBController::DeviceFilters, USBDeviceState</see>

</desc>

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

<desc>UUID of the host USB device to attach.</desc>

</param>

</method>

<method name="detachUSBDevice">

<desc>

Detaches an USB device with the given UUID from the USB controller

oif the virtual machine.

After this method succeeds, the VirtualBox server reinitiates

all USB filters as if the device were just physically attached

to the host, but filters of this machine are ignored to avoid

a possible automatic reattachment.

<see>IUSBController::DeviceFilters, USBDeviceState</see>

</desc>

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

<desc>UUID of the USB device to detach.</desc>

</param>

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

<desc>Detached USB device.</desc>

</param>

</method>

<method name="createSharedFolder">

<desc>

Creates a new 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

about logical name unicity.

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

</method>

<method name="removeSharedFolder">

<desc>

Removes a 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="takeSnapshot">

<desc>

Saves the current execution state and all settings of the

machine and creates differencing images for all

normal (non-independent) hard disks.

This method can be called for a PoweredOff, Saved, Running or

Paused virtual machine. When the machine is PoweredOff, an

offline <link to="ISnapshot">snapshot</link> is created,

in all other cases -- an online snapshot.

The taken snapshot is always based on the

<link to="IMachine::currentSnapshot">current

snapshot</link> of the associated virtual machine and becomes

a new current snapshot.

<note>This method implicitly calls <link

to="IMachine::saveSettings"/> to save all current machine

settings before taking an offline snapshot.</note>

<see>ISnapshot, <link to="#saveState"/></see>

</desc>

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

<desc>Short name for the snapshot.</desc>

</param>

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

<desc>Optional description of the snapshot.</desc>

</param>

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

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

</param>

</method>

<method name="discardSnapshot">

<desc>

Starts discarding the specified snapshot. The execution state

and settings of the associated machine stored in the snapshot

will be deleted. The contents of all differencing hard disks of

this snapshot will be merged with the contents of their

dependent child hard disks to keep the, disks valid (in other

words, all changes represented by hard disks being discarded

will be propagated to their child hard disks). After that, this

snapshot's differencing hard disks will be deleted. The parent

of this snapshot will become a new parent for all its child

snapshots.

If the discarded snapshot is the current one, its parent

snapshot will become a new current snapshot. The current machine

state is not directly affected in this case, except that

currently attached differencing hard disks based on hard disks

of the discarded snapshot will be also merged as described

above.

If the discarded snapshot is the first one (the root snapshot)

and it has exactly one child snapshot, this child snapshot will

become the first snapshot after discarding. If there are no

children at all (i.e. the first snapshot is the only snapshot of

the machine), both the current and the first snapshot of the

machine will be set to null. In all other cases, the first

snapshot cannot be discarded.

You cannot discard the snapshot if it stores <link

to="HardDiskType::NormalHardDisk">normal</link>

(non-differencing) hard disks that have differencing hard disks

based on them. Snapshots of such kind can be discarded only when

every normal hard disk has either no children at all or exactly

one child. In the former case, the normal hard disk simply

becomes unused (i.e. not attached to any VM). In the latter

case, it receives all the changes strored in the child hard

disk, and then it replaces the child hard disk in the

configuration of the corresponding snapshot or machine.

Also, you cannot discard the snapshot if it stores hard disks

(of any type) having differencing child hard disks that belong

to other machines. Such snapshots can be only discarded after

you discard all snapshots of other machines containing "foreign"

child disks, or detach these "foreign" child disks from machines

they are attached to.

One particular example of the snapshot storing normal hard disks

is the first snapshot of a virtual machine that had normal hard

disks attached when taking the snapshot. Be careful when

discarding such snapshots because this implicitly commits

changes (made since the snapshot being discarded has been taken)

to normal hard disks (as described above), which may be not what

you want.

The virtual machine is put to the <link

to="MachineState::Discarding">Discarding</link> state until the

discard operation is completed.

<note>The machine must not be running, otherwise the operation

will fail.</note>

<note>

Child hard disks of all normal hard disks of the

discarded snapshot must be <link to="IHardDisk::accessible">

accessible</link> for this operation to succeed.

In particular, this means that all virtual machines,

whose hard disks are directly or indirectly based on

the hard disks of discarded snapshot, must be powered off.

</note>

<note>

Merging hard disk contents can be very time and disk space

consuming, if these disks are big in size and have many

children. However, if the snapshot being discarded is the last

(head) snapshot on the branch, the operation will be rather

quick.

</note>

<note>

Note that discarding the current snapshot

will imlicitly call <link to="IMachine::saveSettings()"/> to

make all current machine settings permanent.

</note>

</desc>

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

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

</param>

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

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

</param>

</method>

<method name="discardCurrentState">

<desc>

This operation is similar to <link to="#discardSnapshot()"/> but

affects the current machine state. This means that the state stored

in the current snapshot will become a new current state, and

all current settings of the machine and changes stored in

differencing hard disks will be lost.

After this operation is successfully completed, new empty

differencing hard disks are created for all normal hard disks

of the machine.

If the current snapshot of the machine is an online snapshot,

the machine will go to the <link to="MachineState::Saved">

saved state</link>, so that the next time it is powered on,

the execution state will be restored from the current snapshot.

<note>The machine must not be running, otherwise the operation

will fail.</note>

<note>If the machine state is <link

to="MachineState::Saved">Saved</link> prior to this operation,

the saved state file will be implicitly discarded (as if <link

to="IConsole::discardSavedState()"/> were called).</note>

</desc>

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

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

</param>

</method>

<method name="discardCurrentSnapshotAndState">

<desc>

This method is equivalent to doing <link

to="#discardSnapshot">discardSnapshot</link> (<link

to="IMachine::currentSnapshot">currentSnapshot</link>.<link

to="ISnapshot::id">id()</link>, ...) followed by <link

to="#discardCurrentState()"/>.

As a result, the machine will be fully restored from the

snapshot preceeding the current snapshot, while both the current

snapshot and the current machine state will be discarded.

If the current snapshot is the first snapshot of the machine

(i.e. it has the only snapshot), the current machine state will

be discarded <b>before</b> discarding the snapshot. In other

words, the machine will be restored from its last snapshot,

before discarding it. This differs from performing a single

<link to="#discardSnapshot()"/> call (note that no <link

to="#discardCurrentState()"/> will be possible after it) to the

effect that the latter will preserve the current state instead

of discarding it.

Unless explicitly mentioned otherwise, all remarks and

limitations of the above two methods also apply to this method.

<note>The machine must not be running, otherwise the operation

will fail.</note>

<note>If the machine state is <link

to="MachineState::Saved">Saved</link> prior to this operation,

the saved state file will be implicitly discarded (as if <link

to="IConsole::discardSavedState()"/> were called).</note>

<note>

This method is more efficient than calling two above

methods separately: it requires less IPC calls and provides

a single progress object.

</note>

</desc>

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

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

</param>

</method>

<method name="registerCallback">

<param name="callback" type="IConsoleCallback" dir="in"/>

<desc>

Registers a new console callback on this instance. The methods of the

callback interface will be called by this instance when the appropriate

event occurs.

</desc>

</method>

<method name="unregisterCallback">

<param name="callback" type="IConsoleCallback" dir="in"/>

<desc>

Unregisters the console callback previously registered using

<link to="#registerCallback"/>.

</desc>

</method>

</interface>

<!--

<interface

name="IHostDVDDrive" extends="$unknown"

uuid="c2308775-85f3-45ab-ade5-97f02d1e61e0"

>

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

<desc>Returns the platform device identifier.</desc>

</attribute>

</interface>

<enumerator

name="IHostDVDDriveEnumerator" type="IHostDVDDrive"

uuid="1ed7cfaf-c363-40df-aa4e-89c1afb7d96b"

/>

<collection

name="IHostDVDDriveCollection" type="IHostDVDDrive"

enumerator="IHostDVDDriveEnumerator"

uuid="1909c533-1a1e-445f-a4e1-a267cffc30ed"

readonly="yes"

>

<method name="findByName">

<desc>

Searches this collection for a host drive with the given name.

<note>

The method returns an error if the given name does not

correspond to any host drive in the collection.

</note>

</desc>

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

<desc>Name of the host drive to search for</desc>

</param>

<param name="drive" type="IHostDVDDrive" dir="return">

<desc>Found host drive object</desc>

</param>

</method>

</collection>

<interface

name="IHostFloppyDrive" extends="$unknown"

uuid="2b2ad1ab-2ea9-4cf8-be3c-2a76677d8725"

>

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

<desc>Returns the platform device identifier.</desc>

</attribute>

</interface>

<enumerator

name="IHostFloppyDriveEnumerator" type="IHostFloppyDrive"

uuid="ce04c924-4f54-432a-9dec-11fddc3ea875"

/>

<collection

name="IHostFloppyDriveCollection" type="IHostFloppyDrive"

enumerator="IHostFloppyDriveEnumerator"

uuid="fd84bb86-c59a-4037-a557-755ff263a460"

readonly="yes"

>

<method name="findByName">

<desc>

Searches this collection for a host drive with the given name.

<note>

The method returns an error if the given name does not

correspond to any host drive in the collection.

</note>

</desc>

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

<desc>Name of the host drive to search for</desc>

</param>

<param name="drive" type="IHostFloppyDrive" dir="return">

<desc>Found host drive object</desc>

</param>

</method>

</collection>

<if target="midl">

<interface

name="IHostNetworkInterface" extends="$unknown"

uuid="F4512D7C-B074-4e97-99B8-6D2BD27C3F5A"

>

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

<desc>Returns the host network interface name.</desc>

</attribute>

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

<desc>Returns the interface UUID.</desc>