VirtualBox.xidl@ 28835

Last change on this file since 28835 was 28835, checked in by vboxsync, 15 years ago
Main: live snapshot merging. initially limited to forward merging (i.e. everything but the first snapshot can be deleted)
Property svn:eol-style set to `native`
File size: 532.1 KB

Line
1	<?xml version="1.0" ?>
2
3	<!--
4	* :tabSize=2:indentSize=2:noTabs=true:
5	* :folding=explicit:collapseFolds=1:
6	*
7	* Master declaration for VirtualBox's Main API, represented
8	* by COM/XPCOM and web service interfaces.
9	*
10	* From this document, the build system generates several files
11	* via XSLT that are then used during the build process.
12	*
13	* Below is the list of XSL templates that operate on this file and
14	* output files they generate. These XSL templates must be updated
15	* whenever the schema of this file changes:
16	*
17	* 1. src/VBox/Main/idl/midl.xsl =>
18	* out/<platform>/bin/sdk/idl/VirtualBox.idl
19	* (MS COM interface definition file for Main API)
20	*
21	* 2. src/VBox/Main/idl/xpidl.xsl =>
22	* out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
23	* (XPCOM interface definition file for Main API)
24	*
25	* 3. src/VBox/Main/idl/doxygen.xsl =>
26	* out/<platform>/obj/src/VBox/Main/VirtualBox.idl
27	* (pseudo-IDL for Doxygen to generate the official Main API
28	* documentation)
29	*
30	* 4. src/VBox/Main/webservice/*.xsl =>
31	* a bunch of WSDL and C++ files
32	* (VirtualBox web service sources and SOAP mappers;
33	* see src/VBox/Main/webservice/Makefile.kmk for details)
34	*
35	* 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
36	* out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
37	* (smart Qt-based C++ wrapper classes for COM interfaces
38	* of the Main API)
39	*
40	* 6. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
41	* out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
42	* (Main API TypeLib block for the WiX installer)
43	*
44	* 7. src/VBox/Runtime/common/err/errmsgvboxcom.xsl =>
45	* out/<platform>/obj/Runtime/errmsgvboxcomdata.h
46	* (<result> extraction for the %Rhrc format specifier)
47	*
48	Copyright (C) 2006-2010 Oracle Corporation
49
50	This file is part of VirtualBox Open Source Edition (OSE), as
51	available from http://www.virtualbox.org. This file is free software;
52	you can redistribute it and/or modify it under the terms of the GNU
53	General Public License (GPL) as published by the Free Software
54	Foundation, in version 2 as it comes in the "COPYING" file of the
55	VirtualBox OSE distribution. VirtualBox OSE is distributed in the
56	hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
57	-->
58
59	<idl>
60
61	<desc>
62	Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
63	describes the so-called <i>VirtualBox Main API</i> which comprises all public
64	COM interfaces and components provided by the VirtualBox server and by the
65	VirtualBox client library.
66
67	VirtualBox employs a client-server design, meaning that whenever any part of
68	VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
69	interface or any virtual machine --, a dedicated server process named
70	VBoxSVC runs in the background. This allows multiple processes working with
71	VirtualBox to cooperate without conflicts. These processes communicate to each
72	other using inter-process communication facilities provided by the COM
73	implementation of the host computer.
74
75	On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
76	implementation. On all other platforms, Mozilla XPCOM, an open-source COM
77	implementation, is used.
78
79	All the parts that a typical VirtualBox user interacts with (the Qt GUI,
80	the VBoxManage command-line interface and the VBoxVRDP server) are technically
81	front-ends to the Main API and only use the interfaces that are documented
82	in this Main API documentation. This ensures that, with any given release
83	version of VirtualBox, all capabilities of the product that could be useful
84	to an external client program are always exposed by way of this API.
85
86	The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
87	contains two public component classes:
88	<tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
89	implement IVirtualBox and ISession interfaces respectively. These two classes
90	are of supreme importance and will be needed in order for any front-end
91	program to do anything useful. It is recommended to read the documentation of
92	the mentioned interfaces first.
93
94	The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
95	there can be only one object of this class on the local machine at any given
96	time. This object is a parent of many other objects in the VirtualBox COM
97	library and lives in the VBoxSVC process. In fact, when you create an instance
98	of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
99	process is already running, starts it if not, and returns you a reference to
100	the <tt>VirtualBox</tt> object created in this process. When the last reference
101	to this object is released, the VBoxSVC process ends (with a 5 second delay to
102	protect from too frequent restarts).
103
104	The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
105	as many <tt>Session</tt> objects as you need but all of them will live in a
106	process which issues the object instantiation call. <tt>Session</tt> objects
107	represent virtual machine sessions which are used to configure virtual
108	machines and control their execution.
109	</desc>
110
111	<if target="midl">
112	<cpp line="enum {"/>
113	<cpp line=" kTypeLibraryMajorVersion = 1,"/>
114	<cpp line=" kTypeLibraryMinorVersion = 0"/>
115	<cpp line="};"/>
116	</if>
117
118	<if target="xpidl">
119	<!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
120	<cpp>
121	/* currently, nsISupportsImpl.h lacks the below-like macros */
122
123	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
124	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
125	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI
126
127	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
128	# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
129	NS_IMPL_THREADSAFE_ADDREF(_class) \
130	NS_IMPL_THREADSAFE_RELEASE(_class) \
131	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
132	NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
133	#endif
134
135	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
136	# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
137	NS_IMPL_THREADSAFE_ADDREF(_class) \
138	NS_IMPL_THREADSAFE_RELEASE(_class) \
139	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
140	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
141	#endif
142
143	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI
144	# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \
145	NS_IMPL_THREADSAFE_ADDREF(_class) \
146	NS_IMPL_THREADSAFE_RELEASE(_class) \
147	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \
148	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
149	#endif
150
151	#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
152	# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
153	NS_INTERFACE_MAP_BEGIN(_class) \
154	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
155	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
156	NS_IMPL_QUERY_CLASSINFO(_class) \
157	NS_INTERFACE_MAP_END
158	#endif
159
160	#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
161	# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
162	_i2, _ic2) \
163	NS_INTERFACE_MAP_BEGIN(_class) \
164	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
165	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
166	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
167	NS_IMPL_QUERY_CLASSINFO(_class) \
168	NS_INTERFACE_MAP_END
169	#endif
170
171	#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
172	# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
173	_i2, _ic2, _i3, _ic3) \
174	NS_INTERFACE_MAP_BEGIN(_class) \
175	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
176	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
177	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \
178	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
179	NS_IMPL_QUERY_CLASSINFO(_class) \
180	NS_INTERFACE_MAP_END
181	#endif
182
183	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
184	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
185	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
186
187	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
188	# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
189	NS_IMPL_THREADSAFE_ADDREF(_class) \
190	NS_IMPL_THREADSAFE_RELEASE(_class) \
191	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
192	NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
193	#endif
194
195	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
196	# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
197	_i2, _ic2) \
198	NS_IMPL_THREADSAFE_ADDREF(_class) \
199	NS_IMPL_THREADSAFE_RELEASE(_class) \
200	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
201	_i2, _ic2) \
202	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
203	#endif
204
205	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI
206	# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \
207	_i2, _ic2, _i3, _ic3) \
208	NS_IMPL_THREADSAFE_ADDREF(_class) \
209	NS_IMPL_THREADSAFE_RELEASE(_class) \
210	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
211	_i2, _ic2, _i3, _ic3) \
212	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
213	#endif
214
215	</cpp>
216	</if>
217
218	<library
219	name="VirtualBox"
220	uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
221	version="1.3"
222	desc="VirtualBox Type Library"
223	appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
224	supportsErrorInfo="yes"
225	>
226
227
228	<!--
229	// COM result codes for VirtualBox
230	/////////////////////////////////////////////////////////////////////////
231	-->
232
233	<descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
234	<desc>
235	This section describes all VirtualBox-specific COM result codes that may
236	be returned by methods of VirtualBox COM interfaces in addition to
237	standard COM result codes.
238
239	Note that along with the result code, every VirtualBox method returns
240	extended error information through the IVirtualBoxErrorInfo interface on
241	failure. This interface is a preferred way to present the error to the end
242	user because it contains a human readable description of the error. Raw
243	result codes, both standard and described in this section, are intended to
244	be used by programs to analyze the reason of a failure and select an
245	appropriate course of action without involving the end user (for example,
246	retry the operation later or make a different call).
247
248	The standard COM result codes that may originate from our methods include:
249
250	<table>
251	<tr><td>E_INVALIDARG</td>
252	<td>
253	Returned when the value of the method's argument is not within the range
254	of valid values. This should not be confused with situations when the
255	value is within the range but simply doesn't suit the current object
256	state and there is a possibility that it will be accepted later (in such
257	cases VirtualBox-specific codes are returned, for example,
258	<link to="VBOX_E_OBJECT_NOT_FOUND"/>).
259	</td>
260	</tr>
261	<tr><td>E_POINTER</td>
262	<td>
263	Returned if a memory pointer for the output argument is invalid (for
264	example, @c null). Note that when pointers representing input
265	arguments (such as strings) are invalid, E_INVALIDARG is returned.
266	</td>
267	</tr>
268	<tr><td>E_ACCESSDENIED</td>
269	<td>
270	Returned when the called object is not ready. Since the lifetime of a
271	public COM object cannot be fully controlled by the implementation,
272	VirtualBox maintains the readiness state for all objects it creates and
273	returns this code in response to any method call on the object that was
274	deactivated by VirtualBox and is not functioning any more.
275	</td>
276	</tr>
277	<tr><td>E_OUTOFMEMORY</td>
278	<td>
279	Returned when a memory allocation operation fails.
280	</td>
281	</tr>
282	</table>
283	</desc>
284	</descGroup>
285
286	<!--
287	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
288	everything in <result>/<desc> after (and including) the first dot, so express
289	the matter of the error code in the first sentence and keep it short.
290	-->
291
292	<result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
293	<desc>
294	Object corresponding to the supplied arguments does not exist.
295	</desc>
296	</result>
297
298	<result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
299	<desc>
300	Current virtual machine state prevents the operation.
301	</desc>
302	</result>
303
304	<result name="VBOX_E_VM_ERROR" value="0x80BB0003">
305	<desc>
306	Virtual machine error occurred attempting the operation.
307	</desc>
308	</result>
309
310	<result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
311	<desc>
312	File not accessible or erroneous file contents.
313	</desc>
314	</result>
315
316	<result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
317	<desc>
318	Runtime subsystem error.
319	</desc>
320	</result>
321
322	<result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
323	<desc>
324	Pluggable Device Manager error.
325	</desc>
326	</result>
327
328	<result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
329	<desc>
330	Current object state prohibits operation.
331	</desc>
332	</result>
333
334	<result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
335	<desc>
336	Host operating system related error.
337	</desc>
338	</result>
339
340	<result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
341	<desc>
342	Requested operation is not supported.
343	</desc>
344	</result>
345
346	<result name="VBOX_E_XML_ERROR" value="0x80BB000A">
347	<desc>
348	Invalid XML found.
349	</desc>
350	</result>
351
352	<result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
353	<desc>
354	Current session state prohibits operation.
355	</desc>
356	</result>
357
358	<result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
359	<desc>
360	Object being in use prohibits operation.
361	</desc>
362	</result>
363
364	<!--
365	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
366	everything in <result>/<desc> after (and including) the first dot, so express
367	the matter of the error code in the first sentence and keep it short.
368	-->
369
370	<descGroup/>
371
372	<!--
373	// all common enums
374	/////////////////////////////////////////////////////////////////////////
375	-->
376
377	<enum name="SettingsVersion"
378	uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f"
379	>
380	<desc>Settings version of VirtualBox settings files. This is written to
381	the "version" attribute of the root "VirtualBox" element in the settings
382	file XML and indicates which VirtualBox version wrote the file.
383	</desc>
384
385	<const name="Null" value="0">
386	<desc>Null value, indicates invalid version.</desc>
387	</const>
388	<const name="v1_0" value="1">
389	<desc>Legacy settings version, not currently supported.</desc>
390	</const>
391	<const name="v1_1" value="2">
392	<desc>Legacy settings version, not currently supported.</desc>
393	</const>
394	<const name="v1_2" value="3">
395	<desc>Legacy settings version, not currently supported.</desc>
396	</const>
397	<const name="v1_3pre" value="4">
398	<desc>Legacy settings version, not currently supported.</desc>
399	</const>
400	<const name="v1_3" value="5">
401	<desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>
402	<!--
403	Machine XML: Capitalization of Uart, Lpt elements and many attributes changed.
404	-->
405	</const>
406	<const name="v1_4" value="6">
407	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
408	<!--
409	VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged
410	(was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk)
411	-->
412	</const>
413	<const name="v1_5" value="7">
414	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
415	<!-- 2008-09-04: 2.0.0 released
416	2008-11-20: settings version 1.5 introduced
417	2008-12-17: 2.1.0 released
418	Machine changes:
419	guest OS identifiers changed;
420	Machine/Hardware/Display/MonitorCount renamed to monitorCount;
421	Machine/Hardware/Display/Accelerate3D renamed to accelerate3D;
422	Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count
423	-->
424	</const>
425	<const name="v1_6" value="8">
426	<desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>
427	<!-- 2008-12-17: 2.1.0 released
428	2008-12-19: settings version 1.6 introduced (is in 2.1 branch)
429	2009-04-08: 2.2.0 released
430	Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done)
431	-->
432	</const>
433	<const name="v1_7" value="9">
434	<desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>
435	<!-- 2008-12-17: 2.1.0 released
436	2009-03-11: settings version 1.7 introduced (is in 2.2 branch)
437	2009-04-08: 2.2.0 released
438	VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done)
439	Machine changes: HardDiskAttachments is now StorageControllers (done)
440	-->
441	</const>
442	<const name="v1_8" value="10">
443	<desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>
444	<!-- Machine additions: Display/@accelerate2DVideo (done)
445	-->
446	</const>
447	<const name="v1_9" value="11">
448	<desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>
449	<!-- The big storage controller / DVD / Floppy rework (done)
450	-->
451	</const>
452	<const name="v1_10" value="12">
453	<desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc>
454	<!-- Machine changes: RTC localOrUTC (done)
455	CPU hot-plug support
456	-->
457	</const>
458	<const name="Future" value="13">
459	<desc>Settings version greater than "1.10", written by a future VirtualBox version.</desc>
460	</const>
461	</enum>
462
463	<enum
464	name="AccessMode"
465	uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
466	>
467	<desc>
468	Access mode for opening files.
469	</desc>
470
471	<const name="ReadOnly" value="1"/>
472	<const name="ReadWrite" value="2"/>
473	</enum>
474
475	<enum
476	name="MachineState"
477	uuid="e998d075-543a-41fc-8aa9-5ca3e92393fd"
478	>
479	<desc>
480	Virtual machine execution state.
481
482	This enumeration represents possible values of the <link
483	to="IMachine::state"/> attribute.
484
485	Below is the basic virtual machine state diagram. It shows how the state
486	changes during virtual machine execution. The text in square braces shows
487	a method of the IConsole interface that performs the given state
488	transition.
489
490	<pre>
491	+---------[powerDown()] <- Stuck <--[failure]-+
492	V \|
493	+-> PoweredOff --+-->[powerUp()]--> Starting --+ \| +-----[resume()]-----+
494	\| \| \| \| V \|
495	\| Aborted -----+ +--> Running --[pause()]--> Paused
496	\| \| ^ \| ^ \|
497	\| Saved -----------[powerUp()]--> Restoring -+ \| \| \| \|
498	\| ^ \| \| \| \|
499	\| \| +-----------------------------------------+-\|-------------------+ +
500	\| \| \| \| \|
501	\| \| +-- Saving <--------[takeSnapshot()]<-------+---------------------+
502	\| \| \| \|
503	\| +-------- Saving <--------[saveState()]<----------+---------------------+
504	\| \| \|
505	+-------------- Stopping -------[powerDown()]<----------+---------------------+
506	</pre>
507
508	Note that states to the right from PoweredOff, Aborted and Saved in the
509	above diagram are called <i>online VM states</i>. These states
510	represent the virtual machine which is being executed in a dedicated
511	process (usually with a GUI window attached to it where you can see the
512	activity of the virtual machine and interact with it). There are two
513	special pseudo-states, FirstOnline and LastOnline, that can be used in
514	relational expressions to detect if the given machine state is online or
515	not:
516
517	<pre>
518	if (machine.GetState() >= MachineState_FirstOnline &&
519	machine.GetState() <= MachineState_LastOnline)
520	{
521	...the machine is being executed...
522	}
523	</pre>
524
525	When the virtual machine is in one of the online VM states (that is, being
526	executed), only a few machine settings can be modified. Methods working
527	with such settings contain an explicit note about that. An attempt to
528	change any oter setting or perform a modifying operation during this time
529	will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
530
531	All online states except Running, Paused and Stuck are transitional: they
532	represent temporary conditions of the virtual machine that will last as
533	long as the operation that initiated such a condition.
534
535	The Stuck state is a special case. It means that execution of the machine
536	has reached the "Guru Meditation" condition. This condition indicates an
537	internal VMM (virtual machine manager) failure which may happen as a
538	result of either an unhandled low-level virtual hardware exception or one
539	of the recompiler exceptions (such as the <i>too-many-traps</i>
540	condition).
541
542	Note also that any online VM state may transit to the Aborted state. This
543	happens if the process that is executing the virtual machine terminates
544	unexpectedly (for example, crashes). Other than that, the Aborted state is
545	equivalent to PoweredOff.
546
547	There are also a few additional state diagrams that do not deal with
548	virtual machine execution and therefore are shown separately. The states
549	shown on these diagrams are called <i>offline VM states</i> (this includes
550	PoweredOff, Aborted and Saved too).
551
552	The first diagram shows what happens when a lengthy setup operation is
553	being executed (such as <link to="IMachine::attachDevice"/>).
554
555	<pre>
556	+----------------------------------(same state as before the call)------+
557	\| \|
558	+-> PoweredOff --+ \|
559	\| \| \|
560	\|-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
561	\| \|
562	+-> Saved -------+
563	</pre>
564
565	The next two diagrams demonstrate the process of taking a snapshot of a
566	powered off virtual machine, restoring the state to that as of a snapshot
567	or deleting a snapshot, respectively.
568
569	<pre>
570	+----------------------------------(same state as before the call)------+
571	\| \|
572	+-> PoweredOff --+ \|
573	\| +-->[takeSnapshot()] -------------------> Saving ------+
574	+-> Aborted -----+
575
576	+-> PoweredOff --+
577	\| \|
578	\| Aborted -----+-->[restoreSnapshot() ]-------> RestoringSnapshot -+
579	\| \| [deleteSnapshot() ]-------> DeletingSnapshot --+
580	+-> Saved -------+ \|
581	\| \|
582	+---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
583	</pre>
584
585	Note that the Saving state is present in both the offline state group and
586	online state group. Currently, the only way to determine what group is
587	assumed in a particular case is to remember the previous machine state: if
588	it was Running or Paused, then Saving is an online state, otherwise it is
589	an offline state. This inconsistency may be removed in one of the future
590	versions of VirtualBox by adding a new state.
591
592	<note internal="yes">
593	For whoever decides to touch this enum: In order to keep the
594	comparisons involving FirstOnline and LastOnline pseudo-states valid,
595	the numeric values of these states must be correspondingly updated if
596	needed: for any online VM state, the condition
597	<tt>FirstOnline <= state <= LastOnline</tt> must be
598	@c true. The same relates to transient states for which
599	the condition <tt>FirstOnline <= state <= LastOnline</tt> must be
600	@c true.
601	</note>
602	</desc>
603
604	<const name="Null" value="0">
605	<desc>Null value (never used by the API).</desc>
606	</const>
607	<const name="PoweredOff" value="1">
608	<desc>
609	The machine is not running and has no saved execution state; it has
610	either never been started or been shut down successfully.
611	</desc>
612	</const>
613	<const name="Saved" value="2">
614	<desc>
615	The machine is not currently running, but the execution state of the machine
616	has been saved to an external file when it was running, from where
617	it can be resumed.
618	</desc>
619	</const>
620	<const name="Teleported" value="3">
621	<desc>
622	The machine was teleported to a different host (or process) and then
623	powered off. Take care when powering it on again may corrupt resources
624	it shares with the teleportation target (e.g. disk and network).
625	</desc>
626	</const>
627	<const name="Aborted" value="4">
628	<desc>
629	The process running the machine has terminated abnormally. This may
630	indicate a crash of the VM process in host execution context, or
631	the VM process has been terminated externally.
632	</desc>
633	</const>
634	<const name="Running" value="5">
635	<desc>
636	The machine is currently being executed.
637	<note internal="yes">
638	For whoever decides to touch this enum: In order to keep the
639	comparisons in the old source code valid, this state must immediately
640	precede the Paused state.
641	TODO: Lift this spectacularly wonderful restriction.
642	</note>
643	</desc>
644	</const>
645	<const name="Paused" value="6">
646	<desc>
647	Execution of the machine has been paused.
648	<note internal="yes">
649	For whoever decides to touch this enum: In order to keep the
650	comparisons in the old source code valid, this state must immediately
651	follow the Running state.
652	TODO: Lift this spectacularly wonderful restriction.
653	</note>
654	</desc>
655	</const>
656	<const name="Stuck" value="7">
657	<desc>
658	Execution of the machine has reached the "Guru Meditation"
659	condition. This indicates a severe error in the hypervisor itself.
660	<note internal="yes">
661	bird: Why this uncool name? Could we rename it to "GuruMeditation" or
662	"Guru", perhaps? Or are there some other VMM states that are
663	intended to be lumped in here as well?
664	</note>
665	</desc>
666	</const>
667	<const name="Teleporting" value="8">
668	<desc>
669	The machine is about to be teleported to a different host or process.
670	It is possible to pause a machine in this state, but it will go to the
671	<link to="MachineState::PausedTeleporting"/> state and it will not be
672	possible to resume it again unless the teleportation fails.
673	</desc>
674	</const>
675	<const name="LiveSnapshotting" value="9">
676	<desc>
677	A live snapshot is being taken. The machine is running normally, but
678	some of the runtime configuration options are inaccessible. Also, if
679	paused while in this state it will transition to
680	<link to="MachineState::Saving"/> and it will not be resume the
681	execution until the snapshot operation has completed.
682	</desc>
683	</const>
684	<const name="Starting" value="10">
685	<desc>
686	Machine is being started after powering it on from a
687	zero execution state.
688	</desc>
689	</const>
690	<const name="Stopping" value="11">
691	<desc>
692	Machine is being normally stopped powering it off, or after the guest OS
693	has initiated a shutdown sequence.
694	</desc>
695	</const>
696	<const name="Saving" value="12">
697	<desc>
698	Machine is saving its execution state to a file, or an online
699	snapshot of the machine is being taken.
700	</desc>
701	</const>
702	<const name="Restoring" value="13">
703	<desc>
704	Execution state of the machine is being restored from a file
705	after powering it on from the saved execution state.
706	</desc>
707	</const>
708	<const name="TeleportingPausedVM" value="14">
709	<desc>
710	The machine is being teleported to another host or process, but it is
711	not running. This is the paused variant of the
712	<link to="MachineState::Teleporting"/> state.
713	</desc>
714	</const>
715	<const name="TeleportingIn" value="15">
716	<desc>
717	Teleporting the machine state in from another host or process.
718	</desc>
719	</const>
720	<const name="DeletingSnapshotOnline" value="16">
721	<desc>
722	Teleporting the machine state in from another host or process.
723	</desc>
724	</const>
725	<const name="DeletingSnapshotPaused" value="17">
726	<desc>
727	Teleporting the machine state in from another host or process.
728	</desc>
729	</const>
730	<const name="RestoringSnapshot" value="18">
731	<desc>
732	A machine snapshot is being restored; this typically does not take long.
733	</desc>
734	</const>
735	<const name="DeletingSnapshot" value="19">
736	<desc>
737	A machine snapshot is being deleted; this can take a long time since this
738	may require merging differencing media.
739	</desc>
740	</const>
741	<const name="SettingUp" value="20">
742	<desc>
743	Lengthy setup operation is in progress.
744	</desc>
745	</const>
746
747	<const name="FirstOnline" value="5" wsmap="suppress"> <!-- Running -->
748	<desc>
749	Pseudo-state: first online state (for use in relational expressions).
750	</desc>
751	</const>
752	<const name="LastOnline" value="17" wsmap="suppress"> <!-- DeletingSnapshotPaused -->
753	<desc>
754	Pseudo-state: last online state (for use in relational expressions).
755	</desc>
756	</const>
757
758	<const name="FirstTransient" value="8" wsmap="suppress"> <!-- Teleporting -->
759	<desc>
760	Pseudo-state: first transient state (for use in relational expressions).
761	</desc>
762	</const>
763	<const name="LastTransient" value="20" wsmap="suppress"> <!-- SettingUp -->
764	<desc>
765	Pseudo-state: last transient state (for use in relational expressions).
766	</desc>
767	</const>
768
769	</enum>
770
771	<enum
772	name="SessionState"
773	uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8"
774	>
775	<desc>
776	Session state. This enumeration represents possible values of
777	<link to="IMachine::sessionState"/> and <link to="ISession::state"/>
778	attributes. See individual enumerator descriptions for the meaning for
779	every value.
780	</desc>
781
782	<const name="Null" value="0">
783	<desc>Null value (never used by the API).</desc>
784	</const>
785	<const name="Closed" value="1">
786	<desc>
787	The machine has no open sessions (<link to="IMachine::sessionState"/>);
788	the session is closed (<link to="ISession::state"/>)
789	</desc>
790	</const>
791	<const name="Open" value="2">
792	<desc>
793	The machine has an open direct session (<link to="IMachine::sessionState"/>);
794	the session is open (<link to="ISession::state"/>)
795	</desc>
796	</const>
797	<const name="Spawning" value="3">
798	<desc>
799	A new (direct) session is being opened for the machine as a result of
800	<link to="IVirtualBox::openRemoteSession"/> call
801	(<link to="IMachine::sessionState"/> or <link to="ISession::state"/>).
802	This state also occurs as a short transient state when a new direct
803	session is opened by calling <link to="IVirtualBox::openSession"/>.
804	</desc>
805	</const>
806	<const name="Closing" value="4">
807	<desc>
808	The direct session is being closed (<link to="IMachine::sessionState"/>);
809	the session is being closed (<link to="ISession::state"/>)
810	</desc>
811	</const>
812	</enum>
813
814	<enum
815	name="CPUPropertyType"
816	uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5"
817	>
818	<desc>
819	Virtual CPU property type. This enumeration represents possible values of the
820	IMachine get- and setCPUProperty methods.
821	</desc>
822	<const name="Null" value="0">
823	<desc>Null value (never used by the API).</desc>
824	</const>
825	<const name="PAE" value="1">
826	<desc>
827	This setting determines whether VirtualBox will expose the Physical Address
828	Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
829	is not available, it will not be reported.
830	</desc>
831	</const>
832	<const name="Synthetic" value="2">
833	<desc>
834	This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow
835	teleporting between host systems that differ significantly.
836	</desc>
837	</const>
838	</enum>
839
840
841	<enum
842	name="HWVirtExPropertyType"
843	uuid="ce81dfdd-d2b8-4a90-bbea-40ee8b7ffcee"
844	>
845	<desc>
846	Hardware virtualization property type. This enumeration represents possible values
847	for the <link to="IMachine::getHWVirtExProperty"/> and
848	<link to="IMachine::setHWVirtExProperty"/> methods.
849	</desc>
850	<const name="Null" value="0">
851	<desc>Null value (never used by the API).</desc>
852	</const>
853	<const name="Enabled" value="1">
854	<desc>
855	Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If
856	such extensions are not available, they will not be used.
857	</desc>
858	</const>
859	<const name="Exclusive" value="2">
860	<desc>
861	Whether hardware virtualization is used exclusively by VirtualBox. When enabled,
862	VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V
863	feature of the host. To share these with other hypervisors, you must disable this property.
864	</desc>
865	</const>
866	<const name="VPID" value="3">
867	<desc>
868	Whether VT-x VPID is enabled. If this extension is not available, it will not be used.
869	</desc>
870	</const>
871	<const name="NestedPaging" value="4">
872	<desc>
873	Whether Nested Paging is enabled. If this extension is not available, it will not be used.
874	</desc>
875	</const>
876	<const name="LargePages" value="5">
877	<desc>
878	Whether large page allocation is enabled; requires nested paging and a 64 bits host.
879	</desc>
880	</const>
881	</enum>
882
883	<enum
884	name="SessionType"
885	uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
886	>
887	<desc>
888	Session type. This enumeration represents possible values of the
889	<link to="ISession::type"/> attribute.
890	</desc>
891
892	<const name="Null" value="0">
893	<desc>Null value (never used by the API).</desc>
894	</const>
895	<const name="Direct" value="1">
896	<desc>
897	Direct session
898	(opened by <link to="IVirtualBox::openSession"/>)
899	</desc>
900	</const>
901	<const name="Remote" value="2">
902	<desc>
903	Remote session
904	(opened by <link to="IVirtualBox::openRemoteSession"/>)
905	</desc>
906	</const>
907	<const name="Existing" value="3">
908	<desc>
909	Existing session
910	(opened by <link to="IVirtualBox::openExistingSession"/>)
911	</desc>
912	</const>
913	</enum>
914
915	<enum
916	name="DeviceType"
917	uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
918	>
919	<desc>
920	Device type.
921	</desc>
922	<const name="Null" value="0">
923	<desc>
924	Null value, may also mean "no device" (not allowed for
925	<link to="IConsole::getDeviceActivity"/>).
926	</desc>
927	</const>
928	<const name="Floppy" value="1">
929	<desc>Floppy device.</desc>
930	</const>
931	<const name="DVD" value="2">
932	<desc>CD/DVD-ROM device.</desc>
933	</const>
934	<const name="HardDisk" value="3">
935	<desc>Hard disk device.</desc>
936	</const>
937	<const name="Network" value="4">
938	<desc>Network device.</desc>
939	</const>
940	<const name="USB" value="5">
941	<desc>USB device.</desc>
942	</const>
943	<const name="SharedFolder" value="6">
944	<desc>Shared folder device.</desc>
945	</const>
946	</enum>
947
948	<enum
949	name="DeviceActivity"
950	uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
951	>
952	<desc>
953	Device activity for <link to="IConsole::getDeviceActivity"/>.
954	</desc>
955
956	<const name="Null" value="0"/>
957	<const name="Idle" value="1"/>
958	<const name="Reading" value="2"/>
959	<const name="Writing" value="3"/>
960	</enum>
961
962	<enum
963	name="ClipboardMode"
964	uuid="33364716-4008-4701-8f14-be0fa3d62950"
965	>
966	<desc>
967	Host-Guest clipboard interchange mode.
968	</desc>
969
970	<const name="Disabled" value="0"/>
971	<const name="HostToGuest" value="1"/>
972	<const name="GuestToHost" value="2"/>
973	<const name="Bidirectional" value="3"/>
974	</enum>
975
976	<enum
977	name="Scope"
978	uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
979	>
980	<desc>
981	Scope of the operation.
982
983	A generic enumeration used in various methods to define the action or
984	argument scope.
985	</desc>
986
987	<const name="Global" value="0"/>
988	<const name="Machine" value="1"/>
989	<const name="Session" value="2"/>
990	</enum>
991
992	<enum
993	name="BIOSBootMenuMode"
994	uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
995	>
996	<desc>
997	BIOS boot menu mode.
998	</desc>
999
1000	<const name="Disabled" value="0"/>
1001	<const name="MenuOnly" value="1"/>
1002	<const name="MessageAndMenu" value="2"/>
1003	</enum>
1004
1005	<enum
1006	name="ProcessorFeature"
1007	uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
1008	>
1009	<desc>
1010	CPU features.
1011	</desc>
1012
1013	<const name="HWVirtEx" value="0"/>
1014	<const name="PAE" value="1"/>
1015	<const name="LongMode" value="2"/>
1016	<const name="NestedPaging" value="3"/>
1017	</enum>
1018
1019	<enum
1020	name="FirmwareType"
1021	uuid="b903f264-c230-483e-ac74-2b37ce60d371"
1022	>
1023	<desc>
1024	Firmware type.
1025	</desc>
1026	<const name="BIOS" value="1">
1027	<desc>BIOS Firmware.</desc>
1028	</const>
1029	<const name="EFI" value="2">
1030	<desc>EFI Firmware, bitness detetced basing on OS type.</desc>
1031	</const>
1032	<const name="EFI32" value="3">
1033	<desc>Efi firmware, 32-bit.</desc>
1034	</const>
1035	<const name="EFI64" value="4">
1036	<desc>Efi firmware, 64-bit.</desc>
1037	</const>
1038	<const name="EFIDUAL" value="5">
1039	<desc>Efi firmware, combined 32 and 64-bit.</desc>
1040	</const>
1041	</enum>
1042
1043	<enum
1044	name="PointingHidType"
1045	uuid="0d3c17a2-821a-4b2e-ae41-890c6c60aa97"
1046	>
1047	<desc>
1048	Type of pointing device used in a virtual machine.
1049	</desc>
1050	<const name="None" value="1">
1051	<desc>No mouse.</desc>
1052	</const>
1053	<const name="PS2Mouse" value="2">
1054	<desc>PS/2 auxillary device, a.k.a. mouse.</desc>
1055	</const>
1056	<const name="USBMouse" value="3">
1057	<desc>USB mouse (relative pointer).</desc>
1058	</const>
1059	<const name="USBTablet" value="4">
1060	<desc>USB tablet (absolute pointer).</desc>
1061	</const>
1062	<const name="ComboMouse" value="5">
1063	<desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.
1064	Using of such device can have negative performance implications. </desc>
1065	</const>
1066	</enum>
1067
1068	<enum
1069	name="KeyboardHidType"
1070	uuid="5a5b0996-3a3e-44bb-9019-56979812cbcc"
1071	>
1072	<desc>
1073	Type of keyboard device used in a virtual machine.
1074	</desc>
1075	<const name="None" value="1">
1076	<desc>No keyboard.</desc>
1077	</const>
1078	<const name="PS2Keyboard" value="2">
1079	<desc>PS/2 keyboard.</desc>
1080	</const>
1081	<const name="USBKeyboard" value="3">
1082	<desc>USB keyboard.</desc>
1083	</const>
1084	<const name="ComboKeyboard" value="4">
1085	<desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.
1086	Using of such device can have negative performance implications. </desc>
1087	</const>
1088	</enum>
1089
1090	<enum
1091	name="IoMgrType"
1092	uuid="35567419-4d2a-4256-a74e-efcae33493a2"
1093	>
1094	<desc>
1095	Type of the I/O manager used for the image files in a virtual machine.
1096	</desc>
1097	<const name="Simple" value="1">
1098	<desc>Simple manager. Normally only used if the default one runs into an
1099	error. </desc>
1100	</const>
1101	<const name="Async" value="2">
1102	<desc>Asynchronous manager using the async I/O API on the host if present.
1103	This is the default manager.</desc>
1104	</const>
1105	</enum>
1106
1107	<enum
1108	name="IoBackendType"
1109	uuid="2a7e16d1-4e6b-4d5d-b0c9-b9bbe6c5b2ad"
1110	>
1111	<desc>
1112	Type of I/O backend used for the image files in a virtual machine.
1113	</desc>
1114	<const name="Buffered" value="1">
1115	<desc>Image files will use the host cache if possible.
1116	This type does not work with the Async I/O manager on Linux hosts.
1117	Default on all hosts except Linux.</desc>
1118	</const>
1119	<const name="Unbuffered" value="2">
1120	<desc>Image files will not use the host cache.
1121	This should be used on OS X and Linux hosts if a high I/O load is expected
1122	or many virtual machines are running to prevent I/O cache
1123	related hangs. Default on Linux hosts.</desc>
1124	</const>
1125	</enum>
1126
1127	<!--
1128	// IVirtualBoxErrorInfo
1129	/////////////////////////////////////////////////////////////////////////
1130	-->
1131
1132	<interface
1133	name="IVirtualBoxErrorInfo" extends="$errorinfo"
1134	uuid="4b86d186-407e-4f9e-8be8-e50061be8725"
1135	supportsErrorInfo="no"
1136	wsmap="managed"
1137	>
1138	<desc>
1139	The IVirtualBoxErrorInfo interface represents extended error information.
1140
1141	Extended error information can be set by VirtualBox components after
1142	unsuccessful or partially successful method invocation. This information
1143	can be retrieved by the calling party as an IVirtualBoxErrorInfo object
1144	and then shown to the client in addition to the plain 32-bit result code.
1145
1146	In MS COM, this interface extends the IErrorInfo interface,
1147	in XPCOM, it extends the nsIException interface. In both cases,
1148	it provides a set of common attributes to retrieve error
1149	information.
1150
1151	Sometimes invocation of some component's method may involve methods of
1152	other components that may also fail (independently of this method's
1153	failure), or a series of non-fatal errors may precede a fatal error that
1154	causes method failure. In cases like that, it may be desirable to preserve
1155	information about all errors happened during method invocation and deliver
1156	it to the caller. The <link to="#next"/> attribute is intended
1157	specifically for this purpose and allows to represent a chain of errors
1158	through a single IVirtualBoxErrorInfo object set after method invocation.
1159
1160	Note that errors are stored to a chain in the reverse order, i.e. the
1161	initial error object you query right after method invocation is the last
1162	error set by the callee, the object it points to in the @a next attribute
1163	is the previous error and so on, up to the first error (which is the last
1164	in the chain).
1165	</desc>
1166
1167	<attribute name="resultCode" type="long" readonly="yes">
1168	<desc>
1169	Result code of the error.
1170	Usually, it will be the same as the result code returned
1171	by the method that provided this error information, but not
1172	always. For example, on Win32, CoCreateInstance() will most
1173	likely return E_NOINTERFACE upon unsuccessful component
1174	instantiation attempt, but not the value the component factory
1175	returned. Value is typed 'long', not 'result',
1176	to make interface usable from scripting languages.
1177	<note>
1178	In MS COM, there is no equivalent.
1179	In XPCOM, it is the same as nsIException::result.
1180	</note>
1181	</desc>
1182	</attribute>
1183
1184	<attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
1185	<desc>
1186	UUID of the interface that defined the error.
1187	<note>
1188	In MS COM, it is the same as IErrorInfo::GetGUID, except for the
1189	data type.
1190	In XPCOM, there is no equivalent.
1191	</note>
1192	</desc>
1193	</attribute>
1194
1195	<attribute name="component" type="wstring" readonly="yes">
1196	<desc>
1197	Name of the component that generated the error.
1198	<note>
1199	In MS COM, it is the same as IErrorInfo::GetSource.
1200	In XPCOM, there is no equivalent.
1201	</note>
1202	</desc>
1203	</attribute>
1204
1205	<attribute name="text" type="wstring" readonly="yes">
1206	<desc>
1207	Text description of the error.
1208	<note>
1209	In MS COM, it is the same as IErrorInfo::GetDescription.
1210	In XPCOM, it is the same as nsIException::message.
1211	</note>
1212	</desc>
1213	</attribute>
1214
1215	<attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
1216	<desc>
1217	Next error object if there is any, or @c null otherwise.
1218	<note>
1219	In MS COM, there is no equivalent.
1220	In XPCOM, it is the same as nsIException::inner.
1221	</note>
1222	</desc>
1223	</attribute>
1224
1225	</interface>
1226
1227	<interface
1228	name="ILocalOwner" extends="$unknown"
1229	uuid="308FF42A-DC45-49D4-A950-B1EEE5E00BB5" wsmap="suppress"
1230	>
1231	<desc>
1232	The ILocalOwner interface allows to register local objects
1233	(created without COM calls, but with new()).
1234	Once registered, calls to methods of such objects can be made
1235	from remote COM processes.
1236	The main usecase is the event callback implementation where
1237	API clients provide callback objects.
1238	</desc>
1239	<method name="setLocalObject">
1240	<desc>
1241	Set local object.
1242	</desc>
1243	<param name="object" type="$unknown" dir="in">
1244	<desc>Local object to forward requests to.
1245	If null, clears currently set local object.</desc>
1246	</param>
1247	</method>
1248	</interface>
1249
1250	<!--
1251	// IVirtualBox
1252	/////////////////////////////////////////////////////////////////////////
1253	-->
1254
1255	<interface
1256	name="IVirtualBoxCallback" extends="$unknown"
1257	uuid="7f6a65b6-ad5d-4a67-8872-0b11cb7ea95c"
1258	wsmap="suppress"
1259	>
1260
1261	<method name="onMachineStateChange">
1262	<desc>
1263	The execution state of the given machine has changed.
1264	<see>IMachine::state</see>
1265	</desc>
1266	<param name="machineId" type="uuid" mod="string" dir="in">
1267	<desc>ID of the machine this event relates to.</desc>
1268	</param>
1269	<param name="state" type="MachineState" dir="in">
1270	<desc>New execution state.</desc>
1271	</param>
1272	</method>
1273
1274	<method name="onMachineDataChange">
1275	<desc>
1276	Any of the settings of the given machine has changed.
1277	</desc>
1278	<param name="machineId" type="uuid" mod="string" dir="in">
1279	<desc>ID of the machine this event relates to.</desc>
1280	</param>
1281	</method>
1282
1283	<method name="onExtraDataCanChange">
1284	<desc>
1285	Notification when someone tries to change extra data for
1286	either the given machine or (if @c null) global extra data.
1287	This gives the chance to veto against changes.
1288	</desc>
1289	<param name="machineId" type="uuid" mod="string" dir="in">
1290	<desc>
1291	ID of the machine this event relates to
1292	(@c null ID for global extra data change requests).
1293	</desc>
1294	</param>
1295	<param name="key" type="wstring" dir="in">
1296	<desc>
1297	Extra data key for the attempted write.
1298	</desc>
1299	</param>
1300	<param name="value" type="wstring" dir="in">
1301	<desc>
1302	Extra data value for the given key.
1303	</desc>
1304	</param>
1305	<param name="error" type="wstring" dir="out">
1306	<desc>
1307	Optional error message describing the reason of the
1308	veto (ignored if this notification returns @c true).
1309	</desc>
1310	</param>
1311	<param name="allowChange" type="boolean" dir="return">
1312	<desc>
1313	Flag to indicate whether the callee agrees (@c true)
1314	or vetoes against the change (@c false).
1315	</desc>
1316	</param>
1317	</method>
1318
1319	<method name="onExtraDataChange">
1320	<desc>
1321	Notification when machine specific or global extra data
1322	has changed.
1323	</desc>
1324	<param name="machineId" type="uuid" mod="string" dir="in">
1325	<desc>
1326	ID of the machine this event relates to.
1327	Null for global extra data changes.
1328	</desc>
1329	</param>
1330	<param name="key" type="wstring" dir="in">
1331	<desc>
1332	Extra data key that has changed.
1333	</desc>
1334	</param>
1335	<param name="value" type="wstring" dir="in">
1336	<desc>
1337	Extra data value for the given key.
1338	</desc>
1339	</param>
1340	</method>
1341
1342	<method name="onMediumRegistered">
1343	<desc>
1344	The given medium was registered or unregistered
1345	within this VirtualBox installation.
1346
1347	The @a mediumType parameter describes what type of
1348	medium the specified @a mediumId refers to. Possible
1349	values are:
1350
1351	<ul>
1352	<li><link to="DeviceType_HardDisk"/>: the medium is a hard disk
1353	that, if registered, can be obtained using the
1354	<link to="IVirtualBox::getHardDisk"/> call.</li>
1355	<li><link to="DeviceType_DVD"/>: the medium is a CD/DVD image
1356	that, if registered, can be obtained using the
1357	<link to="IVirtualBox::getDVDImage"/> call.</li>
1358	<li><link to="DeviceType_Floppy"/>: the medium is a Floppy image
1359	that, if registered, can be obtained using the
1360	<link to="IVirtualBox::getFloppyImage"/> call.</li>
1361	</ul>
1362
1363	Note that if this is a deregistration notification,
1364	there is no way to access the object representing the
1365	unregistered medium. It is supposed that the
1366	application will do required cleanup based on the
1367	@a mediumId value.
1368	</desc>
1369	<param name="mediumId" type="uuid" mod="string" dir="in">
1370	<desc>ID of the medium this event relates to.</desc>
1371	</param>
1372	<param name="mediumType" type="DeviceType" dir="in">
1373	<desc>Type of the medium this event relates to.</desc>
1374	</param>
1375	<param name="registered" type="boolean" dir="in">
1376	<desc>
1377	If @c true, the medium was registered, otherwise it was
1378	unregistered.
1379	</desc>
1380	</param>
1381	</method>
1382
1383	<method name="onMachineRegistered">
1384	<desc>
1385	The given machine was registered or unregistered
1386	within this VirtualBox installation.
1387	</desc>
1388	<param name="machineId" type="uuid" mod="string" dir="in">
1389	<desc>ID of the machine this event relates to.</desc>
1390	</param>
1391	<param name="registered" type="boolean" dir="in">
1392	<desc>
1393	If @c true, the machine was registered, otherwise it was
1394	unregistered.
1395	</desc>
1396	</param>
1397	</method>
1398
1399	<method name="onSessionStateChange">
1400	<desc>
1401	The state of the session for the given machine was changed.
1402	<see>IMachine::sessionState</see>
1403	</desc>
1404	<param name="machineId" type="uuid" mod="string" dir="in">
1405	<desc>ID of the machine this event relates to.</desc>
1406	</param>
1407	<param name="state" type="SessionState" dir="in">
1408	<desc>New session state.</desc>
1409	</param>
1410	</method>
1411
1412	<method name="onSnapshotTaken">
1413	<desc>
1414	A new snapshot of the machine has been taken.
1415	<see>ISnapshot</see>
1416	</desc>
1417	<param name="machineId" type="uuid" mod="string" dir="in">
1418	<desc>ID of the machine this event relates to.</desc>
1419	</param>
1420	<param name="snapshotId" type="uuid" mod="string" dir="in">
1421	<desc>ID of the new snapshot.</desc>
1422	</param>
1423	</method>
1424
1425	<method name="onSnapshotDeleted">
1426	<desc>
1427	Snapshot of the given machine has been deleted.
1428
1429	<note>
1430	This notification is delivered <b>after</b> the snapshot
1431	object has been uninitialized on the server (so that any
1432	attempt to call its methods will return an error).
1433	</note>
1434
1435	<see>ISnapshot</see>
1436	</desc>
1437	<param name="machineId" type="uuid" mod="string" dir="in">
1438	<desc>ID of the machine this event relates to.</desc>
1439	</param>
1440	<param name="snapshotId" type="uuid" mod="string" dir="in">
1441	<desc>
1442	ID of the deleted snapshot. @c null means the current machine
1443	state has been deleted (restored from the current snapshot).
1444	</desc>
1445	</param>
1446	</method>
1447
1448	<method name="onSnapshotChange">
1449	<desc>
1450	Snapshot properties (name and/or description) have been changed.
1451	<see>ISnapshot</see>
1452	</desc>
1453	<param name="machineId" type="uuid" mod="string" dir="in">
1454	<desc>ID of the machine this event relates to.</desc>
1455	</param>
1456	<param name="snapshotId" type="uuid" mod="string" dir="in">
1457	<desc>ID of the changed snapshot.</desc>
1458	</param>
1459	</method>
1460
1461	<method name="onGuestPropertyChange">
1462	<desc>
1463	Notification when a guest property has changed.
1464	</desc>
1465	<param name="machineId" type="uuid" mod="string" dir="in">
1466	<desc>
1467	ID of the machine this event relates to.
1468	</desc>
1469	</param>
1470	<param name="name" type="wstring" dir="in">
1471	<desc>
1472	The name of the property that has changed.
1473	</desc>
1474	</param>
1475	<param name="value" type="wstring" dir="in">
1476	<desc>
1477	The new property value.
1478	</desc>
1479	</param>
1480	<param name="flags" type="wstring" dir="in">
1481	<desc>
1482	The new property flags.
1483	</desc>
1484	</param>
1485	</method>
1486
1487	</interface>
1488
1489	<interface
1490	name="IDHCPServer" extends="$unknown"
1491	uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
1492	wsmap="managed"
1493	>
1494	<desc>
1495	The IDHCPServer interface represents the vbox dhcp server configuration.
1496
1497	To enumerate all the dhcp servers on the host, use the
1498	<link to="IVirtualBox::DHCPServers"/> attribute.
1499	</desc>
1500
1501	<attribute name="enabled" type="boolean">
1502	<desc>
1503	specifies if the dhcp server is enabled
1504	</desc>
1505	</attribute>
1506
1507	<attribute name="IPAddress" type="wstring" readonly="yes">
1508	<desc>
1509	specifies server IP
1510	</desc>
1511	</attribute>
1512
1513	<attribute name="networkMask" type="wstring" readonly="yes">
1514	<desc>
1515	specifies server network mask
1516	</desc>
1517	</attribute>
1518
1519	<attribute name="networkName" type="wstring" readonly="yes">
1520	<desc>
1521	specifies internal network name the server is used for
1522	</desc>
1523	</attribute>
1524
1525	<attribute name="lowerIP" type="wstring" readonly="yes">
1526	<desc>
1527	specifies from IP adrres in server address range
1528	</desc>
1529	</attribute>
1530
1531	<attribute name="upperIP" type="wstring" readonly="yes">
1532	<desc>
1533	specifies to IP adrres in server address range
1534	</desc>
1535	</attribute>
1536
1537	<method name="setConfiguration">
1538	<desc>
1539	configures the server
1540	<result name="E_INVALIDARG">
1541	invalid configuration supplied
1542	</result>
1543	</desc>
1544	<param name="IPAddress" type="wstring" dir="in">
1545	<desc>
1546	server IP address
1547	</desc>
1548	</param>
1549	<param name="networkMask" type="wstring" dir="in">
1550	<desc>
1551	server network mask
1552	</desc>
1553	</param>
1554	<param name="FromIPAddress" type="wstring" dir="in">
1555	<desc>
1556	server From IP address for address range
1557	</desc>
1558	</param>
1559	<param name="ToIPAddress" type="wstring" dir="in">
1560	<desc>
1561	server To IP address for address range
1562	</desc>
1563	</param>
1564	</method>
1565
1566	<method name="start">
1567	<desc>
1568	Starts DHCP server process.
1569	<result name="E_FAIL">
1570	Failed to start the process.
1571	</result>
1572	</desc>
1573	<param name="networkName" type="wstring" dir="in">
1574	<desc>
1575	Name of internal network DHCP server should attach to.
1576	</desc>
1577	</param>
1578	<param name="trunkName" type="wstring" dir="in">
1579	<desc>
1580	Name of internal network trunk.
1581	</desc>
1582	</param>
1583	<param name="trunkType" type="wstring" dir="in">
1584	<desc>
1585	Type of internal network trunk.
1586	</desc>
1587	</param>
1588	</method>
1589
1590	<method name="stop">
1591	<desc>
1592	Stops DHCP server process.
1593	<result name="E_FAIL">
1594	Failed to stop the process.
1595	</result>
1596	</desc>
1597	</method>
1598	</interface>
1599
1600	<interface
1601	name="IVirtualBox" extends="$unknown"
1602	uuid="3f36e024-7fed-4f20-a02c-9158a82b44e6"
1603	wsmap="managed"
1604	>
1605	<desc>
1606	The IVirtualBox interface represents the main interface exposed by the
1607	product that provides virtual machine management.
1608
1609	An instance of IVirtualBox is required for the product to do anything
1610	useful. Even though the interface does not expose this, internally,
1611	IVirtualBox is implemented as a singleton and actually lives in the
1612	process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1613	IVirtualBox can track the state of all virtual machines on a particular
1614	host, regardless of which frontend started them.
1615
1616	To enumerate all the virtual machines on the host, use the
1617	<link to="IVirtualBox::machines"/> attribute.
1618	</desc>
1619
1620	<attribute name="version" type="wstring" readonly="yes">
1621	<desc>
1622	A string representing the version number of the product. The
1623	format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1624	last number represents the build number and will frequently change.
1625	</desc>
1626	</attribute>
1627
1628	<attribute name="revision" type="unsigned long" readonly="yes">
1629	<desc>
1630	The internal build revision number of the product.
1631	</desc>
1632	</attribute>
1633
1634	<attribute name="packageType" type="wstring" readonly="yes">
1635	<desc>
1636	A string representing the package type of this product. The
1637	format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1638	SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1639	is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1640	this.
1641	</desc>
1642	</attribute>
1643
1644	<attribute name="homeFolder" type="wstring" readonly="yes">
1645	<desc>
1646	Full path to the directory where the global settings file,
1647	<tt>VirtualBox.xml</tt>, is stored.
1648
1649	In this version of VirtualBox, the value of this property is
1650	always <tt><user_dir>/.VirtualBox</tt> (where
1651	<tt><user_dir></tt> is the path to the user directory,
1652	as determined by the host OS), and cannot be changed.
1653
1654	This path is also used as the base to resolve relative paths in
1655	places where relative paths are allowed (unless otherwise
1656	expressly indicated).
1657	</desc>
1658	</attribute>
1659
1660	<attribute name="settingsFilePath" type="wstring" readonly="yes">
1661	<desc>
1662	Full name of the global settings file.
1663	The value of this property corresponds to the value of
1664	<link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1665	</desc>
1666	</attribute>
1667
1668	<attribute name="host" type="IHost" readonly="yes">
1669	<desc>Associated host object.</desc>
1670	</attribute>
1671
1672	<attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1673	<desc>Associated system information object.</desc>
1674	</attribute>
1675
1676	<attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1677	<desc>
1678	Array of machine objects registered within this VirtualBox instance.
1679	</desc>
1680	</attribute>
1681
1682	<attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
1683	<desc>
1684	Array of medium objects known to this VirtualBox installation.
1685
1686	This array contains only base media. All differencing
1687	media of the given base medium can be enumerated using
1688	<link to="IMedium::children"/>.
1689	</desc>
1690	</attribute>
1691
1692	<attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
1693	<desc>
1694	Array of CD/DVD image objects registered with this VirtualBox instance.
1695	</desc>
1696	</attribute>
1697
1698	<attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
1699	<desc>
1700	Array of floppy image objects registered with this VirtualBox instance.
1701	</desc>
1702	</attribute>
1703
1704	<attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1705
1706	<attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1707
1708	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1709	<desc>
1710	Collection of global shared folders. Global shared folders are
1711	available to all virtual machines.
1712
1713	New shared folders are added to the collection using
1714	<link to="#createSharedFolder"/>. Existing shared folders can be
1715	removed using <link to="#removeSharedFolder"/>.
1716
1717	<note>
1718	In the current version of the product, global shared folders are not
1719	implemented and therefore this collection is always empty.
1720	</note>
1721	</desc>
1722	</attribute>
1723
1724	<attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1725	<desc>
1726	Associated performance collector object.
1727	</desc>
1728	</attribute>
1729
1730	<attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1731	<desc>
1732	dhcp server settings.
1733	</desc>
1734	</attribute>
1735
1736	<method name="createMachine">
1737	<desc>
1738	Creates a new virtual machine.
1739
1740	The new machine is created unregistered, with the initial configuration
1741	set according to the specified guest OS type. A typical sequence of
1742	actions to create a new virtual machine is as follows:
1743
1744	<ol>
1745	<li>
1746	Call this method to have a new machine created. The returned machine
1747	object will be "mutable" allowing to change any machine property.
1748	</li>
1749
1750	<li>
1751	Configure the machine using the appropriate attributes and methods.
1752	</li>
1753
1754	<li>
1755	Call <link to="IMachine::saveSettings" /> to write the settings
1756	to the machine's XML settings file. The configuration of the newly
1757	created machine will not be saved to disk until this method is
1758	called.
1759	</li>
1760
1761	<li>
1762	Call <link to="#registerMachine" /> to add the machine to the list
1763	of machines known to VirtualBox.
1764	</li>
1765	</ol>
1766
1767	You should specify valid name for the newly created machine when calling
1768	this method. See the <link to="IMachine::name"/> attribute description
1769	for more details about the machine name.
1770
1771	The specified guest OS type identifier must match an ID of one of known
1772	guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1773	array.
1774
1775	Every machine has a <i>settings file</i> that is used to store
1776	the machine configuration. This file is stored in a directory called the
1777	<i>machine settings subfolder</i>. Both the settings subfolder and file
1778	will have a name that corresponds to the name of the virtual machine.
1779	You can specify where to create the machine setting subfolder using the
1780	@a baseFolder argument. The base folder can be absolute (full path) or
1781	relative to the <link to="IVirtualBox::homeFolder">VirtualBox home
1782	directory</link>.
1783
1784	If @a baseFolder is a @c null or empty string (which is recommended), the
1785	<link to="ISystemProperties::defaultMachineFolder">default machine
1786	settings folder</link> will be used as a base folder for the created
1787	machine. Otherwise the given base folder will be used. In either case,
1788	the full path to the resulting settings file has the following
1789	structure:
1790	<pre>
1791	<base_folder>/<machine_name>/<machine_name>.xml
1792	</pre>
1793
1794	Note that if the resulting settings file already exists, this method
1795	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1796
1797	Optionally, you may specify an UUID of to assign to the created machine.
1798	However, this is not recommended and you should normally pass an empty
1799	(@c null) UUID to this method so that a new UUID will be automatically
1800	generated for every created machine. You can use UUID
1801	00000000-0000-0000-0000-000000000000 as @c null value.
1802
1803	<note>
1804	There is no way to change the name of the settings file or
1805	subfolder of the created machine directly.
1806	</note>
1807
1808	<result name="VBOX_E_OBJECT_NOT_FOUND">
1809	@a osTypeId is invalid.
1810	</result>
1811	<result name="VBOX_E_FILE_ERROR">
1812	Resulting settings file name is invalid or the settings file already
1813	exists or could not be created due to an I/O error.
1814	</result>
1815	<result name="E_INVALIDARG">
1816	@a name is empty or @c null.
1817	</result>
1818	</desc>
1819
1820	<param name="name" type="wstring" dir="in">
1821	<desc>Machine name.</desc>
1822	</param>
1823	<param name="osTypeId" type="wstring" dir="in">
1824	<desc>Guest OS Type ID.</desc>
1825	</param>
1826	<param name="baseFolder" type="wstring" dir="in">
1827	<desc>Base machine folder (optional).</desc>
1828	</param>
1829	<param name="id" type="uuid" mod="string" dir="in">
1830	<desc>Machine UUID (optional).</desc>
1831	</param>
1832	<param name="override" type="boolean" dir="in">
1833	<desc>Create the VM even if there are conflicting files.</desc>
1834	</param>
1835	<param name="machine" type="IMachine" dir="return">
1836	<desc>Created machine object.</desc>
1837	</param>
1838	</method>
1839
1840	<method name="createLegacyMachine">
1841	<desc>
1842	Creates a new virtual machine in "legacy" mode, using the specified
1843	settings file to store machine settings.
1844
1845	As opposed to machines created by <link to="#createMachine"/>,
1846	the settings file of the machine created in "legacy" mode is not
1847	automatically renamed when the machine name is changed -- it will always
1848	remain the same as specified in this method call.
1849
1850	The specified settings file name can be absolute (full path) or relative
1851	to the <link to="IVirtualBox::homeFolder">VirtualBox home
1852	directory</link>. If the file name doesn't contain an extension, the
1853	default extension (.xml) will be appended.
1854
1855	Note that the configuration of the newly created machine is not
1856	saved to disk (and therefore no settings file is created)
1857	until <link to="IMachine::saveSettings"/> is called. If the
1858	specified settings file already exists, this method
1859	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1860
1861	See <link to="#createMachine"/> for more information.
1862
1863	@deprecated This method may be removed later. Use <link
1864	to="IVirtualBox::createMachine"/> instead.
1865
1866	<note>
1867	There is no way to change the name of the settings file
1868	of the machine created in "legacy" mode.
1869	</note>
1870
1871	<result name="VBOX_E_OBJECT_NOT_FOUND">
1872	@a osTypeId is invalid.
1873	</result>
1874	<result name="VBOX_E_FILE_ERROR">
1875	@a settingsFile is invalid or the settings file already exists or
1876	could not be created due to an I/O error.
1877	</result>
1878	<result name="E_INVALIDARG">
1879	@a name or @a settingsFile is empty or @c null.
1880	</result>
1881	</desc>
1882
1883	<param name="name" type="wstring" dir="in">
1884	<desc>Machine name.</desc>
1885	</param>
1886	<param name="osTypeId" type="wstring" dir="in">
1887	<desc>Machine OS Type ID.</desc>
1888	</param>
1889	<param name="settingsFile" type="wstring" dir="in">
1890	<desc>Name of the machine settings file.</desc>
1891	</param>
1892	<param name="id" type="uuid" mod="string" dir="in">
1893	<desc>Machine UUID (optional).</desc>
1894	</param>
1895	<param name="machine" type="IMachine" dir="return">
1896	<desc>Created machine object.</desc>
1897	</param>
1898	</method>
1899
1900	<method name="openMachine">
1901	<desc>
1902	Opens a virtual machine from the existing settings file.
1903	The opened machine remains unregistered until you call
1904	<link to="#registerMachine"/>.
1905
1906	The specified settings file name can be absolute
1907	(full path) or relative to the <link to="IVirtualBox::homeFolder">
1908	VirtualBox home directory</link>. This file must exist
1909	and must be a valid machine settings file whose contents
1910	will be used to construct the machine object.
1911
1912	@deprecated Will be removed soon.
1913	<result name="VBOX_E_FILE_ERROR">
1914	Settings file name invalid, not found or sharing violation.
1915	</result>
1916	</desc>
1917	<param name="settingsFile" type="wstring" dir="in">
1918	<desc>
1919	Name of the machine settings file.
1920	</desc>
1921	</param>
1922	<param name="machine" type="IMachine" dir="return">
1923	<desc>Opened machine object.</desc>
1924	</param>
1925	<note>
1926	<link to="IMachine::settingsModified"/> will return
1927	@c false for the created machine, until any of machine settings
1928	are changed.
1929	</note>
1930	</method>
1931
1932	<method name="registerMachine">
1933	<desc>
1934
1935	Registers the machine previously created using
1936	<link to="#createMachine"/> or opened using
1937	<link to="#openMachine"/> within this VirtualBox installation. After
1938	successful method invocation, the
1939	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1940	to all registered callbacks.
1941
1942	<note>
1943	This method implicitly calls <link to="IMachine::saveSettings"/>
1944	to save all current machine settings before registering it.
1945	</note>
1946
1947	<result name="VBOX_E_OBJECT_NOT_FOUND">
1948	No matching virtual machine found.
1949	</result>
1950	<result name="VBOX_E_INVALID_OBJECT_STATE">
1951	Virtual machine was not created within this VirtualBox instance.
1952	</result>
1953
1954	</desc>
1955	<param name="machine" type="IMachine" dir="in"/>
1956	</method>
1957
1958	<method name="getMachine">
1959	<desc>
1960	Attempts to find a virtual machine given its UUID.
1961	To look up a machine by name, use <link to="IVirtualBox::findMachine" />
1962	instead.
1963
1964	<result name="VBOX_E_OBJECT_NOT_FOUND">
1965	Could not find registered machine matching @a id.
1966	</result>
1967
1968	</desc>
1969	<param name="id" type="uuid" mod="string" dir="in"/>
1970	<param name="machine" type="IMachine" dir="return"/>
1971	</method>
1972
1973	<method name="findMachine">
1974	<desc>
1975	Attempts to find a virtual machine given its name.
1976	To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
1977	instead.
1978
1979	<result name="VBOX_E_OBJECT_NOT_FOUND">
1980	Could not find registered machine matching @a name.
1981	</result>
1982
1983	</desc>
1984	<param name="name" type="wstring" dir="in"/>
1985	<param name="machine" type="IMachine" dir="return"/>
1986	</method>
1987
1988	<method name="unregisterMachine">
1989	<desc>
1990
1991	Unregisters the machine previously registered using
1992	<link to="#registerMachine"/>. After successful method invocation, the
1993	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1994	to all registered callbacks.
1995
1996	<note>
1997	The specified machine must not be in the Saved state, have an open
1998	(or a spawning) direct session associated with it, have snapshots or
1999	have any medium attached.
2000	</note>
2001
2002	<note>
2003	This method implicitly calls <link to="IMachine::saveSettings"/> to
2004	save all current machine settings before unregistering it.
2005	</note>
2006
2007	<note>
2008	If the given machine is inaccessible (see
2009	<link to="IMachine::accessible"/>), it will be unregistered and
2010	fully uninitialized right afterwards. As a result, the returned
2011	machine object will be unusable and an attempt to call
2012	<b>any</b> method will return the "Object not ready" error.
2013	</note>
2014
2015	<result name="VBOX_E_OBJECT_NOT_FOUND">
2016	Could not find registered machine matching @a id.
2017	</result>
2018	<result name="VBOX_E_INVALID_VM_STATE">
2019	Machine is in Saved state.
2020	</result>
2021	<result name="VBOX_E_INVALID_OBJECT_STATE">
2022	Machine has snapshot or open session or medium attached.
2023	</result>
2024
2025	</desc>
2026	<param name="id" type="uuid" mod="string" dir="in">
2027	<desc>UUID of the machine to unregister.</desc>
2028	</param>
2029	<param name="machine" type="IMachine" dir="return">
2030	<desc>Unregistered machine object.</desc>
2031	</param>
2032	</method>
2033
2034	<method name="createAppliance">
2035	<desc>
2036	Creates a new appliance object, which represents an appliance in the Open Virtual Machine
2037	Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
2038	machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
2039	</desc>
2040	<param name="appliance" type="IAppliance" dir="return">
2041	<desc>New appliance.</desc>
2042	</param>
2043	</method>
2044
2045	<method name="createHardDisk">
2046	<desc>
2047	Creates a new base medium object that will use the given storage
2048	format and location for medium data.
2049
2050	Note that the actual storage unit is not created by this method. In
2051	order to do it, and before you are able to attach the created medium
2052	to virtual machines, you must call one of the following methods to
2053	allocate a format-specific storage unit at the specified location:
2054	<ul>
2055	<li><link to="IMedium::createBaseStorage"/></li>
2056	<li><link to="IMedium::createDiffStorage"/></li>
2057	</ul>
2058
2059	Some medium attributes, such as <link to="IMedium::id"/>, may
2060	remain uninitialized until the medium storage unit is successfully
2061	created by one of the above methods.
2062
2063	After the storage unit is successfully created, the medium gets
2064	remembered by this VirtualBox installation and will be accessible
2065	through <link to="#getHardDisk"/> and <link to="#findHardDisk"/>
2066	methods. Remembered base medium are also returned as part of
2067	the <link to="#hardDisks"/> array. See IMedium for more details.
2068
2069	The list of all storage formats supported by this VirtualBox
2070	installation can be obtained using
2071	<link to="ISystemProperties::mediumFormats"/>. If the @a format
2072	attribute is empty or @c null then the default storage format
2073	specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
2074	be used for creating a storage unit of the medium.
2075
2076	Note that the format of the location string is storage format specific.
2077	See <link to="IMedium::location"/>, IMedium and
2078	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
2079
2080	<result name="VBOX_E_OBJECT_NOT_FOUND">
2081	@a format identifier is invalid. See
2082	<link to="ISystemProperties::mediumFormats"/>.
2083	</result>
2084	<result name="VBOX_E_FILE_ERROR">
2085	@a location is a not valid file name (for file-based formats only).
2086	</result>
2087	</desc>
2088	<param name="format" type="wstring" dir="in">
2089	<desc>
2090	Identifier of the storage format to use for the new medium.
2091	</desc>
2092	</param>
2093	<param name="location" type="wstring" dir="in">
2094	<desc>
2095	Location of the storage unit for the new medium.
2096	</desc>
2097	</param>
2098	<param name="medium" type="IMedium" dir="return">
2099	<desc>Created medium object.</desc>
2100	</param>
2101	</method>
2102
2103	<method name="openHardDisk">
2104	<desc>
2105	Opens a medium from an existing location, optionally replacing
2106	the image UUID and/or parent UUID.
2107
2108	After the medium is successfully opened by this method, it gets
2109	remembered by (known to) this VirtualBox installation and will be
2110	accessible through <link to="#getHardDisk"/> and
2111	<link to="#findHardDisk"/> methods. Remembered base media
2112	are also returned as part of the <link to="#hardDisks"/> array and can
2113	be attached to virtual machines. See IMedium for more details.
2114
2115	If a differencing medium is to be opened by this method, the
2116	operation will succeed only if its parent medium and all ancestors,
2117	if any, are already known to this VirtualBox installation (for example,
2118	were opened by this method before).
2119
2120	This method tries to guess the storage format of the specified medium
2121	by reading medium data at the specified location.
2122
2123	If @a accessMode is ReadWrite (which it should be), the image is opened
2124	for read/write access and must have according permissions, as VirtualBox
2125	may actually write status information into the disk's metadata sections.
2126
2127	Note that write access is required for all typical image usage in VirtualBox,
2128	since VirtualBox may need to write metadata such as a UUID into the image.
2129	The only exception is opening a source image temporarily for copying and
2130	cloning when the image will quickly be closed again.
2131
2132	Note that the format of the location string is storage format specific.
2133	See <link to="IMedium::location"/>, IMedium and
2134	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
2135
2136	<result name="VBOX_E_FILE_ERROR">
2137	Invalid medium storage file location or could not find the medium
2138	at the specified location.
2139	</result>
2140	<result name="VBOX_E_IPRT_ERROR">
2141	Could not get medium storage format.
2142	</result>
2143	<result name="E_INVALIDARG">
2144	Invalid medium storage format.
2145	</result>
2146
2147	</desc>
2148	<param name="location" type="wstring" dir="in">
2149	<desc>
2150	Location of the storage unit that contains medium data in one of
2151	the supported storage formats.
2152	</desc>
2153	</param>
2154	<param name="accessMode" type="AccessMode" dir="in">
2155	<desc>
2156	Determines whether to open the image in read/write or read-only mode.
2157	</desc>
2158	</param>
2159	<param name="setImageId" type="boolean" dir="in">
2160	<desc>
2161	Select whether a new image UUID is set or not.
2162	</desc>
2163	</param>
2164	<param name="imageId" type="uuid" mod="string" dir="in">
2165	<desc>
2166	New UUID for the image. If an empty string is passed, then a new
2167	UUID is automatically created. Specifying a zero UUIDs is not valid.
2168	</desc>
2169	</param>
2170	<param name="setParentId" type="boolean" dir="in">
2171	<desc>
2172	Select whether a new parent UUID is set or not.
2173	</desc>
2174	</param>
2175	<param name="parentId" type="uuid" mod="string" dir="in">
2176	<desc>
2177	New parent UUID for the image. If an empty string is passed, then a
2178	new UUID is automatically created, provided @a setParentId is
2179	@c true. A zero UUID is valid.
2180	</desc>
2181	</param>
2182	<param name="medium" type="IMedium" dir="return">
2183	<desc>Opened medium object.</desc>
2184	</param>
2185	</method>
2186
2187	<method name="getHardDisk" const="yes">
2188	<desc>
2189	Returns a medium with the given UUID.
2190
2191	The medium with the given UUID must be known to this VirtualBox
2192	installation, i.e. it must be previously created by
2193	<link to="#createHardDisk"/> or opened by <link
2194	to="#openHardDisk"/>, or attached to some known virtual machine.
2195
2196	<result name="VBOX_E_OBJECT_NOT_FOUND">
2197	No medium object matching @a id found.
2198	</result>
2199
2200	</desc>
2201	<param name="id" type="uuid" mod="string" dir="in">
2202	<desc>UUID of the medium to look for.</desc>
2203	</param>
2204	<param name="medium" type="IMedium" dir="return">
2205	<desc>Found medium object.</desc>
2206	</param>
2207	</method>
2208
2209	<method name="findHardDisk">
2210	<desc>
2211	Returns a medium that uses the given location to store medium data.
2212
2213	The given medium must be known to this VirtualBox installation, i.e.
2214	it must be previously created by
2215	<link to="#createHardDisk"/> or opened by <link
2216	to="#openHardDisk"/>, or attached to some known virtual machine.
2217
2218	The search is done by comparing the value of the @a location argument to
2219	the <link to="IMedium::location"/> attribute of each known medium.
2220
2221	For locations represented by file names in the host's file system, the
2222	requested location can be a path relative to the
2223	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2224	only a file name without any path is given, the
2225	<link to="ISystemProperties::defaultHardDiskFolder"> default medium
2226	folder</link> will be prepended to the file name before searching. Note
2227	that on case sensitive file systems, a case sensitive comparison is
2228	performed, otherwise the case of symbols in the file path is ignored.
2229
2230	<result name="VBOX_E_OBJECT_NOT_FOUND">
2231	No medium object matching @a location found.
2232	</result>
2233
2234	</desc>
2235	<param name="location" type="wstring" dir="in">
2236	<desc>Location string to search for.</desc>
2237	</param>
2238	<param name="medium" type="IMedium" dir="return">
2239	<desc>Found medium object.</desc>
2240	</param>
2241	</method>
2242
2243	<method name="openDVDImage">
2244	<desc>
2245	Opens a CD/DVD image contained in the specified file of the supported
2246	format and assigns it the given UUID.
2247
2248	After the image is successfully opened by this method, it gets
2249	remembered by (known to) this VirtualBox installation and will be
2250	accessible through <link to="#getDVDImage"/> and
2251	<link to="#findDVDImage"/> methods. Remembered images are also
2252	returned as part of the <link to="#DVDImages"/> array and can be mounted
2253	to virtual machines. See IMedium for more details.
2254
2255	See <link to="IMedium::location"/> to get more details about the format
2256	of the location string.
2257
2258	<note>
2259	Currently only ISO 9960 CD/DVD images are supported by VirtualBox.
2260	</note>
2261
2262	<result name="VBOX_E_FILE_ERROR">
2263	Invalid CD/DVD image file location or could not find the CD/DVD
2264	image at the specified location.
2265	</result>
2266	<result name="VBOX_E_INVALID_OBJECT_STATE">
2267	CD/DVD image already exists in the media registry.
2268	</result>
2269
2270	</desc>
2271	<param name="location" type="wstring" dir="in">
2272	<desc>
2273	Full path to the file that contains a valid CD/DVD image.
2274	</desc>
2275	</param>
2276	<param name="id" type="uuid" mod="string" dir="in">
2277	<desc>
2278	UUID to assign to the given image within this VirtualBox installation.
2279	If an empty (@c null) UUID is specified, the system will randomly
2280	generate a new UUID.
2281	</desc>
2282	</param>
2283	<param name="image" type="IMedium" dir="return">
2284	<desc>Opened CD/DVD image object.</desc>
2285	</param>
2286	</method>
2287
2288	<method name="getDVDImage">
2289	<desc>
2290	Returns a CD/DVD image with the given UUID.
2291
2292	The image with the given UUID must be known to this VirtualBox
2293	installation, i.e. it must be previously opened by <link
2294	to="#openDVDImage"/>, or mounted to some known virtual machine.
2295
2296	<result name="VBOX_E_OBJECT_NOT_FOUND">
2297	No matching DVD image found in the media registry.
2298	</result>
2299
2300	</desc>
2301	<param name="id" type="uuid" mod="string" dir="in">
2302	<desc>UUID of the image to look for.</desc>
2303	</param>
2304	<param name="image" type="IMedium" dir="return">
2305	<desc>Found CD/DVD image object.</desc>
2306	</param>
2307	</method>
2308
2309	<method name="findDVDImage">
2310	<desc>
2311	Returns a CD/DVD image with the given image location.
2312
2313	The image with the given UUID must be known to this VirtualBox
2314	installation, i.e. it must be previously opened by <link
2315	to="#openDVDImage"/>, or mounted to some known virtual machine.
2316
2317	The search is done by comparing the value of the @a location argument to
2318	the <link to="IMedium::location"/> attribute of each known CD/DVD image.
2319
2320	The requested location can be a path relative to the
2321	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2322	only a file name without any path is given, the
2323	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2324	folder</link> will be prepended to the file name before searching. Note
2325	that on case sensitive file systems, a case sensitive comparison is
2326	performed, otherwise the case in the file path is ignored.
2327
2328	<result name="VBOX_E_FILE_ERROR">
2329	Invalid image file location.
2330	</result>
2331	<result name="VBOX_E_OBJECT_NOT_FOUND">
2332	No matching DVD image found in the media registry.
2333	</result>
2334
2335	</desc>
2336	<param name="location" type="wstring" dir="in">
2337	<desc>CD/DVD image file path to look for.</desc>
2338	</param>
2339	<param name="image" type="IMedium" dir="return">
2340	<desc>Found CD/DVD image object.</desc>
2341	</param>
2342	</method>
2343
2344	<method name="openFloppyImage">
2345	<desc>
2346	Opens a floppy image contained in the specified file of the supported
2347	format and assigns it the given UUID.
2348
2349	After the image is successfully opened by this method, it gets
2350	remembered by (known to) this VirtualBox installation and will be
2351	accessible through <link to="#getFloppyImage"/> and
2352	<link to="#findFloppyImage"/> methods. Remembered images are also
2353	returned as part of the <link to="#floppyImages"/> array and can be
2354	mounted to virtual machines. See IMedium for more details.
2355
2356	See <link to="IMedium::location"/> to get more details about the format
2357	of the location string.
2358
2359	<result name="VBOX_E_FILE_ERROR">
2360	Invalid floppy image file location or could not find the floppy
2361	image at the specified location.
2362	</result>
2363	<result name="VBOX_E_INVALID_OBJECT_STATE">
2364	Floppy image already exists in the media registry.
2365	</result>
2366
2367	<note>
2368	Currently, only raw floppy images are supported by VirtualBox.
2369	</note>
2370	</desc>
2371	<param name="location" type="wstring" dir="in">
2372	<desc>
2373	Full path to the file that contains a valid floppy image.
2374	</desc>
2375	</param>
2376	<param name="id" type="uuid" mod="string" dir="in">
2377	<desc>
2378	UUID to assign to the given image file within this VirtualBox
2379	installation. If an empty (@c null) UUID is specified, the system will
2380	randomly generate a new UUID.
2381	</desc>
2382	</param>
2383	<param name="image" type="IMedium" dir="return">
2384	<desc>Opened floppy image object.</desc>
2385	</param>
2386	</method>
2387
2388	<method name="getFloppyImage">
2389	<desc>
2390	Returns a floppy image with the given UUID.
2391
2392	The image with the given UUID must be known to this VirtualBox
2393	installation, i.e. it must be previously opened by <link
2394	to="#openFloppyImage"/>, or mounted to some known virtual machine.
2395
2396	<result name="VBOX_E_OBJECT_NOT_FOUND">
2397	No matching floppy image found in the media registry.
2398	</result>
2399
2400	</desc>
2401	<param name="id" type="uuid" mod="string" dir="in">
2402	<desc>UUID of the image to look for.</desc>
2403	</param>
2404	<param name="image" type="IMedium" dir="return">
2405	<desc>Found floppy image object.</desc>
2406	</param>
2407	</method>
2408
2409	<method name="findFloppyImage">
2410	<desc>
2411	Returns a floppy image with the given image location.
2412
2413	The image with the given UUID must be known to this VirtualBox
2414	installation, i.e. it must be previously opened by <link
2415	to="#openFloppyImage"/>, or mounted to some known virtual machine.
2416
2417	The search is done by comparing the value of the @a location argument to
2418	the <link to="IMedium::location"/> attribute of each known floppy image.
2419
2420	The requested location can be a path relative to the
2421	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2422	only a file name without any path is given, the
2423	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2424	folder</link> will be prepended to the file name before searching. Note
2425	that on case sensitive file systems, a case sensitive comparison is
2426	performed, otherwise the case of symbols in the file path is ignored.
2427
2428	<result name="VBOX_E_FILE_ERROR">
2429	Invalid image file location.
2430	</result>
2431	<result name="VBOX_E_OBJECT_NOT_FOUND">
2432	No matching floppy image found in the media registry.
2433	</result>
2434
2435	</desc>
2436	<param name="location" type="wstring" dir="in">
2437	<desc>Floppy image file path to look for.</desc>
2438	</param>
2439	<param name="image" type="IMedium" dir="return">
2440	<desc>Found floppy image object.</desc>
2441	</param>
2442	</method>
2443
2444	<method name="getGuestOSType">
2445	<desc>
2446	Returns an object describing the specified guest OS type.
2447
2448	The requested guest OS type is specified using a string which is a
2449	mnemonic identifier of the guest operating system, such as
2450	<tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
2451	particular virtual machine can be read or set using the
2452	<link to="IMachine::OSTypeId"/> attribute.
2453
2454	The <link to="IVirtualBox::guestOSTypes"/> collection contains all
2455	available guest OS type objects. Each object has an
2456	<link to="IGuestOSType::id"/> attribute which contains an identifier of
2457	the guest OS this object describes.
2458
2459	<result name="E_INVALIDARG">
2460	@a id is not a valid Guest OS type.
2461	</result>
2462
2463	</desc>
2464	<param name="id" type="uuid" mod="string" dir="in">
2465	<desc>Guest OS type ID string.</desc>
2466	</param>
2467	<param name="type" type="IGuestOSType" dir="return">
2468	<desc>Guest OS type object.</desc>
2469	</param>
2470	</method>
2471
2472	<method name="createSharedFolder">
2473	<desc>
2474	Creates a new global shared folder by associating the given logical
2475	name with the given host path, adds it to the collection of shared
2476	folders and starts sharing it. Refer to the description of
2477	<link to="ISharedFolder"/> to read more about logical names.
2478	<note>
2479	In the current implementation, this operation is not
2480	implemented.
2481	</note>
2482	</desc>
2483	<param name="name" type="wstring" dir="in">
2484	<desc>Unique logical name of the shared folder.</desc>
2485	</param>
2486	<param name="hostPath" type="wstring" dir="in">
2487	<desc>Full path to the shared folder in the host file system.</desc>
2488	</param>
2489	<param name="writable" type="boolean" dir="in">
2490	<desc>Whether the share is writable or readonly</desc>
2491	</param>
2492	</method>
2493
2494	<method name="removeSharedFolder">
2495	<desc>
2496	Removes the global shared folder with the given name previously
2497	created by <link to="#createSharedFolder"/> from the collection of
2498	shared folders and stops sharing it.
2499	<note>
2500	In the current implementation, this operation is not
2501	implemented.
2502	</note>
2503	</desc>
2504	<param name="name" type="wstring" dir="in">
2505	<desc>Logical name of the shared folder to remove.</desc>
2506	</param>
2507	</method>
2508
2509	<method name="getExtraDataKeys">
2510	<desc>
2511	Returns an array representing the global extra data keys which currently
2512	have values defined.
2513	</desc>
2514	<param name="value" type="wstring" dir="return" safearray="yes">
2515	<desc>Array of extra data keys.</desc>
2516	</param>
2517	</method>
2518
2519	<method name="getExtraData">
2520	<desc>
2521	Returns associated global extra data.
2522
2523	If the requested data @a key does not exist, this function will
2524	succeed and return an empty string in the @a value argument.
2525
2526	<result name="VBOX_E_FILE_ERROR">
2527	Settings file not accessible.
2528	</result>
2529	<result name="VBOX_E_XML_ERROR">
2530	Could not parse the settings file.
2531	</result>
2532
2533	</desc>
2534	<param name="key" type="wstring" dir="in">
2535	<desc>Name of the data key to get.</desc>
2536	</param>
2537	<param name="value" type="wstring" dir="return">
2538	<desc>Value of the requested data key.</desc>
2539	</param>
2540	</method>
2541
2542	<method name="setExtraData">
2543	<desc>
2544	Sets associated global extra data.
2545
2546	If you pass @c null or empty string as a key @a value, the given @a key
2547	will be deleted.
2548
2549	<note>
2550	Before performing the actual data change, this method will ask all
2551	registered callbacks using the
2552	<link to="IVirtualBoxCallback::onExtraDataCanChange"/>
2553	notification for a permission. If one of the callbacks refuses the
2554	new value, the change will not be performed.
2555	</note>
2556	<note>
2557	On success, the
2558	<link to="IVirtualBoxCallback::onExtraDataChange"/> notification
2559	is called to inform all registered callbacks about a successful data
2560	change.
2561	</note>
2562
2563	<result name="VBOX_E_FILE_ERROR">
2564	Settings file not accessible.
2565	</result>
2566	<result name="VBOX_E_XML_ERROR">
2567	Could not parse the settings file.
2568	</result>
2569	<result name="E_ACCESSDENIED">
2570	Modification request refused.
2571	</result>
2572
2573	</desc>
2574	<param name="key" type="wstring" dir="in">
2575	<desc>Name of the data key to set.</desc>
2576	</param>
2577	<param name="value" type="wstring" dir="in">
2578	<desc>Value to assign to the key.</desc>
2579	</param>
2580	</method>
2581
2582	<method name="openSession">
2583	<desc>
2584	Opens a new direct session with the given virtual machine.
2585
2586	A direct session acts as a local lock on the given VM.
2587	There can be only one direct session open at a time for every
2588	virtual machine, protecting the VM from being manipulated by
2589	conflicting actions from different processes. Only after a
2590	direct session has been opened, one can change all VM settings
2591	and execute the VM in the process space of the session object.
2592
2593	Sessions therefore can be compared to mutex semaphores that
2594	lock a given VM for modification and execution.
2595	See <link to="ISession">ISession</link> for details.
2596
2597	<note>Unless you are writing a new VM frontend, you will not
2598	want to execute a VM in the current process. To spawn a new
2599	process that executes a VM, use
2600	<link to="IVirtualBox::openRemoteSession" />
2601	instead.</note>
2602
2603	Upon successful return, the session object can be used to
2604	get access to the machine and to the VM console.
2605
2606	In VirtualBox terminology, the machine becomes "mutable" after
2607	a session has been opened. Note that the "mutable" machine
2608	object, on which you may invoke IMachine methods to change its
2609	settings, will be a different object from the immutable IMachine
2610	objects returned by various IVirtualBox methods. To obtain a
2611	mutable IMachine object (upon which you can invoke settings methods),
2612	use the <link to="ISession::machine" /> attribute.
2613
2614	One must always call <link to="ISession::close" /> to release the
2615	lock on the machine, or the machine's state will eventually be
2616	set to "Aborted".
2617
2618	In other words, to change settings on a machine, the following
2619	sequence is typically performed:
2620
2621	<ol>
2622	<li>Call this method (openSession) to have a machine locked for
2623	the current session.</li>
2624
2625	<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
2626
2627	<li>Change the settings of the machine.</li>
2628
2629	<li>Call <link to="IMachine::saveSettings" />.</li>
2630
2631	<li>Close the session by calling <link to="ISession::close"/>.</li>
2632	</ol>
2633
2634	<result name="E_UNEXPECTED">
2635	Virtual machine not registered.
2636	</result>
2637	<result name="E_ACCESSDENIED">
2638	Process not started by OpenRemoteSession.
2639	</result>
2640	<result name="VBOX_E_OBJECT_NOT_FOUND">
2641	No matching virtual machine found.
2642	</result>
2643	<result name="VBOX_E_INVALID_OBJECT_STATE">
2644	Session already open or being opened.
2645	</result>
2646	<result name="VBOX_E_VM_ERROR">
2647	Failed to assign machine to session.
2648	</result>
2649
2650	</desc>
2651	<param name="session" type="ISession" dir="in">
2652	<desc>
2653	Session object that will represent the opened session after
2654	successful method invocation. This object must not represent
2655	the already open session.
2656	<note>
2657	This session will be automatically closed if the
2658	VirtualBox server is terminated for some reason.
2659	</note>
2660	</desc>
2661	</param>
2662	<param name="machineId" type="uuid" mod="string" dir="in">
2663	<desc>ID of the virtual machine to open a session with.</desc>
2664	</param>
2665	</method>
2666
2667	<method name="openRemoteSession">
2668	<desc>
2669	Spawns a new process that executes a virtual machine (called a
2670	"remote session").
2671
2672	Opening a remote session causes the VirtualBox server to start a new
2673	process that opens a direct session with the given VM. As a result, the
2674	VM is locked by that direct session in the new process, preventing
2675	conflicting changes from other processes. Since sessions act as locks
2676	that prevent conflicting changes, one cannot open a remote session
2677	for a VM that already has another open session (direct or remote), or
2678	is currently in the process of opening one (see <link
2679	to="IMachine::sessionState"/>).
2680
2681	While the remote session still provides some level of control over the
2682	VM execution to the caller (using the <link to="IConsole" /> interface),
2683	not all VM settings are available for modification within the remote
2684	session context.
2685
2686	This operation can take some time (a new VM is started in a new process,
2687	for which memory and other resources need to be set up). Because of this,
2688	an <link to="IProgress" /> is returned to allow the caller to wait for this
2689	asynchronous operation to be completed. Until then, the remote session
2690	object remains in the closed state, and accessing the machine or its
2691	console through it is invalid. It is recommended to use
2692	<link to="IProgress::waitForCompletion" /> or similar calls to wait for
2693	completion. Completion is signalled when the VM is powered on. Error
2694	messages etc. can be queried via the progress object, if available.
2695
2696	As with all <link to="ISession" /> objects, it is recommended to call
2697	<link to="ISession::close" /> on the local session object once openRemoteSession()
2698	has been called. However, the session's state (see <link to="ISession::state" />)
2699	will not return to "Closed" until the remote session has also closed (i.e.
2700	until the VM is no longer running). In that case, however, the state of
2701	the session will automatically change back to "Closed".
2702
2703	Currently supported session types (values of the @a type
2704	argument) are:
2705	<ul>
2706	<li><tt>"gui"</tt>: VirtualBox Qt GUI session</li>
2707	<li><tt>"vrdp"</tt>: VirtualBox VRDP Server session</li>
2708	<li><tt>"sdl"</tt>: VirtualBox SDL GUI session</li>
2709	</ul>
2710
2711	The @a environment argument is a string containing definitions of
2712	environment variables in the following format:
2713	@code
2714	NAME[=VALUE]\n
2715	NAME[=VALUE]\n
2716	...
2717	@endcode
2718	where <tt>\\n</tt> is the new line character. These environment
2719	variables will be appended to the environment of the VirtualBox server
2720	process. If an environment variable exists both in the server process
2721	and in this list, the value from this list takes precedence over the
2722	server's variable. If the value of the environment variable is
2723	omitted, this variable will be removed from the resulting environment.
2724	If the environment string is @c null or empty, the server environment
2725	is inherited by the started process as is.
2726
2727	<see>openExistingSession</see>
2728
2729	<result name="E_UNEXPECTED">
2730	Virtual machine not registered.
2731	</result>
2732	<result name="E_INVALIDARG">
2733	Invalid session type @a type.
2734	</result>
2735	<result name="VBOX_E_OBJECT_NOT_FOUND">
2736	No machine matching @a machineId found.
2737	</result>
2738	<result name="VBOX_E_INVALID_OBJECT_STATE">
2739	Session already open or being opened.
2740	</result>
2741	<result name="VBOX_E_IPRT_ERROR">
2742	Launching process for machine failed.
2743	</result>
2744	<result name="VBOX_E_VM_ERROR">
2745	Failed to assign machine to session.
2746	</result>
2747
2748	</desc>
2749	<param name="session" type="ISession" dir="in">
2750	<desc>
2751	Session object that will represent the opened remote session
2752	after successful method invocation (this object must not
2753	represent an already open session).
2754	</desc>
2755	</param>
2756	<param name="machineId" type="uuid" mod="string" dir="in">
2757	<desc>ID of the virtual machine to open a session with.</desc>
2758	</param>
2759	<param name="type" type="wstring" dir="in">
2760	<desc>
2761	Type of the remote session (case sensitive).
2762	</desc>
2763	</param>
2764	<param name="environment" type="wstring" dir="in">
2765	<desc>
2766	Environment to pass to the opened session.
2767	</desc>
2768	</param>
2769	<param name="progress" type="IProgress" dir="return">
2770	<desc>Progress object to track the operation completion.</desc>
2771	</param>
2772	</method>
2773
2774	<method name="openExistingSession">
2775	<desc>
2776	Opens a new remote session with the virtual machine for
2777	which a direct session is already open.
2778
2779	The remote session provides some level of control over the VM
2780	execution (using the IConsole interface) to the caller; however,
2781	within the remote session context, not all VM settings are available
2782	for modification.
2783
2784	As opposed to <link to="#openRemoteSession"/>, the number of
2785	remote sessions opened this way is not limited by the API
2786
2787	<note>
2788	It is an error to open a remote session with the machine that
2789	doesn't have an open direct session.
2790	</note>
2791
2792	<result name="E_UNEXPECTED">
2793	Virtual machine not registered.
2794	</result>
2795	<result name="VBOX_E_OBJECT_NOT_FOUND">
2796	No machine matching @a machineId found.
2797	</result>
2798	<result name="VBOX_E_INVALID_OBJECT_STATE">
2799	Session already open or being opened.
2800	</result>
2801	<result name="VBOX_E_INVALID_SESSION_STATE">
2802	Direct session state not Open.
2803	</result>
2804	<result name="VBOX_E_VM_ERROR">
2805	Failed to get console object from direct session or assign
2806	machine to session.
2807	</result>
2808
2809	<see>openRemoteSession</see>
2810	</desc>
2811	<param name="session" type="ISession" dir="in">
2812	<desc>
2813	Session object that will represent the open remote session
2814	after successful method invocation. This object must not
2815	represent an already open session.
2816	<note>
2817	This session will be automatically closed when the peer
2818	(direct) session dies or gets closed.
2819	</note>
2820	</desc>
2821	</param>
2822	<param name="machineId" type="uuid" mod="string" dir="in">
2823	<desc>ID of the virtual machine to open a session with.</desc>
2824	</param>
2825	</method>
2826
2827	<method name="registerCallback">
2828	<desc>
2829	Registers a new global VirtualBox callback. The methods of the given
2830	callback object will be called by VirtualBox when an appropriate
2831	event occurs.
2832
2833	<result name="E_INVALIDARG">
2834	A @c null callback cannot be registered.
2835	</result>
2836
2837	</desc>
2838	<param name="callback" type="IVirtualBoxCallback" dir="in">
2839	<desc>Callback object to register.</desc>
2840	</param>
2841	</method>
2842
2843	<method name="unregisterCallback">
2844	<desc>
2845	Unregisters the previously registered global VirtualBox callback.
2846
2847	<result name="E_INVALIDARG">
2848	Specified @a callback not registered.
2849	</result>
2850
2851	</desc>
2852	<param name="callback" type="IVirtualBoxCallback" dir="in">
2853	<desc>Callback object to unregister.</desc>
2854	</param>
2855	</method>
2856
2857	<method name="waitForPropertyChange">
2858	<desc>
2859	Blocks the caller until any of the properties represented by the
2860	@a what argument changes the value or until the given timeout interval
2861	expires.
2862
2863	The @a what argument is a comma separated list of property masks that
2864	describe properties the caller is interested in. The property mask is
2865	a string in the following format:
2866
2867	<pre>
2868	[[group.]subgroup.]name
2869	</pre>
2870
2871	where @c name is the property name and @c group, @c subgroup are zero
2872	or more property group specifiers. Each element (group or name) in
2873	the property mask may be either a Latin string or an asterisk symbol
2874	(@c "*") which is used to match any string for the given element. A
2875	property mask that doesn't contain asterisk symbols represents a
2876	single fully qualified property name.
2877
2878	Groups in the fully qualified property name go from more generic (the
2879	left-most part) to more specific (the right-most part). The first
2880	element is usually a name of the object the property belongs to. The
2881	second element may be either a property name, or a child object name,
2882	or an index if the preceding element names an object which is one of
2883	many objects of the same type. This way, property names form a
2884	hierarchy of properties. Here are some examples of property names:
2885
2886	<table>
2887	<tr>
2888	<td><tt>VirtualBox.version</tt></td>
2889	<td><link to="IVirtualBox::version"/> property</td>
2890	</tr>
2891	<tr>
2892	<td><tt>Machine.<UUID>.name</tt></td>
2893	<td><link to="IMachine::name"/> property of the machine with the
2894	given UUID</td>
2895	</tr>
2896	</table>
2897
2898	Most property names directly correspond to the properties of objects
2899	(components) provided by the VirtualBox library and may be used to
2900	track changes to these properties. However, there may be
2901	pseudo-property names that don't correspond to any existing object's
2902	property directly, as well as there may be object properties that
2903	don't have a corresponding property name that is understood by this
2904	method, and therefore changes to such properties cannot be
2905	tracked. See individual object's property descriptions to get a
2906	fully qualified property name that can be used with this method (if
2907	any).
2908
2909	There is a special property mask @c "*" (i.e. a string consisting of a
2910	single asterisk symbol) that can be used to match all properties.
2911	Below are more examples of property masks:
2912
2913	<table>
2914	<tr>
2915	<td><tt>VirtualBox.*</tt></td>
2916	<td>Track all properties of the VirtualBox object</td>
2917	</tr>
2918	<tr>
2919	<td><tt>Machine.*.name</tt></td>
2920	<td>Track changes to the <link to="IMachine::name"/> property of
2921	all registered virtual machines</td>
2922	</tr>
2923	</table>
2924
2925	<note>
2926	This function is not implemented in the current version of the
2927	product.
2928	</note>
2929	</desc>
2930	<param name="what" type="wstring" dir="in">
2931	<desc>Comma separated list of property masks.</desc>
2932	</param>
2933	<param name="timeout" type="unsigned long" dir="in">
2934	<desc>
2935	Wait timeout in milliseconds.
2936	Specify -1 for an indefinite wait.
2937	</desc>
2938	</param>
2939	<param name="changed" type="wstring" dir="out">
2940	<desc>
2941	Comma separated list of properties that have been changed and caused
2942	this method to return to the caller.
2943	</desc>
2944	</param>
2945	<param name="values" type="wstring" dir="out">
2946	<desc>Reserved, not currently used.</desc>
2947	</param>
2948	</method>
2949
2950	<!--method name="createDHCPServerForInterface">
2951	<desc>
2952	Creates a dhcp server settings to be used for the given interface
2953	<result name="E_INVALIDARG">
2954	Host network interface @a name already exists.
2955	</result>
2956	</desc>
2957	<param name="interface" type="IHostNetworkInterface" dir="in">
2958	<desc>Network Interface</desc>
2959	</param>
2960	<param name="server" type="IDHCPServer" dir="out">
2961	<desc>Dhcp server settings</desc>
2962	</param>
2963	</method-->
2964
2965	<method name="createDHCPServer">
2966	<desc>
2967	Creates a dhcp server settings to be used for the given internal network name
2968	<result name="E_INVALIDARG">
2969	Host network interface @a name already exists.
2970	</result>
2971	</desc>
2972	<param name="name" type="wstring" dir="in">
2973	<desc>server name</desc>
2974	</param>
2975	<param name="server" type="IDHCPServer" dir="return">
2976	<desc>Dhcp server settings</desc>
2977	</param>
2978	</method>
2979
2980	<method name="findDHCPServerByNetworkName">
2981	<desc>
2982	Searches a dhcp server settings to be used for the given internal network name
2983	<result name="E_INVALIDARG">
2984	Host network interface @a name already exists.
2985	</result>
2986
2987	</desc>
2988	<param name="name" type="wstring" dir="in">
2989	<desc>server name</desc>
2990	</param>
2991	<param name="server" type="IDHCPServer" dir="return">
2992	<desc>Dhcp server settings</desc>
2993	</param>
2994	</method>
2995
2996	<!--method name="findDHCPServerForInterface">
2997	<desc>
2998	Searches a dhcp server settings to be used for the given interface
2999	<result name="E_INVALIDARG">
3000	Host network interface @a name already exists.
3001	</result>
3002	</desc>
3003	<param name="interface" type="IHostNetworkInterface" dir="in">
3004	<desc>Network Interface</desc>
3005	</param>
3006	<param name="server" type="IDHCPServer" dir="out">
3007	<desc>Dhcp server settings</desc>
3008	</param>
3009	</method-->
3010
3011	<method name="removeDHCPServer">
3012	<desc>
3013	Removes the dhcp server settings
3014	<result name="E_INVALIDARG">
3015	Host network interface @a name already exists.
3016	</result>
3017	</desc>
3018	<param name="server" type="IDHCPServer" dir="in">
3019	<desc>Dhcp server settings to be removed</desc>
3020	</param>
3021	</method>
3022
3023
3024	<method name="checkFirmwarePresent">
3025	<desc>
3026	Check if this VirtualBox installation has a firmware
3027	of the given type available, either system-wide or per-user.
3028	Optionally, this may return a hint where this firmware can be
3029	downloaded from.
3030	</desc>
3031	<param name="firmwareType" type="FirmwareType" dir="in">
3032	<desc>
3033	Type of firmware to check.
3034	</desc>
3035	</param>
3036	<param name="version" type="wstring" dir="in">
3037	<desc>Expected version number, usually empty string (presently ignored).</desc>
3038	</param>
3039
3040	<param name="url" type="wstring" dir="out">
3041	<desc>
3042	Suggested URL to download this firmware from.
3043	</desc>
3044	</param>
3045
3046	<param name="file" type="wstring" dir="out">
3047	<desc>
3048	Filename of firmware, only valid if result == TRUE.
3049	</desc>
3050	</param>
3051
3052	<param name="result" type="boolean" dir="return">
3053	<desc>If firmware of this type and version is available.</desc>
3054	</param>
3055	</method>
3056
3057	</interface>
3058
3059	<!--
3060	// IVFSExplorer
3061	/////////////////////////////////////////////////////////////////////////
3062	-->
3063
3064	<enum
3065	name="VFSType"
3066	uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
3067	>
3068	<desc>
3069	Virtual file systems supported by VFSExplorer.
3070	</desc>
3071
3072	<const name="File" value="1" />
3073	<const name="Cloud" value="2" />
3074	<const name="S3" value="3" />
3075	<const name="WebDav" value="4" />
3076	</enum>
3077
3078	<enum
3079	name="VFSFileType"
3080	uuid="714333cd-44e2-415f-a245-d378fa9b1242"
3081	>
3082	<desc>
3083	File types known by VFSExplorer.
3084	</desc>
3085
3086	<const name="Unknown" value="1" />
3087	<const name="Fifo" value="2" />
3088	<const name="DevChar" value="3" />
3089	<const name="Directory" value="4" />
3090	<const name="DevBlock" value="5" />
3091	<const name="File" value="6" />
3092	<const name="SymLink" value="7" />
3093	<const name="Socket" value="8" />
3094	<const name="WhiteOut" value="9" />
3095	</enum>
3096
3097	<interface
3098	name="IVFSExplorer" extends="$unknown"
3099	uuid="2bb864a1-02a3-4474-a1d4-fb5f23b742e1"
3100	wsmap="managed"
3101	>
3102	<desc>
3103	The VFSExplorer interface unifies access to different file system
3104	types. This includes local file systems as well remote file systems like
3105	S3. For a list of supported types see <link to="VFSType" />.
3106	An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
3107	</desc>
3108
3109	<attribute name="path" type="wstring" readonly="yes">
3110	<desc>Returns the current path in the virtual file system.</desc>
3111	</attribute>
3112
3113	<attribute name="type" type="VFSType" readonly="yes">
3114	<desc>Returns the file system type which is currently in use.</desc>
3115	</attribute>
3116
3117	<method name="update">
3118	<desc>Updates the internal list of files/directories from the
3119	current directory level. Use <link to="#entryList" /> to get the full list
3120	after a call to this method.</desc>
3121
3122	<param name="aProgress" type="IProgress" dir="return">
3123	<desc>Progress object to track the operation completion.</desc>
3124	</param>
3125	</method>
3126
3127	<method name="cd">
3128	<desc>Change the current directory level.</desc>
3129
3130	<param name="aDir" type="wstring" dir="in">
3131	<desc>The name of the directory to go in.</desc>
3132	</param>
3133
3134	<param name="aProgress" type="IProgress" dir="return">
3135	<desc>Progress object to track the operation completion.</desc>
3136	</param>
3137	</method>
3138
3139	<method name="cdUp">
3140	<desc>Go one directory upwards from the current directory level.</desc>
3141
3142	<param name="aProgress" type="IProgress" dir="return">
3143	<desc>Progress object to track the operation completion.</desc>
3144	</param>
3145	</method>
3146
3147	<method name="entryList">
3148	<desc>Returns a list of files/directories after a call to <link
3149	to="#update" />. The user is responsible for keeping this internal
3150	list up do date.</desc>
3151
3152	<param name="aNames" type="wstring" safearray="yes" dir="out">
3153	<desc>The list of names for the entries.</desc>
3154	</param>
3155
3156	<param name="aTypes" type="unsigned long" safearray="yes" dir="out">
3157	<desc>The list of types for the entries.</desc>
3158	</param>
3159	</method>
3160
3161	<method name="exists">
3162	<desc>Checks if the given file list exists in the current directory
3163	level.</desc>
3164
3165	<param name="aNames" type="wstring" safearray="yes" dir="in">
3166	<desc>The names to check.</desc>
3167	</param>
3168
3169	<param name="aExists" type="wstring" safearray="yes" dir="return">
3170	<desc>The names which exist.</desc>
3171	</param>
3172	</method>
3173
3174	<method name="remove">
3175	<desc>Deletes the given files in the current directory level.</desc>
3176
3177	<param name="aNames" type="wstring" safearray="yes" dir="in">
3178	<desc>The names to remove.</desc>
3179	</param>
3180
3181	<param name="aProgress" type="IProgress" dir="return">
3182	<desc>Progress object to track the operation completion.</desc>
3183	</param>
3184	</method>
3185
3186	</interface>
3187
3188	<!--
3189	// IAppliance
3190	/////////////////////////////////////////////////////////////////////////
3191	-->
3192
3193	<interface
3194	name="IAppliance" extends="$unknown"
3195	uuid="e3ba9ab9-ac2c-4266-8bd2-91c4bf721ceb"
3196	wsmap="managed"
3197	>
3198	<desc>
3199	Represents a platform-independent appliance in OVF format. An instance of this is returned
3200	by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
3201	virtual machines within an appliance with VirtualBox.
3202
3203	The OVF standard suggests two different physical file formats:
3204
3205	<ol>
3206	<li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
3207	file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
3208	this descriptor file references other files such as disk images, as OVF appliances typically
3209	do, those additional files must be in the same directory as the descriptor file.</li>
3210
3211	<li>If the appliance is distributed as a single file, it must be in TAR format and have the
3212	<tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
3213	files and optionally other files.
3214
3215	At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
3216	be added with a later version.</li>
3217	</ol>
3218
3219	<b>Importing</b> an OVF appliance into VirtualBox as instances of
3220	<link to="IMachine" /> involves the following sequence of API calls:
3221
3222	<ol>
3223	<li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
3224	</li>
3225
3226	<li>On the new object, call <link to="#read" /> with the full path of the OVF file you
3227	would like to import. So long as this file is syntactically valid, this will succeed
3228	and fill the appliance object with the parsed data from the OVF file.
3229	</li>
3230
3231	<li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
3232	contents of the IAppliance attributes accordingly. These can be inspected by a
3233	VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
3234	user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
3235	instances of <link to="IVirtualSystemDescription" /> which represent the virtual
3236	systems in the OVF, which in turn describe the virtual hardware prescribed by the
3237	OVF (network and hardware adapters, virtual disk images, memory size and so on).
3238	The GUI can then give the user the option to confirm and/or change these suggestions.
3239	</li>
3240
3241	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3242	virtual system to override the suggestions made by the interpret() routine.
3243	</li>
3244
3245	<li>Finally, call <link to="#importMachines" /> to create virtual machines in
3246	VirtualBox as instances of <link to="IMachine" /> that match the information in the
3247	virtual system descriptions.
3248	</li>
3249	</ol>
3250
3251	<b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
3252
3253	<ol>
3254	<li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
3255	an empty IAppliance object.
3256	</li>
3257
3258	<li>For each machine you would like to export, call <link to="IMachine::export" />
3259	with the IAppliance object you just created. This creates an instance of
3260	<link to="IVirtualSystemDescription" /> inside the appliance.
3261	</li>
3262
3263	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3264	virtual system to override the suggestions made by the export() routine.
3265	</li>
3266
3267	<li>Finally, call <link to="#write" /> with a path specification to have the OVF
3268	file written.</li>
3269	</ol>
3270
3271	</desc>
3272
3273	<attribute name="path" type="wstring" readonly="yes">
3274	<desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
3275	the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
3276	<link to="#write" /> (for export).
3277	This attribute is empty until one of these methods has been called.
3278	</desc>
3279	</attribute>
3280
3281	<attribute name="disks" type="wstring" readonly="yes" safearray="yes">
3282	<desc>
3283	Array of virtual disk definitions. One such description exists for each
3284	disk definition in the OVF; each string array item represents one such piece of
3285	disk information, with the information fields separated by tab (\t) characters.
3286
3287	The caller should be prepared for additional fields being appended to
3288	this string in future versions of VirtualBox and therefore check for
3289	the number of tabs in the strings returned.
3290
3291	In the current version, the following eight fields are returned per string
3292	in the array:
3293
3294	<ol>
3295	<li>Disk ID (unique string identifier given to disk)</li>
3296
3297	<li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
3298
3299	<li>Populated size (optional unsigned integer indicating the current size of the
3300	disk; can be approximate; -1 if unspecified)</li>
3301
3302	<li>Format (string identifying the disk format, typically
3303	"http://www.vmware.com/specifications/vmdk.html#sparse")</li>
3304
3305	<li>Reference (where to find the disk image, typically a file name; if empty,
3306	then the disk should be created on import)</li>
3307
3308	<li>Image size (optional unsigned integer indicating the size of the image,
3309	which need not necessarily be the same as the values specified above, since
3310	the image may be compressed or sparse; -1 if not specified)</li>
3311
3312	<li>Chunk size (optional unsigned integer if the image is split into chunks;
3313	presently unsupported and always -1)</li>
3314
3315	<li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
3316	</ol>
3317	</desc>
3318	</attribute>
3319
3320	<attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
3321	<desc> Array of virtual system descriptions. One such description is created
3322	for each virtual system found in the OVF.
3323	This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
3324	(for export) has been called.
3325	</desc>
3326	</attribute>
3327
3328	<method name="read">
3329	<desc>
3330	Reads an OVF file into the appliance object.
3331
3332	This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
3333	mere fact that this method returns successfully does not mean that VirtualBox supports all
3334	features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
3335	</desc>
3336	<param name="file" type="wstring" dir="in">
3337	<desc>
3338	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3339	on whether the appliance is distributed as a set of files or as a single file, respectively).
3340	</desc>
3341	</param>
3342	<param name="aProgress" type="IProgress" dir="return">
3343	<desc></desc>
3344	</param>
3345	</method>
3346
3347	<method name="interpret">
3348	<desc>
3349	Interprets the OVF data that was read when the appliance was constructed. After
3350	calling this method, one can inspect the
3351	<link to="#virtualSystemDescriptions" /> array attribute, which will then contain
3352	one <link to="IVirtualSystemDescription" /> for each virtual machine found in
3353	the appliance.
3354
3355	Calling this method is the second step of importing an appliance into VirtualBox;
3356	see <link to="IAppliance" /> for an overview.
3357
3358	After calling this method, one should call <link to="#getWarnings" /> to find out
3359	if problems were encountered during the processing which might later lead to
3360	errors.
3361	</desc>
3362	</method>
3363
3364	<method name="importMachines">
3365	<desc>
3366	Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
3367	and other interfaces that match the information contained in the appliance as
3368	closely as possible, as represented by the import instructions in the
3369	<link to="#virtualSystemDescriptions" /> array.
3370
3371	Calling this method is the final step of importing an appliance into VirtualBox;
3372	see <link to="IAppliance" /> for an overview.
3373
3374	Since importing the appliance will most probably involve copying and converting
3375	disk images, which can take a long time, this method operates asynchronously and
3376	returns an IProgress object to allow the caller to monitor the progress.
3377	</desc>
3378
3379	<param name="aProgress" type="IProgress" dir="return">
3380	<desc></desc>
3381	</param>
3382	</method>
3383
3384	<method name="createVFSExplorer">
3385	<desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
3386
3387	<param name="aUri" type="wstring" dir="in">
3388	<desc>The URI describing the file system to use.</desc>
3389	</param>
3390
3391	<param name="aExplorer" type="IVFSExplorer" dir="return">
3392	<desc></desc>
3393	</param>
3394	</method>
3395
3396	<method name="write">
3397	<desc>
3398	Writes the contents of the appliance exports into a new OVF file.
3399
3400	Calling this method is the final step of exporting an appliance from VirtualBox;
3401	see <link to="IAppliance" /> for an overview.
3402
3403	Since exporting the appliance will most probably involve copying and converting
3404	disk images, which can take a long time, this method operates asynchronously and
3405	returns an IProgress object to allow the caller to monitor the progress.
3406	</desc>
3407	<param name="format" type="wstring" dir="in">
3408	<desc>
3409	Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
3410	future versions of VirtualBox may support additional formats.
3411	</desc>
3412	</param>
3413	<param name="path" type="wstring" dir="in">
3414	<desc>
3415	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3416	on whether the appliance is distributed as a set of files or as a single file, respectively).
3417	</desc>
3418	</param>
3419	<param name="aProgress" type="IProgress" dir="return">
3420	<desc>Progress object to track the operation completion.</desc>
3421	</param>
3422	</method>
3423
3424	<method name="getWarnings">
3425	<desc>Returns textual warnings which occured during execution of <link to="#interpret" />.</desc>
3426
3427	<param name="aWarnings" type="wstring" dir="return" safearray="yes">
3428	<desc></desc>
3429	</param>
3430	</method>
3431
3432	</interface>
3433
3434	<enum
3435	name="VirtualSystemDescriptionType"
3436	uuid="aacc58de-5b45-4f82-ae2e-dd9a824fc3b5"
3437	>
3438	<desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
3439	a configuration value.</desc>
3440
3441	<const name="Ignore" value="1" />
3442	<const name="OS" value="2" />
3443	<const name="Name" value="3" />
3444	<const name="Product" value="4" />
3445	<const name="Vendor" value="5" />
3446	<const name="Version" value="6" />
3447	<const name="ProductUrl" value="7" />
3448	<const name="VendorUrl" value="8" />
3449	<const name="Description" value="9" />
3450	<const name="License" value="10" />
3451	<const name="Miscellaneous" value="11" />
3452	<const name="CPU" value="12" />
3453	<const name="Memory" value="13" />
3454	<const name="HardDiskControllerIDE" value="14" />
3455	<const name="HardDiskControllerSATA" value="15" />
3456	<const name="HardDiskControllerSCSI" value="16" />
3457	<const name="HardDiskImage" value="17" />
3458	<const name="Floppy" value="18" />
3459	<const name="CDROM" value="19" />
3460	<const name="NetworkAdapter" value="20" />
3461	<const name="USBController" value="21" />
3462	<const name="SoundCard" value="22" />
3463
3464	</enum>
3465
3466	<enum
3467	name="VirtualSystemDescriptionValueType"
3468	uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
3469	>
3470	<desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
3471	type to fetch.</desc>
3472
3473	<const name="Reference" value="1" />
3474	<const name="Original" value="2" />
3475	<const name="Auto" value="3" />
3476	<const name="ExtraConfig" value="4" />
3477
3478	</enum>
3479
3480	<interface
3481	name="IVirtualSystemDescription" extends="$unknown"
3482	uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
3483	wsmap="managed"
3484	>
3485
3486	<desc>This interface is used in the <link to="IAppliance::virtualSystemDescriptions" /> array.
3487	After <link to="IAppliance::interpret" /> has been called, that array contains
3488	information about how the virtual systems described in the OVF should best be imported into VirtualBox
3489	virtual machines. See <link to="IAppliance" /> for the steps required to import an OVF
3490	into VirtualBox.
3491	</desc>
3492
3493	<attribute name="count" type="unsigned long" readonly="yes">
3494	<desc>Return the number of virtual system description entries.</desc>
3495	</attribute>
3496
3497	<method name="getDescription">
3498	<desc>Returns information about the virtual system as arrays of instruction items. In each array, the
3499	items with the same indices correspond and jointly represent an import instruction for VirtualBox.
3500
3501	The list below identifies the value sets that are possible depending on the
3502	<link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
3503	the array item with the same index in @a aOvfValues[] will contain the original value as contained
3504	in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
3505	will contain a suggested value to be used for VirtualBox. Depending on the description type,
3506	the @a aExtraConfigValues[] array item may also be used.
3507
3508	<ul>
3509	<li>
3510	"OS": the guest operating system type. There must be exactly one such array item on import. The
3511	corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
3512	This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
3513	item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF.
3514	</li>
3515	<li>
3516	"Name": the name to give to the new virtual machine. There can be at most one such array item;
3517	if none is present on import, then an automatic name will be created from the operating system
3518	type. The correponding item im @a aOvfValues[] will contain the suggested virtual machine name
3519	from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
3520	<link to="IMachine" /> name that does not exist yet.
3521	</li>
3522	<li>
3523	"Description": an arbitrary description.
3524	</li>
3525	<li>
3526	"License": the EULA section from the OVF, if present. It is the responsibility of the calling
3527	code to display such a license for agreement; the Main API does not enforce any such policy.
3528	</li>
3529	<li>
3530	Miscellaneous: reserved for future use.
3531	</li>
3532	<li>
3533	"CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
3534	</li>
3535	<li>
3536	"Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
3537	is present on import, then VirtualBox will set a meaningful default based on the operating system
3538	type.
3539	</li>
3540	<li>
3541	"HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
3542	An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
3543	the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
3544	writes into the OVF.
3545	The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
3546	type can use to specify which hard disk controller a virtual disk should be connected to.
3547	Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
3548	in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
3549	its virtual machines supports four channels (primary master, primary slave, secondary master,
3550	secondary slave) and thus maps to two IDE controllers in the OVF sense.
3551	</li>
3552	<li>
3553	"HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
3554	has no value in @a aOvfValues[] or @a aVBoxValues[].
3555	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3556	</li>
3557	<li>
3558	"HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
3559	The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic" or "BusLogic".
3560	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3561	</li>
3562	<li>
3563	"HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
3564	arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
3565
3566	The array item in @a aOvfValues[] will contain the file specification from the OVF file (without
3567	a path since the image file should be in the same location as the OVF file itself), whereas the
3568	item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
3569	hard disk image. This means that on import the image will be copied and converted from the
3570	"ovf" location to the "vbox" location; on export, this will be handled the other way round.
3571	On import, the target image will also be registered with VirtualBox.
3572
3573	The matching item in the @a aExtraConfigValues[] array must contain a string of the following
3574	format: "controller=<index>;channel=<c>"
3575	In this string, <index> must be an integer specifying the hard disk controller to connect
3576	the image to. That number must be the index of an array item with one of the hard disk controller
3577	types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
3578	In addition, <c> must specify the channel to use on that controller. For IDE controllers,
3579	this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
3580	before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
3581	no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
3582	</li>
3583	<li>
3584	"CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
3585	attachment information as with "HardDiskImage" items.
3586	</li>
3587	<li>
3588	"CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
3589	attachment information as with "HardDiskImage" items.
3590	</li>
3591	<li>
3592	"NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
3593	for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
3594	of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
3595	</li>
3596	<li>
3597	"USBController": a USB controller. There can be at most one such item. If and only if such an
3598	item ispresent, USB support will be enabled for the new virtual machine.
3599	</li>
3600	<li>
3601	"SoundCard": a sound card. There can be at most one such item. If and only if such an item is
3602	present, sound support will be enabled for the new virtual machine. Note that the virtual
3603	machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
3604	may be different from the virtual soundcard expected by the appliance.
3605	</li>
3606	</ul>
3607
3608	</desc>
3609
3610	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3611	<desc></desc>
3612	</param>
3613
3614	<param name="aRefs" type="wstring" dir="out" safearray="yes">
3615	<desc></desc>
3616	</param>
3617
3618	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3619	<desc></desc>
3620	</param>
3621
3622	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
3623	<desc></desc>
3624	</param>
3625
3626	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3627	<desc></desc>
3628	</param>
3629
3630	</method>
3631
3632	<method name="getDescriptionByType">
3633	<desc>This is the same as <link to="#getDescription" /> except that you can specify which types
3634	should be returned.</desc>
3635
3636	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3637	<desc></desc>
3638	</param>
3639
3640	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3641	<desc></desc>
3642	</param>
3643
3644	<param name="aRefs" type="wstring" dir="out" safearray="yes">
3645	<desc></desc>
3646	</param>
3647
3648	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3649	<desc></desc>
3650	</param>
3651
3652	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
3653	<desc></desc>
3654	</param>
3655
3656	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3657	<desc></desc>
3658	</param>
3659
3660	</method>
3661
3662	<method name="getValuesByType">
3663	<desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
3664	value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
3665	values.</desc>
3666
3667	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3668	<desc></desc>
3669	</param>
3670
3671	<param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
3672	<desc></desc>
3673	</param>
3674
3675	<param name="aValues" type="wstring" dir="return" safearray="yes">
3676	<desc></desc>
3677	</param>
3678
3679	</method>
3680
3681	<method name="setFinalValues">
3682	<desc>
3683	This method allows the appliance's user to change the configuration for the virtual
3684	system descriptions. For each array item returned from <link to="#getDescription" />,
3685	you must pass in one boolean value and one configuration value.
3686
3687	Each item in the boolean array determines whether the particular configuration item
3688	should be enabled.
3689	You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
3690	HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
3691	and SoundCard.
3692
3693	For the "vbox" and "extra configuration" values, if you pass in the same arrays
3694	as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription(),
3695	the configuration remains unchanged. Please see the documentation for getDescription()
3696	for valid configuration values for the individual array item types. If the
3697	corresponding item in the aEnabled array is @c false, the configuration value is ignored.
3698	</desc>
3699
3700	<param name="aEnabled" type="boolean" dir="in" safearray="yes">
3701	<desc></desc>
3702	</param>
3703
3704	<param name="aVBoxValues" type="wstring" dir="in" safearray="yes">
3705	<desc></desc>
3706	</param>
3707
3708	<param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
3709	<desc></desc>
3710	</param>
3711	</method>
3712
3713	<method name="addDescription">
3714	<desc>
3715	This method adds an additional description entry to the stack of already
3716	available descriptions for this virtual system. This is handy for writing
3717	values which aren't directly supported by VirtualBox. One example would
3718	be the License type of <link to="VirtualSystemDescriptionType" />.
3719	</desc>
3720
3721	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3722	<desc></desc>
3723	</param>
3724
3725	<param name="aVBoxValue" type="wstring" dir="in">
3726	<desc></desc>
3727	</param>
3728
3729	<param name="aExtraConfigValue" type="wstring" dir="in">
3730	<desc></desc>
3731	</param>
3732	</method>
3733	</interface>
3734
3735
3736	<!--
3737	// IMachine
3738	/////////////////////////////////////////////////////////////////////////
3739	-->
3740
3741	<interface
3742	name="IInternalMachineControl" extends="$unknown"
3743	uuid="57e9a280-8d57-4331-aa31-f009f5194f52"
3744	internal="yes"
3745	wsmap="suppress"
3746	>
3747	<method name="setRemoveSavedState">
3748	<desc>
3749	Updates the flag whether saved state is removed on a machine state
3750	change from Saved to PoweredOff.
3751	</desc>
3752	<param name="aRemove" type="boolean" dir="in"/>
3753	</method>
3754
3755	<method name="updateState">
3756	<desc>
3757	Updates the VM state.
3758	<note>
3759	This operation will also update the settings file with
3760	the correct information about the saved state file
3761	and delete this file from disk when appropriate.
3762	</note>
3763	</desc>
3764	<param name="state" type="MachineState" dir="in"/>
3765	</method>
3766
3767	<method name="getIPCId">
3768	<param name="id" type="wstring" dir="return"/>
3769	</method>
3770
3771	<method name="setPowerUpInfo">
3772	<desc>
3773	Transfers success (@c null) or error information for this session.
3774	This method updates the progress object to signal completion of the
3775	<link to="IVirtualBox::openRemoteSession"/> method if appropriate,
3776	which means that the progress object returned by
3777	<link to="IConsole::powerUp"/>.
3778	</desc>
3779	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
3780	</method>
3781
3782	<method name="runUSBDeviceFilters">
3783	<desc>
3784	Asks the server to run USB devices filters of the associated
3785	machine against the given USB device and tell if there is
3786	a match.
3787	<note>
3788	Intended to be used only for remote USB devices. Local
3789	ones don't require to call this method (this is done
3790	implicitly by the Host and USBProxyService).
3791	</note>
3792	</desc>
3793	<param name="device" type="IUSBDevice" dir="in"/>
3794	<param name="matched" type="boolean" dir="out"/>
3795	<param name="maskedInterfaces" type="unsigned long" dir="out"/>
3796	</method>
3797
3798	<method name="captureUSBDevice">
3799	<desc>
3800	Requests a capture of the given host USB device.
3801	When the request is completed, the VM process will
3802	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3803	notification.
3804	</desc>
3805	<param name="id" type="uuid" mod="string" dir="in"/>
3806	</method>
3807
3808	<method name="detachUSBDevice">
3809	<desc>
3810	Notification that a VM is going to detach (@a done = @c false) or has
3811	already detached (@a done = @c true) the given USB device.
3812	When the @a done = @c true request is completed, the VM process will
3813	get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3814	notification.
3815	<note>
3816	In the @a done = @c true case, the server must run its own filters
3817	and filters of all VMs but this one on the detached device
3818	as if it were just attached to the host computer.
3819	</note>
3820	</desc>
3821	<param name="id" type="uuid" mod="string" dir="in"/>
3822	<param name="done" type="boolean" dir="in"/>
3823	</method>
3824
3825	<method name="autoCaptureUSBDevices">
3826	<desc>
3827	Requests a capture all matching USB devices attached to the host.
3828	When the request is completed, the VM process will
3829	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3830	notification per every captured device.
3831	</desc>
3832	</method>
3833
3834	<method name="detachAllUSBDevices">
3835	<desc>
3836	Notification that a VM that is being powered down. The done
3837	parameter indicates whether which stage of the power down
3838	we're at. When @a done = @c false the VM is announcing its
3839	intentions, while when @a done = @c true the VM is reporting
3840	what it has done.
3841	<note>
3842	In the @a done = @c true case, the server must run its own filters
3843	and filters of all VMs but this one on all detach devices as
3844	if they were just attached to the host computer.
3845	</note>
3846	</desc>
3847	<param name="done" type="boolean" dir="in"/>
3848	</method>
3849
3850	<method name="onSessionEnd">
3851	<desc>
3852	Triggered by the given session object when the session is about
3853	to close normally.
3854	</desc>
3855	<param name="session" type="ISession" dir="in">
3856	<desc>Session that is being closed</desc>
3857	</param>
3858	<param name="progress" type="IProgress" dir="return">
3859	<desc>
3860	Used to wait until the corresponding machine is actually
3861	dissociated from the given session on the server.
3862	Returned only when this session is a direct one.
3863	</desc>
3864	</param>
3865	</method>
3866
3867	<method name="beginSavingState">
3868	<desc>
3869	Called by the VM process to inform the server it wants to
3870	save the current state and stop the VM execution.
3871	</desc>
3872	<param name="progress" type="IProgress" dir="in">
3873	<desc>
3874	Progress object created by the VM process to wait until
3875	the state is saved.
3876	</desc>
3877	</param>
3878	<param name="stateFilePath" type="wstring" dir="out">
3879	<desc>
3880	File path the VM process must save the execution state to.
3881	</desc>
3882	</param>
3883	</method>
3884
3885	<method name="endSavingState">
3886	<desc>
3887	Called by the VM process to inform the server that saving
3888	the state previously requested by #beginSavingState is either
3889	successfully finished or there was a failure.
3890
3891	<result name="VBOX_E_FILE_ERROR">
3892	Settings file not accessible.
3893	</result>
3894	<result name="VBOX_E_XML_ERROR">
3895	Could not parse the settings file.
3896	</result>
3897
3898	</desc>
3899
3900	<param name="success" type="boolean" dir="in">
3901	<desc>@c true to indicate success and @c false otherwise.
3902	</desc>
3903	</param>
3904	</method>
3905
3906	<method name="adoptSavedState">
3907	<desc>
3908	Gets called by IConsole::adoptSavedState.
3909	<result name="VBOX_E_FILE_ERROR">
3910	Invalid saved state file path.
3911	</result>
3912	</desc>
3913	<param name="savedStateFile" type="wstring" dir="in">
3914	<desc>Path to the saved state file to adopt.</desc>
3915	</param>
3916	</method>
3917
3918	<method name="beginTakingSnapshot">
3919	<desc>
3920	Called from the VM process to request from the server to perform the
3921	server-side actions of creating a snapshot (creating differencing images
3922	and the snapshot object).
3923
3924	<result name="VBOX_E_FILE_ERROR">
3925	Settings file not accessible.
3926	</result>
3927	<result name="VBOX_E_XML_ERROR">
3928	Could not parse the settings file.
3929	</result>
3930	</desc>
3931	<param name="initiator" type="IConsole" dir="in">
3932	<desc>The console object that initiated this call.</desc>
3933	</param>
3934	<param name="name" type="wstring" dir="in">
3935	<desc>Snapshot name.</desc>
3936	</param>
3937	<param name="description" type="wstring" dir="in">
3938	<desc>Snapshot description.</desc>
3939	</param>
3940	<param name="consoleProgress" type="IProgress" dir="in">
3941	<desc>
3942	Progress object created by the VM process tracking the
3943	snapshot's progress. This has the following sub-operations:
3944	<ul>
3945	<li>setting up (weight 1);</li>
3946	<li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
3947	<li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
3948	<li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
3949	<li>finishing up (weight 1)</li>
3950	</ul>
3951	</desc>
3952	</param>
3953	<param name="fTakingSnapshotOnline" type="boolean" dir="in">
3954	<desc>
3955	Whether this is an online snapshot (i.e. the machine is running).
3956	</desc>
3957	</param>
3958	<param name="stateFilePath" type="wstring" dir="out">
3959	<desc>
3960	File path the VM process must save the execution state to.
3961	</desc>
3962	</param>
3963	</method>
3964
3965	<method name="endTakingSnapshot">
3966	<desc>
3967	Called by the VM process to inform the server that the snapshot
3968	previously requested by #beginTakingSnapshot is either
3969	successfully taken or there was a failure.
3970	</desc>
3971
3972	<param name="success" type="boolean" dir="in">
3973	<desc>@c true to indicate success and @c false otherwise</desc>
3974	</param>
3975	</method>
3976
3977	<method name="deleteSnapshot">
3978	<desc>
3979	Gets called by IConsole::deleteSnapshot.
3980	<result name="VBOX_E_INVALID_OBJECT_STATE">
3981	Snapshot has more than one child snapshot.
3982	</result>
3983	</desc>
3984	<param name="initiator" type="IConsole" dir="in">
3985	<desc>The console object that initiated this call.</desc>
3986	</param>
3987	<param name="id" type="uuid" mod="string" dir="in">
3988	<desc>UUID of the snapshot to delete.</desc>
3989	</param>
3990	<param name="machineState" type="MachineState" dir="out">
3991	<desc>New machine state after this operation is started.</desc>
3992	</param>
3993	<param name="progress" type="IProgress" dir="return">
3994	<desc>Progress object to track the operation completion.</desc>
3995	</param>
3996	</method>
3997
3998	<method name="finishOnlineMergeMedium">
3999	<desc>
4000	Gets called by IConsole::onlineMergeMedium.
4001	</desc>
4002	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
4003	<desc>The medium attachment which needs to be cleaned up.</desc>
4004	</param>
4005	<param name="source" type="IMedium" dir="in">
4006	<desc>Merge source medium.</desc>
4007	</param>
4008	<param name="target" type="IMedium" dir="in">
4009	<desc>Merge target medium.</desc>
4010	</param>
4011	<param name="mergeForward" type="boolean" dir="in">
4012	<desc>Merge direction.</desc>
4013	</param>
4014	<param name="parentForTarget" type="IMedium" dir="in">
4015	<desc>For forward merges: new parent for target medium.</desc>
4016	</param>
4017	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
4018	<desc>For backward merges: list of media which need their parent UUID
4019	updated.</desc>
4020	</param>
4021	</method>
4022
4023	<method name="restoreSnapshot">
4024	<desc>
4025	Gets called by IConsole::RestoreSnapshot.
4026	</desc>
4027	<param name="initiator" type="IConsole" dir="in">
4028	<desc>The console object that initiated this call.</desc>
4029	</param>
4030	<param name="snapshot" type="ISnapshot" dir="in">
4031	<desc>The snapshot to restore the VM state from.</desc>
4032	</param>
4033	<param name="machineState" type="MachineState" dir="out">
4034	<desc>New machine state after this operation is started.</desc>
4035	</param>
4036	<param name="progress" type="IProgress" dir="return">
4037	<desc>Progress object to track the operation completion.</desc>
4038	</param>
4039	</method>
4040
4041	<method name="pullGuestProperties">
4042	<desc>
4043	Get the list of the guest properties matching a set of patterns along
4044	with their values, time stamps and flags and give responsibility for
4045	managing properties to the console.
4046	</desc>
4047	<param name="name" type="wstring" dir="out" safearray="yes">
4048	<desc>
4049	The names of the properties returned.
4050	</desc>
4051	</param>
4052	<param name="value" type="wstring" dir="out" safearray="yes">
4053	<desc>
4054	The values of the properties returned. The array entries match the
4055	corresponding entries in the @a name array.
4056	</desc>
4057	</param>
4058	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
4059	<desc>
4060	The time stamps of the properties returned. The array entries match
4061	the corresponding entries in the @a name array.
4062	</desc>
4063	</param>
4064	<param name="flags" type="wstring" dir="out" safearray="yes">
4065	<desc>
4066	The flags of the properties returned. The array entries match the
4067	corresponding entries in the @a name array.
4068	</desc>
4069	</param>
4070	</method>
4071
4072	<method name="pushGuestProperty">
4073	<desc>
4074	Update a single guest property in IMachine.
4075	</desc>
4076	<param name="name" type="wstring" dir="in">
4077	<desc>
4078	The name of the property to be updated.
4079	</desc>
4080	</param>
4081	<param name="value" type="wstring" dir="in">
4082	<desc>
4083	The value of the property.
4084	</desc>
4085	</param>
4086	<param name="timestamp" type="unsigned long long" dir="in">
4087	<desc>
4088	The timestamp of the property.
4089	</desc>
4090	</param>
4091	<param name="flags" type="wstring" dir="in">
4092	<desc>
4093	The flags of the property.
4094	</desc>
4095	</param>
4096	</method>
4097
4098	<method name="lockMedia">
4099	<desc>
4100	Locks all media attached to the machine for writing and parents of
4101	attached differencing media (if any) for reading. This operation is
4102	atomic so that if it fails no media is actually locked.
4103
4104	This method is intended to be called when the machine is in Starting or
4105	Restoring state. The locked media will be automatically unlocked when
4106	the machine is powered off or crashed.
4107	</desc>
4108	</method>
4109	<method name="unlockMedia">
4110	<desc>
4111	Unlocks all media previously locked using
4112	<link to="IInternalMachineControl::lockMedia"/>.
4113
4114	This method is intended to be used with teleportation so that it is
4115	possible to teleport between processes on the same machine.
4116	</desc>
4117	</method>
4118	</interface>
4119
4120	<interface
4121	name="IBIOSSettings" extends="$unknown"
4122	uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
4123	wsmap="managed"
4124	>
4125	<desc>
4126	The IBIOSSettings interface represents BIOS settings of the virtual
4127	machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
4128	</desc>
4129	<attribute name="logoFadeIn" type="boolean">
4130	<desc>Fade in flag for BIOS logo animation.</desc>
4131	</attribute>
4132
4133	<attribute name="logoFadeOut" type="boolean">
4134	<desc>Fade out flag for BIOS logo animation.</desc>
4135	</attribute>
4136
4137	<attribute name="logoDisplayTime" type="unsigned long">
4138	<desc>BIOS logo display time in milliseconds (0 = default).</desc>
4139	</attribute>
4140
4141	<attribute name="logoImagePath" type="wstring">
4142	<desc>
4143	Local file system path for external BIOS splash image. Empty string
4144	means the default image is shown on boot.
4145	</desc>
4146	</attribute>
4147
4148	<attribute name="bootMenuMode" type="BIOSBootMenuMode">
4149	<desc>Mode of the BIOS boot device menu.</desc>
4150	</attribute>
4151
4152	<attribute name="ACPIEnabled" type="boolean">
4153	<desc>ACPI support flag.</desc>
4154	</attribute>
4155
4156	<attribute name="IOAPICEnabled" type="boolean">
4157	<desc>
4158	IO APIC support flag. If set, VirtualBox will provide an IO APIC
4159	and support IRQs above 15.
4160	</desc>
4161	</attribute>
4162
4163	<attribute name="timeOffset" type="long long">
4164	<desc>
4165	Offset in milliseconds from the host system time. This allows for
4166	guests running with a different system date/time than the host.
4167	It is equivalent to setting the system date/time in the BIOS except
4168	it is not an absolute value but a relative one. Guest Additions
4169	time synchronization honors this offset.
4170	</desc>
4171	</attribute>
4172
4173	<attribute name="PXEDebugEnabled" type="boolean">
4174	<desc>
4175	PXE debug logging flag. If set, VirtualBox will write extensive
4176	PXE trace information to the release log.
4177	</desc>
4178	</attribute>
4179
4180	</interface>
4181
4182	<interface
4183	name="IMachine" extends="$unknown"
4184	uuid="b8a9324a-1042-4c78-aff6-9d1c2bfd8cd0"
4185	wsmap="managed"
4186	>
4187	<desc>
4188	The IMachine interface represents a virtual machine, or guest, created
4189	in VirtualBox.
4190
4191	This interface is used in two contexts. First of all, a collection of
4192	objects implementing this interface is stored in the
4193	<link to="IVirtualBox::machines"/> attribute which lists all the virtual
4194	machines that are currently registered with this VirtualBox
4195	installation. Also, once a session has been opened for the given virtual
4196	machine (e.g. the virtual machine is running), the machine object
4197	associated with the open session can be queried from the session object;
4198	see <link to="ISession"/> for details.
4199
4200	The main role of this interface is to expose the settings of the virtual
4201	machine and provide methods to change various aspects of the virtual
4202	machine's configuration. For machine objects stored in the
4203	<link to="IVirtualBox::machines"/> collection, all attributes are
4204	read-only unless explicitly stated otherwise in individual attribute
4205	and method descriptions. In order to change a machine setting, a session
4206	for this machine must be opened using one of
4207	<link to="IVirtualBox::openSession"/>,
4208	<link to="IVirtualBox::openRemoteSession"/> or
4209	<link to="IVirtualBox::openExistingSession"/> methods. After the
4210	session has been successfully opened, a mutable machine object needs to
4211	be queried from the session object and then the desired settings changes
4212	can be applied to the returned object using IMachine attributes and
4213	methods. See the <link to="ISession"/> interface description for more
4214	information about sessions.
4215
4216	Note that IMachine does not provide methods to control virtual machine
4217	execution (such as start the machine, or power it down) -- these methods
4218	are grouped in a separate interface called <link to="IConsole" />.
4219
4220	<see>ISession, IConsole</see>
4221	</desc>
4222
4223	<attribute name="parent" type="IVirtualBox" readonly="yes">
4224	<desc>Associated parent object.</desc>
4225	</attribute>
4226
4227	<attribute name="accessible" type="boolean" readonly="yes">
4228	<desc>
4229	Whether this virtual machine is currently accessible or not.
4230
4231	A machine is always deemed accessible unless it is registered <i>and</i>
4232	its settings file cannot be read or parsed (either because the file itself
4233	is unavailable or has invalid XML contents).
4234
4235	Every time this property is read, the accessibility state of
4236	this machine is re-evaluated. If the returned value is @c false,
4237	the <link to="#accessError"/> property may be used to get the
4238	detailed error information describing the reason of
4239	inaccessibility, including XML error messages.
4240
4241	When the machine is inaccessible, only the following properties
4242	can be used on it:
4243	<ul>
4244	<li><link to="#parent"/></li>
4245	<li><link to="#id"/></li>
4246	<li><link to="#settingsFilePath"/></li>
4247	<li><link to="#accessible"/></li>
4248	<li><link to="#accessError"/></li>
4249	</ul>
4250
4251	An attempt to access any other property or method will return
4252	an error.
4253
4254	The only possible action you can perform on an inaccessible
4255	machine is to unregister it using the
4256	<link to="IVirtualBox::unregisterMachine"/> call (or, to check
4257	for the accessibility state once more by querying this
4258	property).
4259
4260	<note>
4261	In the current implementation, once this property returns
4262	@c true, the machine will never become inaccessible
4263	later, even if its settings file cannot be successfully
4264	read/written any more (at least, until the VirtualBox
4265	server is restarted). This limitation may be removed in
4266	future releases.
4267	</note>
4268	</desc>
4269	</attribute>
4270
4271	<attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
4272	<desc>
4273	Error information describing the reason of machine
4274	inaccessibility.
4275
4276	Reading this property is only valid after the last call to
4277	<link to="#accessible"/> returned @c false (i.e. the
4278	machine is currently unaccessible). Otherwise, a @c null
4279	IVirtualBoxErrorInfo object will be returned.
4280	</desc>
4281	</attribute>
4282
4283	<attribute name="name" type="wstring">
4284	<desc>
4285	Name of the virtual machine.
4286
4287	Besides being used for human-readable identification purposes
4288	everywhere in VirtualBox, the virtual machine name is also used
4289	as a name of the machine's settings file and as a name of the
4290	subdirectory this settings file resides in. Thus, every time you
4291	change the value of this property, the settings file will be
4292	renamed once you call <link to="#saveSettings"/> to confirm the
4293	change. The containing subdirectory will be also renamed, but
4294	only if it has exactly the same name as the settings file
4295	itself prior to changing this property (for backward compatibility
4296	with previous API releases). The above implies the following
4297	limitations:
4298	<ul>
4299	<li>The machine name cannot be empty.</li>
4300	<li>The machine name can contain only characters that are valid
4301	file name characters according to the rules of the file
4302	system used to store VirtualBox configuration.</li>
4303	<li>You cannot have two or more machines with the same name
4304	if they use the same subdirectory for storing the machine
4305	settings files.</li>
4306	<li>You cannot change the name of the machine if it is running,
4307	or if any file in the directory containing the settings file
4308	is being used by another running machine or by any other
4309	process in the host operating system at a time when
4310	<link to="#saveSettings"/> is called.
4311	</li>
4312	</ul>
4313	If any of the above limitations are hit, <link to="#saveSettings"/>
4314	will return an appropriate error message explaining the exact
4315	reason and the changes you made to this machine will not be
4316	saved.
4317	<note>
4318	For "legacy" machines created using the
4319	<link to="IVirtualBox::createLegacyMachine"/> call,
4320	the above naming limitations do not apply because the
4321	machine name does not affect the settings file name.
4322	The settings file name remains the same as it was specified
4323	during machine creation and never changes.
4324	</note>
4325	</desc>
4326	</attribute>
4327
4328	<attribute name="description" type="wstring">
4329	<desc>
4330	Description of the virtual machine.
4331
4332	The description attribute can contain any text and is
4333	typically used to describe the hardware and software
4334	configuration of the virtual machine in detail (i.e. network
4335	settings, versions of the installed software and so on).
4336	</desc>
4337	</attribute>
4338
4339	<attribute name="id" type="uuid" mod="string" readonly="yes">
4340	<desc>UUID of the virtual machine.</desc>
4341	</attribute>
4342
4343	<attribute name="OSTypeId" type="wstring">
4344	<desc>
4345	User-defined identifier of the Guest OS type.
4346	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
4347	an IGuestOSType object representing details about the given
4348	Guest OS type.
4349	<note>
4350	This value may differ from the value returned by
4351	<link to="IGuest::OSTypeId"/> if Guest Additions are
4352	installed to the guest OS.
4353	</note>
4354	</desc>
4355	</attribute>
4356
4357	<attribute name="HardwareVersion" type="wstring">
4358	<desc>Hardware version identifier. Internal use only for now.</desc>
4359	</attribute>
4360
4361	<attribute name="hardwareUUID" type="uuid" mod="string">
4362	<desc>
4363	The UUID presented to the guest via memory tables, hardware and guest
4364	properties. For most VMs this is the same as the @a id, but for VMs
4365	which have been cloned or teleported it may be the same as the source
4366	VM. This latter is because the guest shouldn't notice that it was
4367	cloned or teleported.
4368	</desc>
4369	</attribute>
4370
4371	<attribute name="CPUCount" type="unsigned long">
4372	<desc>Number of virtual CPUs in the VM.</desc>
4373	</attribute>
4374
4375	<attribute name="CPUHotPlugEnabled" type="boolean">
4376	<desc>
4377	This setting determines whether VirtualBox allows CPU
4378	hotplugging for this machine.</desc>
4379	</attribute>
4380
4381	<attribute name="memorySize" type="unsigned long">
4382	<desc>System memory size in megabytes.</desc>
4383	</attribute>
4384
4385	<attribute name="memoryBalloonSize" type="unsigned long">
4386	<desc>Memory balloon size in megabytes.</desc>
4387	</attribute>
4388
4389	<attribute name="VRAMSize" type="unsigned long">
4390	<desc>Video memory size in megabytes.</desc>
4391	</attribute>
4392
4393	<attribute name="accelerate3DEnabled" type="boolean" default="false">
4394	<desc>
4395	This setting determines whether VirtualBox allows this machine to make
4396	use of the 3D graphics support available on the host.</desc>
4397	</attribute>
4398
4399	<attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
4400	<desc>
4401	This setting determines whether VirtualBox allows this machine to make
4402	use of the 2D video acceleration support available on the host.</desc>
4403	</attribute>
4404
4405	<attribute name="monitorCount" type="unsigned long">
4406	<desc>
4407	Number of virtual monitors.
4408	<note>
4409	Only effective on Windows XP and later guests with
4410	Guest Additions installed.
4411	</note>
4412	</desc>
4413	</attribute>
4414
4415	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
4416	<desc>Object containing all BIOS settings.</desc>
4417	</attribute>
4418
4419	<attribute name="firmwareType" type="FirmwareType">
4420	<desc>Type of firmware (such as legacy BIOS or EFI), used for initial
4421	bootstrap in this VM.</desc>
4422	</attribute>
4423
4424	<attribute name="pointingHidType" type="PointingHidType">
4425	<desc>Type of pointing HID (such as mouse or tablet) used in this VM.
4426	The default is typically "PS2Mouse" but can vary depending on the
4427	requirements of the guest operating system.</desc>
4428	</attribute>
4429
4430	<attribute name="keyboardHidType" type="KeyboardHidType">
4431	<desc>Type of keyboard HID used in this VM.
4432	The default is typically "PS2Keyboard" but can vary depending on the
4433	requirements of the guest operating system.</desc>
4434	</attribute>
4435
4436	<attribute name="hpetEnabled" type="boolean">
4437	<desc>This attribute controls if High Precision Event Timer (HPET) is
4438	enabled in this VM. Use this property if you want to provide guests
4439	with additional time source, or if guest requires HPET to function correctly.
4440	Default is false.</desc>
4441	</attribute>
4442
4443	<attribute name="snapshotFolder" type="wstring">
4444	<desc>
4445	Full path to the directory used to store snapshot data
4446	(differencing media and saved state files) of this machine.
4447
4448	The initial value of this property is
4449	<tt><</tt><link to="#settingsFilePath">
4450	path_to_settings_file</link><tt>>/<</tt>
4451	<link to="#id">machine_uuid</link>
4452	<tt>></tt>.
4453
4454	Currently, it is an error to try to change this property on
4455	a machine that has snapshots (because this would require to
4456	move possibly large files to a different location).
4457	A separate method will be available for this purpose later.
4458
4459	<note>
4460	Setting this property to @c null or to an empty string will restore
4461	the initial value.
4462	</note>
4463	<note>
4464	When setting this property, the specified path can be
4465	absolute (full path) or relative to the directory where the
4466	<link to="#settingsFilePath">machine settings file</link>
4467	is located. When reading this property, a full path is
4468	always returned.
4469	</note>
4470	<note>
4471	The specified path may not exist, it will be created
4472	when necessary.
4473	</note>
4474	</desc>
4475	</attribute>
4476
4477	<attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
4478	<desc>VRDP server object.</desc>
4479	</attribute>
4480
4481	<attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
4482	<desc>Array of media attached to this machine.</desc>
4483	</attribute>
4484
4485	<attribute name="USBController" type="IUSBController" readonly="yes">
4486	<desc>
4487	Associated USB controller object.
4488
4489	<note>
4490	If USB functionality is not available in the given edition of
4491	VirtualBox, this method will set the result code to @c E_NOTIMPL.
4492	</note>
4493	</desc>
4494	</attribute>
4495
4496	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
4497	<desc>Associated audio adapter, always present.</desc>
4498	</attribute>
4499
4500	<attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
4501	<desc>Array of storage controllers attached to this machine.</desc>
4502	</attribute>
4503
4504	<attribute name="settingsFilePath" type="wstring" readonly="yes">
4505	<desc>
4506	Full name of the file containing machine settings data.
4507	</desc>
4508	</attribute>
4509
4510	<attribute name="settingsModified" type="boolean" readonly="yes">
4511	<desc>
4512	Whether the settings of this machine have been modified
4513	(but neither yet saved nor discarded).
4514	<note>
4515	Reading this property is only valid on instances returned
4516	by <link to="ISession::machine"/> and on new machines
4517	created by <link to="IVirtualBox::createMachine"/> or opened
4518	by <link to="IVirtualBox::openMachine"/> but not
4519	yet registered, or on unregistered machines after calling
4520	<link to="IVirtualBox::unregisterMachine"/>. For all other
4521	cases, the settings can never be modified.
4522	</note>
4523	<note>
4524	For newly created unregistered machines, the value of this
4525	property is always @c true until <link to="#saveSettings"/>
4526	is called (no matter if any machine settings have been
4527	changed after the creation or not). For opened machines
4528	the value is set to @c false (and then follows to normal rules).
4529	</note>
4530	</desc>
4531	</attribute>
4532
4533	<attribute name="sessionState" type="SessionState" readonly="yes">
4534	<desc>Current session state for this machine.</desc>
4535	</attribute>
4536
4537	<attribute name="sessionType" type="wstring" readonly="yes">
4538	<desc>
4539	Type of the session. If <link to="#sessionState"/> is
4540	SessionSpawning or SessionOpen, this attribute contains the
4541	same value as passed to the
4542	<link to="IVirtualBox::openRemoteSession"/> method in the
4543	@a type parameter. If the session was opened directly using
4544	<link to="IVirtualBox::openSession"/>, or if
4545	<link to="#sessionState"/> is SessionClosed, the value of this
4546	attribute is an empty string.
4547	</desc>
4548	</attribute>
4549
4550	<attribute name="sessionPid" type="unsigned long" readonly="yes">
4551	<desc>
4552	Identifier of the session process. This attribute contains the
4553	platform-dependent identifier of the process that has opened a
4554	direct session for this machine using the
4555	<link to="IVirtualBox::openSession"/> call. The returned value
4556	is only valid if <link to="#sessionState"/> is SessionOpen or
4557	SessionClosing (i.e. a session is currently open or being
4558	closed) by the time this property is read.
4559	</desc>
4560	</attribute>
4561
4562	<attribute name="state" type="MachineState" readonly="yes">
4563	<desc>Current execution state of this machine.</desc>
4564	</attribute>
4565
4566	<attribute name="lastStateChange" type="long long" readonly="yes">
4567	<desc>
4568	Time stamp of the last execution state change,
4569	in milliseconds since 1970-01-01 UTC.
4570	</desc>
4571	</attribute>
4572
4573	<attribute name="stateFilePath" type="wstring" readonly="yes">
4574	<desc>
4575	Full path to the file that stores the execution state of
4576	the machine when it is in the <link to="MachineState_Saved"/> state.
4577	<note>
4578	When the machine is not in the Saved state, this attribute is
4579	an empty string.
4580	</note>
4581	</desc>
4582	</attribute>
4583
4584	<attribute name="logFolder" type="wstring" readonly="yes">
4585	<desc>
4586	Full path to the folder that stores a set of rotated log files
4587	recorded during machine execution. The most recent log file is
4588	named <tt>VBox.log</tt>, the previous log file is
4589	named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4590	in the current version).
4591	</desc>
4592	</attribute>
4593
4594	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4595	<desc>
4596	Current snapshot of this machine. This is @c null if the machine
4597	currently has no snapshots. If it is not @c null, then it was
4598	set by one of <link to="Console::takeSnapshot" />,
4599	<link to="Console::deleteSnapshot" />
4600	or <link to="Console::restoreSnapshot" />, depending on which
4601	was called last. See <link to="ISnapshot"/> for details.
4602	</desc>
4603	</attribute>
4604
4605	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
4606	<desc>
4607	Number of snapshots taken on this machine. Zero means the
4608	machine doesn't have any snapshots.
4609	</desc>
4610	</attribute>
4611
4612	<attribute name="currentStateModified" type="boolean" readonly="yes">
4613	<desc>
4614	Returns @c true if the current state of the machine is not
4615	identical to the state stored in the current snapshot.
4616
4617	The current state is identical to the current snapshot only
4618	directly after one of the following calls are made:
4619
4620	<ul>
4621	<li><link to="IConsole::restoreSnapshot"/>
4622	</li>
4623	<li><link to="IConsole::takeSnapshot"/> (issued on a
4624	"powered off" or "saved" machine, for which
4625	<link to="#settingsModified"/> returns @c false)
4626	</li>
4627	<li><link to="IMachine::setCurrentSnapshot"/>
4628	</li>
4629	</ul>
4630
4631	The current state remains identical until one of the following
4632	happens:
4633	<ul>
4634	<li>settings of the machine are changed</li>
4635	<li>the saved state is deleted</li>
4636	<li>the current snapshot is deleted</li>
4637	<li>an attempt to execute the machine is made</li>
4638	</ul>
4639
4640	<note>
4641	For machines that don't have snapshots, this property is
4642	always @c false.
4643	</note>
4644	</desc>
4645	</attribute>
4646
4647	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4648	<desc>
4649	Collection of shared folders for this machine (permanent shared
4650	folders). These folders are shared automatically at machine startup
4651	and available only to the guest OS installed within this machine.
4652
4653	New shared folders are added to the collection using
4654	<link to="#createSharedFolder"/>. Existing shared folders can be
4655	removed using <link to="#removeSharedFolder"/>.
4656	</desc>
4657	</attribute>
4658
4659	<attribute name="clipboardMode" type="ClipboardMode">
4660	<desc>
4661	Synchronization mode between the host OS clipboard
4662	and the guest OS clipboard.
4663	</desc>
4664	</attribute>
4665
4666	<attribute name="guestPropertyNotificationPatterns" type="wstring">
4667	<desc>
4668	A comma-separated list of simple glob patterns. Changes to guest
4669	properties whose name matches one of the patterns will generate an
4670	<link to="IVirtualBoxCallback::onGuestPropertyChange"/> signal.
4671	</desc>
4672	</attribute>
4673
4674	<attribute name="teleporterEnabled" type="boolean">
4675	<desc>
4676	When set to @a true, the virtual machine becomes a target teleporter
4677	the next time it is powered on. This can only set to @a true when the
4678	VM is in the @a PoweredOff or @a Aborted state.
4679
4680	<!-- This property is automatically set to @a false when the VM is powered
4681	on. (bird: This doesn't work yet ) -->
4682	</desc>
4683	</attribute>
4684
4685	<attribute name="teleporterPort" type="unsigned long">
4686	<desc>
4687	The TCP port the target teleporter will listen for incoming
4688	teleportations on.
4689
4690	0 means the port is automatically selected upon power on. The actual
4691	value can be read from this property while the machine is waiting for
4692	incoming teleportations.
4693	</desc>
4694	</attribute>
4695
4696	<attribute name="teleporterAddress" type="wstring">
4697	<desc>
4698	The address the target teleporter will listen on. If set to an empty
4699	string, it will listen on all addresses.
4700	</desc>
4701	</attribute>
4702
4703	<attribute name="teleporterPassword" type="wstring">
4704	<desc>
4705	The password the to check for on the target teleporter. This is just a
4706	very basic measure to prevent simple hacks and operators accidentally
4707	beaming a virtual machine to the wrong place.
4708	</desc>
4709	</attribute>
4710
4711	<attribute name="RTCUseUTC" type="boolean">
4712	<desc>
4713	When set to @a true, the RTC device of the virtual machine will run
4714	in UTC time, otherwise in local time. Especially Unix guests prefer
4715	the time in UTC.
4716	</desc>
4717	</attribute>
4718
4719	<attribute name="ioMgr" type="IoMgrType">
4720	<desc>
4721	Selects the I/O manager to use for the virtual machine.
4722	</desc>
4723	</attribute>
4724
4725	<attribute name="ioBackend" type="IoBackendType">
4726	<desc>
4727	Selects the I/O backend to use for the virtual machine.
4728	</desc>
4729	</attribute>
4730
4731	<attribute name="ioCacheEnabled" type="boolean">
4732	<desc>
4733	When set to @a true, the builtin I/O cache of the virtual machine
4734	will be enabled.
4735	</desc>
4736	</attribute>
4737
4738	<attribute name="ioCacheSize" type="unsigned long">
4739	<desc>
4740	Maximum size of the I/O cache in MB.
4741	</desc>
4742	</attribute>
4743
4744	<attribute name="ioBandwidthMax" type="unsigned long">
4745	<desc>
4746	The maximum number of MB the VM is allowed to transfer per second.
4747	0 means unlimited bandwidth.
4748	</desc>
4749	</attribute>
4750
4751	<method name="setBootOrder">
4752	<desc>
4753	Puts the given device to the specified position in
4754	the boot order.
4755
4756	To indicate that no device is associated with the given position,
4757	<link to="DeviceType_Null"/> should be used.
4758
4759	@todo setHardDiskBootOrder(), setNetworkBootOrder()
4760
4761	<result name="E_INVALIDARG">
4762	Boot @a position out of range.
4763	</result>
4764	<result name="E_NOTIMPL">
4765	Booting from USB @a device currently not supported.
4766	</result>
4767
4768	</desc>
4769	<param name="position" type="unsigned long" dir="in">
4770	<desc>
4771	Position in the boot order (@c 1 to the total number of
4772	devices the machine can boot from, as returned by
4773	<link to="ISystemProperties::maxBootPosition"/>).
4774	</desc>
4775	</param>
4776	<param name="device" type="DeviceType" dir="in">
4777	<desc>
4778	The type of the device used to boot at the given position.
4779	</desc>
4780	</param>
4781	</method>
4782
4783	<method name="getBootOrder" const="yes">
4784	<desc>
4785	Returns the device type that occupies the specified
4786	position in the boot order.
4787
4788	@todo [remove?]
4789	If the machine can have more than one device of the returned type
4790	(such as hard disks), then a separate method should be used to
4791	retrieve the individual device that occupies the given position.
4792
4793	If here are no devices at the given position, then
4794	<link to="DeviceType_Null"/> is returned.
4795
4796	@todo getHardDiskBootOrder(), getNetworkBootOrder()
4797
4798	<result name="E_INVALIDARG">
4799	Boot @a position out of range.
4800	</result>
4801
4802	</desc>
4803	<param name="position" type="unsigned long" dir="in">
4804	<desc>
4805	Position in the boot order (@c 1 to the total number of
4806	devices the machine can boot from, as returned by
4807	<link to="ISystemProperties::maxBootPosition"/>).
4808	</desc>
4809	</param>
4810	<param name="device" type="DeviceType" dir="return">
4811	<desc>
4812	Device at the given position.
4813	</desc>
4814	</param>
4815	</method>
4816
4817	<method name="attachDevice">
4818	<desc>
4819	Attaches a device and optionally mounts a medium to the given storage
4820	controller (<link to="IStorageController" />, identified by @a name),
4821	at the indicated port and device.
4822
4823	This method is intended for managing storage devices in general (it works
4824	for both fixed and removable media). For storage devices supporting removable
4825	media (such as DVDs and floppies), you can also use <link to="IMedium::mountMedium"/>
4826	for changing the media while the machine is running.
4827
4828	For the IDE bus, the @a controllerPort parameter can be either
4829	@c 0 or @c 1, to specify the primary or secondary IDE controller,
4830	respectively. For each of these, @a device can then be either @c 0 or @c 1,
4831	to specify the master or the slave device, respectively. (In the
4832	default configuration of virtual machines, the secondary master is
4833	used for a CD/DVD drive.)
4834
4835	For an SATA controller, @a controllerPort must be a number ranging
4836	from @c 0 to @c 29. For a SCSI controller, @a controllerPort must
4837	be a number ranging from @c 0 to @c 15.
4838
4839	For both SCSI and SATA, the @a device parameter is unused and must
4840	be @c 0.
4841
4842	For fixed media such as hard disks, the given medium identifier cannot
4843	be a zero UUID. It may be a zero UUID for removable media such as DVDs
4844	and floppies.
4845
4846	After calling this returns successfully, a new instance of
4847	<link to="IMediumAttachment"/> will appear in the machine's list of medium
4848	attachments (<link to="IMachine::mediumAttachments"/>).
4849
4850	The specified device slot must not have a device attached to it,
4851	or this method will fail.
4852
4853	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
4854	information about attaching media.
4855
4856	<note>
4857	You cannot attach a device to a running machine. Also, you cannot
4858	attach a device to a newly created machine until this machine's
4859	settings are saved to disk using <link to="#saveSettings"/>.
4860	</note>
4861	<note>
4862	If the medium is being attached indirectly, a new differencing medium
4863	will implicitly be created for it and attached instead. If the
4864	changes made to the machine settings (including this indirect
4865	attachment) are later cancelled using <link to="#discardSettings"/>,
4866	this implicitly created differencing medium will implicitly
4867	be deleted.
4868	</note>
4869
4870	<result name="E_INVALIDARG">
4871	SATA device, SATA port, IDE port or IDE slot out of range.
4872	</result>
4873	<result name="VBOX_E_INVALID_OBJECT_STATE">
4874	Attempt to attach medium to an unregistered virtual machine.
4875	</result>
4876	<result name="VBOX_E_INVALID_VM_STATE">
4877	Invalid machine state.
4878	</result>
4879	<result name="VBOX_E_OBJECT_IN_USE">
4880	Hard disk already attached to this or another virtual machine.
4881	</result>
4882
4883	</desc>
4884	<param name="name" type="wstring" dir="in">
4885	<desc>Name of the storage controller to attach the device to.</desc>
4886	</param>
4887	<param name="controllerPort" type="long" dir="in">
4888	<desc>Port to attach the device to.</desc>
4889	</param>
4890	<param name="device" type="long" dir="in">
4891	<desc>Device slot in the given port to attach the device to.</desc>
4892	</param>
4893	<param name="type" type="DeviceType" dir="in">
4894	<desc>Device type of the attached device.</desc>
4895	</param>
4896	<param name="id" type="uuid" mod="string" dir="in">
4897	<desc>UUID of the medium to mount. Zero UUID means do not mount any
4898	medium.</desc>
4899	</param>
4900	</method>
4901
4902	<method name="detachDevice">
4903	<desc>
4904	Detaches the device attached to a device slot of the specified bus.
4905
4906	Detaching the device from the virtual machine is deferred. This means
4907	that the medium remains associated with the machine when this method
4908	returns and gets actually de-associated only after a successful
4909	<link to="#saveSettings"/> call. See <link to="IMedium"/>
4910	for more detailed information about attaching media.
4911
4912	<note>
4913	You cannot detach a device from a running machine.
4914	</note>
4915	<note>
4916	Detaching differencing media implicitly created by <link
4917	to="#attachDevice"/> for the indirect attachment using this
4918	method will <b>not</b> implicitly delete them. The
4919	<link to="IMedium::deleteStorage"/> operation should be
4920	explicitly performed by the caller after the medium is successfully
4921	detached and the settings are saved with
4922	<link to="#saveSettings"/>, if it is the desired action.
4923	</note>
4924
4925	<result name="VBOX_E_INVALID_VM_STATE">
4926	Attempt to detach medium from a running virtual machine.
4927	</result>
4928	<result name="VBOX_E_OBJECT_NOT_FOUND">
4929	No medium attached to given slot/bus.
4930	</result>
4931	<result name="VBOX_E_NOT_SUPPORTED">
4932	Medium format does not support storage deletion.
4933	</result>
4934
4935	</desc>
4936	<param name="name" type="wstring" dir="in">
4937	<desc>Name of the storage controller to detach the medium from.</desc>
4938	</param>
4939	<param name="controllerPort" type="long" dir="in">
4940	<desc>Port number to detach the medium from.</desc>
4941	</param>
4942	<param name="device" type="long" dir="in">
4943	<desc>Device slot number to detach the medium from.</desc>
4944	</param>
4945	</method>
4946
4947	<method name="passthroughDevice">
4948	<desc>
4949	Sets the passthrough mode of an existing DVD device. Changing the
4950	setting while the VM is running is forbidden. The setting is only used
4951	if at VM start the device is configured as a host DVD drive, in all
4952	other cases it is ignored. The device must already exist; see
4953	<link to="IMachine::attachDevice"/> for how to attach a new device.
4954
4955	The @a controllerPort and @a device parameters specify the device slot and
4956	have have the same meaning as with <link to="IMachine::attachDevice" />.
4957
4958	<result name="E_INVALIDARG">
4959	SATA device, SATA port, IDE port or IDE slot out of range.
4960	</result>
4961	<result name="VBOX_E_INVALID_OBJECT_STATE">
4962	Attempt to modify an unregistered virtual machine.
4963	</result>
4964	<result name="VBOX_E_INVALID_VM_STATE">
4965	Invalid machine state.
4966	</result>
4967
4968	</desc>
4969	<param name="name" type="wstring" dir="in">
4970	<desc>Name of the storage controller.</desc>
4971	</param>
4972	<param name="controllerPort" type="long" dir="in">
4973	<desc>Storage controller port.</desc>
4974	</param>
4975	<param name="device" type="long" dir="in">
4976	<desc>Device slot in the given port.</desc>
4977	</param>
4978	<param name="passthrough" type="boolean" dir="in">
4979	<desc>New value for the passthrough setting.</desc>
4980	</param>
4981	</method>
4982
4983	<method name="mountMedium">
4984	<desc>
4985	Mounts a medium (<link to="IMedium" />, identified
4986	by the given UUID @a id) to the given storage controller
4987	(<link to="IStorageController" />, identified by @a name),
4988	at the indicated port and device. The device must already exist;
4989	see <link to="IMachine::attachDevice"/> for how to attach a new device.
4990
4991	This method is intended only for managing removable media, where the
4992	device is fixed but media is changeable at runtime (such as DVDs
4993	and floppies). It cannot be used for fixed media such as hard disks.
4994
4995	The @a controllerPort and @a device parameters specify the device slot and
4996	have have the same meaning as with <link to="IMachine::attachDevice" />.
4997
4998	The specified device slot can have a medium mounted, which will be
4999	unmounted first. Specifying a zero UUID (or an empty string) for
5000	@a medium does just an unmount.
5001
5002	See <link to="IMedium"/> for more detailed information about
5003	attaching media.
5004
5005	<result name="E_INVALIDARG">
5006	SATA device, SATA port, IDE port or IDE slot out of range.
5007	</result>
5008	<result name="VBOX_E_INVALID_OBJECT_STATE">
5009	Attempt to attach medium to an unregistered virtual machine.
5010	</result>
5011	<result name="VBOX_E_INVALID_VM_STATE">
5012	Invalid machine state.
5013	</result>
5014	<result name="VBOX_E_OBJECT_IN_USE">
5015	Medium already attached to this or another virtual machine.
5016	</result>
5017
5018	</desc>
5019	<param name="name" type="wstring" dir="in">
5020	<desc>Name of the storage controller to attach the medium to.</desc>
5021	</param>
5022	<param name="controllerPort" type="long" dir="in">
5023	<desc>Port to attach the medium to.</desc>
5024	</param>
5025	<param name="device" type="long" dir="in">
5026	<desc>Device slot in the given port to attach the medium to.</desc>
5027	</param>
5028	<param name="medium" type="uuid" mod="string" dir="in">
5029	<desc>UUID of the medium to attach. A zero UUID means unmount the
5030	currently mounted medium.</desc>
5031	</param>
5032	<param name="force" type="boolean" dir="in">
5033	<desc>Allows to force unmount/mount of a medium which is locked by
5034	theDevice slot in the given port to attach the medium to.</desc>
5035	</param>
5036	</method>
5037
5038	<method name="getMedium" const="yes">
5039	<desc>
5040	Returns the virtual medium attached to a device slot of the specified
5041	bus.
5042
5043	Note that if the medium was indirectly attached by
5044	<link to="#mountMedium"/> to the given device slot then this
5045	method will return not the same object as passed to the
5046	<link to="#mountMedium"/> call. See <link to="IMedium"/> for
5047	more detailed information about mounting a medium.
5048
5049	<result name="VBOX_E_OBJECT_NOT_FOUND">
5050	No medium attached to given slot/bus.
5051	</result>
5052
5053	</desc>
5054	<param name="name" type="wstring" dir="in">
5055	<desc>Name of the storage controller the medium is attached to.</desc>
5056	</param>
5057	<param name="controllerPort" type="long" dir="in">
5058	<desc>Port to query.</desc>
5059	</param>
5060	<param name="device" type="long" dir="in">
5061	<desc>Device slot in the given port to query.</desc>
5062	</param>
5063	<param name="medium" type="IMedium" dir="return">
5064	<desc>Attached medium object.</desc>
5065	</param>
5066	</method>
5067
5068	<method name="getMediumAttachmentsOfController" const="yes">
5069	<desc>
5070	Returns an array of medium attachments which are attached to the
5071	the controller with the given name.
5072
5073	<result name="VBOX_E_OBJECT_NOT_FOUND">
5074	A storage controller with given name doesn't exist.
5075	</result>
5076	</desc>
5077	<param name="name" type="wstring" dir="in"/>
5078	<param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
5079	</method>
5080
5081	<method name="getMediumAttachment" const="yes">
5082	<desc>
5083	Returns a medium attachment which corresponds to the controller with
5084	the given name, on the given port and device slot.
5085
5086	<result name="VBOX_E_OBJECT_NOT_FOUND">
5087	No attachment exists for the given controller/port/device combination.
5088	</result>
5089	</desc>
5090	<param name="name" type="wstring" dir="in"/>
5091	<param name="controllerPort" type="long" dir="in"/>
5092	<param name="device" type="long" dir="in"/>
5093	<param name="attachment" type="IMediumAttachment" dir="return"/>
5094	</method>
5095
5096	<method name="getNetworkAdapter" const="yes">
5097	<desc>
5098	Returns the network adapter associated with the given slot.
5099	Slots are numbered sequentially, starting with zero. The total
5100	number of adapters per machine is defined by the
5101	<link to="ISystemProperties::networkAdapterCount"/> property,
5102	so the maximum slot number is one less than that property's value.
5103
5104	<result name="E_INVALIDARG">
5105	Invalid @a slot number.
5106	</result>
5107
5108	</desc>
5109	<param name="slot" type="unsigned long" dir="in"/>
5110	<param name="adapter" type="INetworkAdapter" dir="return"/>
5111	</method>
5112
5113	<method name="addStorageController">
5114	<desc>
5115	Adds a new storage controller (SCSI or SATA controller) to the
5116	machine and returns it as an instance of
5117	<link to="IStorageController" />.
5118
5119	@a name identifies the controller for subsequent calls such as
5120	<link to="#getStorageControllerByName" />,
5121	<link to="#getStorageControllerByInstance" />,
5122	<link to="#removeStorageController" />,
5123	<link to="#attachDevice" /> or <link to="#mountMedium" />.
5124
5125	After the controller has been added, you can set its exact
5126	type by setting the <link to="IStorageController::controllerType" />.
5127
5128	<result name="VBOX_E_OBJECT_IN_USE">
5129	A storage controller with given name exists already.
5130	</result>
5131	<result name="E_INVALIDARG">
5132	Invalid @a controllerType.
5133	</result>
5134	</desc>
5135	<param name="name" type="wstring" dir="in"/>
5136	<param name="connectionType" type="StorageBus" dir="in"/>
5137	<param name="controller" type="IStorageController" dir="return"/>
5138	</method>
5139
5140	<method name="getStorageControllerByName" const="yes">
5141	<desc>
5142	Returns a storage controller with the given name.
5143
5144	<result name="VBOX_E_OBJECT_NOT_FOUND">
5145	A storage controller with given name doesn't exist.
5146	</result>
5147	</desc>
5148	<param name="name" type="wstring" dir="in"/>
5149	<param name="storageController" type="IStorageController" dir="return"/>
5150	</method>
5151
5152	<method name="getStorageControllerByInstance" const="yes">
5153	<desc>
5154	Returns a storage controller with the given instance number.
5155
5156	<result name="VBOX_E_OBJECT_NOT_FOUND">
5157	A storage controller with given instance number doesn't exist.
5158	</result>
5159	</desc>
5160	<param name="instance" type="unsigned long" dir="in"/>
5161	<param name="storageController" type="IStorageController" dir="return"/>
5162	</method>
5163
5164	<method name="removeStorageController">
5165	<desc>
5166	Removes a storage controller from the machine.
5167
5168	<result name="VBOX_E_OBJECT_NOT_FOUND">
5169	A storage controller with given name doesn't exist.
5170	</result>
5171	</desc>
5172	<param name="name" type="wstring" dir="in"/>
5173	</method>
5174
5175	<method name="getSerialPort" const="yes">
5176	<desc>
5177	Returns the serial port associated with the given slot.
5178	Slots are numbered sequentially, starting with zero. The total
5179	number of serial ports per machine is defined by the
5180	<link to="ISystemProperties::serialPortCount"/> property,
5181	so the maximum slot number is one less than that property's value.
5182
5183	<result name="E_INVALIDARG">
5184	Invalid @a slot number.
5185	</result>
5186
5187	</desc>
5188	<param name="slot" type="unsigned long" dir="in"/>
5189	<param name="port" type="ISerialPort" dir="return"/>
5190	</method>
5191
5192	<method name="getParallelPort" const="yes">
5193	<desc>
5194	Returns the parallel port associated with the given slot.
5195	Slots are numbered sequentially, starting with zero. The total
5196	number of parallel ports per machine is defined by the
5197	<link to="ISystemProperties::parallelPortCount"/> property,
5198	so the maximum slot number is one less than that property's value.
5199
5200	<result name="E_INVALIDARG">
5201	Invalid @a slot number.
5202	</result>
5203
5204	</desc>
5205	<param name="slot" type="unsigned long" dir="in"/>
5206	<param name="port" type="IParallelPort" dir="return"/>
5207	</method>
5208
5209	<method name="getExtraDataKeys">
5210	<desc>
5211	Returns an array representing the machine-specific extra data keys
5212	which currently have values defined.
5213	</desc>
5214	<param name="value" type="wstring" dir="return" safearray="yes">
5215	<desc>Array of extra data keys.</desc>
5216	</param>
5217	</method>
5218
5219	<method name="getExtraData">
5220	<desc>
5221	Returns associated machine-specific extra data.
5222
5223	If the requested data @a key does not exist, this function will
5224	succeed and return an empty string in the @a value argument.
5225
5226	<result name="VBOX_E_FILE_ERROR">
5227	Settings file not accessible.
5228	</result>
5229	<result name="VBOX_E_XML_ERROR">
5230	Could not parse the settings file.
5231	</result>
5232
5233	</desc>
5234	<param name="key" type="wstring" dir="in">
5235	<desc>Name of the data key to get.</desc>
5236	</param>
5237	<param name="value" type="wstring" dir="return">
5238	<desc>Value of the requested data key.</desc>
5239	</param>
5240	</method>
5241
5242	<method name="setExtraData">
5243	<desc>
5244	Sets associated machine-specific extra data.
5245
5246	If you pass @c null or an empty string as a key @a value, the given
5247	@a key will be deleted.
5248
5249	<note>
5250	Before performing the actual data change, this method will ask all
5251	registered callbacks using the
5252	<link to="IVirtualBoxCallback::onExtraDataCanChange"/>
5253	notification for a permission. If one of the callbacks refuses the
5254	new value, the change will not be performed.
5255	</note>
5256	<note>
5257	On success, the
5258	<link to="IVirtualBoxCallback::onExtraDataChange"/> notification
5259	is called to inform all registered callbacks about a successful data
5260	change.
5261	</note>
5262	<note>
5263	This method can be called outside the machine session and therefore
5264	it's a caller's responsibility to handle possible race conditions
5265	when several clients change the same key at the same time.
5266	</note>
5267
5268	<result name="VBOX_E_FILE_ERROR">
5269	Settings file not accessible.
5270	</result>
5271	<result name="VBOX_E_XML_ERROR">
5272	Could not parse the settings file.
5273	</result>
5274
5275	</desc>
5276	<param name="key" type="wstring" dir="in">
5277	<desc>Name of the data key to set.</desc>
5278	</param>
5279	<param name="value" type="wstring" dir="in">
5280	<desc>Value to assign to the key.</desc>
5281	</param>
5282	</method>
5283
5284	<method name="getCPUProperty" const="yes">
5285	<desc>
5286	Returns the virtual CPU boolean value of the specified property.
5287
5288	<result name="E_INVALIDARG">
5289	Invalid property.
5290	</result>
5291
5292	</desc>
5293	<param name="property" type="CPUPropertyType" dir="in">
5294	<desc>
5295	Property type to query.
5296	</desc>
5297	</param>
5298	<param name="value" type="boolean" dir="return">
5299	<desc>
5300	Property value.
5301	</desc>
5302	</param>
5303	</method>
5304
5305	<method name="setCPUProperty">
5306	<desc>
5307	Sets the virtual CPU boolean value of the specified property.
5308
5309	<result name="E_INVALIDARG">
5310	Invalid property.
5311	</result>
5312
5313	</desc>
5314	<param name="property" type="CPUPropertyType" dir="in">
5315	<desc>
5316	Property type to query.
5317	</desc>
5318	</param>
5319	<param name="value" type="boolean" dir="in">
5320	<desc>
5321	Property value.
5322	</desc>
5323	</param>
5324	</method>
5325
5326	<method name="getCPUIDLeaf" const="yes">
5327	<desc>
5328	Returns the virtual CPU cpuid information for the specified leaf.
5329
5330	Currently supported index values for cpuid:
5331	Standard CPUID leafs: 0 - 0xA
5332	Extended CPUID leafs: 0x80000000 - 0x8000000A
5333
5334	See the Intel and AMD programmer's manuals for detailed information
5335	about the cpuid instruction and its leafs.
5336	<result name="E_INVALIDARG">
5337	Invalid id.
5338	</result>
5339
5340	</desc>
5341	<param name="id" type="unsigned long" dir="in">
5342	<desc>
5343	CPUID leaf index.
5344	</desc>
5345	</param>
5346	<param name="valEax" type="unsigned long" dir="out">
5347	<desc>
5348	CPUID leaf value for register eax.
5349	</desc>
5350	</param>
5351	<param name="valEbx" type="unsigned long" dir="out">
5352	<desc>
5353	CPUID leaf value for register ebx.
5354	</desc>
5355	</param>
5356	<param name="valEcx" type="unsigned long" dir="out">
5357	<desc>
5358	CPUID leaf value for register ecx.
5359	</desc>
5360	</param>
5361	<param name="valEdx" type="unsigned long" dir="out">
5362	<desc>
5363	CPUID leaf value for register edx.
5364	</desc>
5365	</param>
5366	</method>
5367
5368	<method name="setCPUIDLeaf">
5369	<desc>
5370	Sets the virtual CPU cpuid information for the specified leaf. Note that these values
5371	are not passed unmodified. VirtualBox clears features that it doesn't support.
5372
5373	Currently supported index values for cpuid:
5374	Standard CPUID leafs: 0 - 0xA
5375	Extended CPUID leafs: 0x80000000 - 0x8000000A
5376
5377	See the Intel and AMD programmer's manuals for detailed information
5378	about the cpuid instruction and its leafs.
5379
5380	Do not use this method unless you know exactly what you're doing. Misuse can lead to
5381	random crashes inside VMs.
5382	<result name="E_INVALIDARG">
5383	Invalid id.
5384	</result>
5385
5386	</desc>
5387	<param name="id" type="unsigned long" dir="in">
5388	<desc>
5389	CPUID leaf index.
5390	</desc>
5391	</param>
5392	<param name="valEax" type="unsigned long" dir="in">
5393	<desc>
5394	CPUID leaf value for register eax.
5395	</desc>
5396	</param>
5397	<param name="valEbx" type="unsigned long" dir="in">
5398	<desc>
5399	CPUID leaf value for register ebx.
5400	</desc>
5401	</param>
5402	<param name="valEcx" type="unsigned long" dir="in">
5403	<desc>
5404	CPUID leaf value for register ecx.
5405	</desc>
5406	</param>
5407	<param name="valEdx" type="unsigned long" dir="in">
5408	<desc>
5409	CPUID leaf value for register edx.
5410	</desc>
5411	</param>
5412	</method>
5413
5414	<method name="removeCPUIDLeaf">
5415	<desc>
5416	Removes the virtual CPU cpuid leaf for the specified index
5417
5418	<result name="E_INVALIDARG">
5419	Invalid id.
5420	</result>
5421
5422	</desc>
5423	<param name="id" type="unsigned long" dir="in">
5424	<desc>
5425	CPUID leaf index.
5426	</desc>
5427	</param>
5428	</method>
5429
5430	<method name="removeAllCPUIDLeaves">
5431	<desc>
5432	Removes all the virtual CPU cpuid leaves
5433	</desc>
5434	</method>
5435
5436	<method name="getHWVirtExProperty" const="yes">
5437	<desc>
5438	Returns the value of the specified hardware virtualization boolean property.
5439
5440	<result name="E_INVALIDARG">
5441	Invalid property.
5442	</result>
5443
5444	</desc>
5445	<param name="property" type="HWVirtExPropertyType" dir="in">
5446	<desc>
5447	Property type to query.
5448	</desc>
5449	</param>
5450	<param name="value" type="boolean" dir="return">
5451	<desc>
5452	Property value.
5453	</desc>
5454	</param>
5455	</method>
5456
5457	<method name="setHWVirtExProperty">
5458	<desc>
5459	Sets a new value for the specified hardware virtualization boolean property.
5460
5461	<result name="E_INVALIDARG">
5462	Invalid property.
5463	</result>
5464
5465	</desc>
5466	<param name="property" type="HWVirtExPropertyType" dir="in">
5467	<desc>
5468	Property type to set.
5469	</desc>
5470	</param>
5471	<param name="value" type="boolean" dir="in">
5472	<desc>
5473	New property value.
5474	</desc>
5475	</param>
5476	</method>
5477
5478	<method name="saveSettings">
5479	<desc>
5480	Saves any changes to machine settings made since the session
5481	has been opened or a new machine has been created, or since the
5482	last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
5483	For registered machines, new settings become visible to all
5484	other VirtualBox clients after successful invocation of this
5485	method.
5486	<note>
5487	The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
5488	notification event after the configuration has been successfully
5489	saved (only for registered machines).
5490	</note>
5491	<note>
5492	Calling this method is only valid on instances returned
5493	by <link to="ISession::machine"/> and on new machines
5494	created by <link to="IVirtualBox::createMachine"/> but not
5495	yet registered, or on unregistered machines after calling
5496	<link to="IVirtualBox::unregisterMachine"/>.
5497	</note>
5498
5499	<result name="VBOX_E_FILE_ERROR">
5500	Settings file not accessible.
5501	</result>
5502	<result name="VBOX_E_XML_ERROR">
5503	Could not parse the settings file.
5504	</result>
5505	<result name="E_ACCESSDENIED">
5506	Modification request refused.
5507	</result>
5508
5509	</desc>
5510	</method>
5511
5512	<method name="discardSettings">
5513	<desc>
5514	Discards any changes to the machine settings made since the session
5515	has been opened or since the last call to <link to="#saveSettings"/>
5516	or <link to="#discardSettings"/>.
5517	<note>
5518	Calling this method is only valid on instances returned
5519	by <link to="ISession::machine"/> and on new machines
5520	created by <link to="IVirtualBox::createMachine"/> or
5521	opened by <link to="IVirtualBox::openMachine"/> but not
5522	yet registered, or on unregistered machines after calling
5523	<link to="IVirtualBox::unregisterMachine"/>.
5524	</note>
5525
5526	<result name="VBOX_E_INVALID_VM_STATE">
5527	Virtual machine is not mutable.
5528	</result>
5529
5530	</desc>
5531	</method>
5532
5533	<method name="deleteSettings">
5534	<desc>
5535	Deletes the settings file of this machine from disk.
5536	The machine must not be registered in order for this operation
5537	to succeed.
5538	<note>
5539	<link to="#settingsModified"/> will return @c true after this
5540	method successfully returns.
5541	</note>
5542	<note>
5543	Calling this method is only valid on instances returned
5544	by <link to="ISession::machine"/> and on new machines
5545	created by <link to="IVirtualBox::createMachine"/> or
5546	opened by <link to="IVirtualBox::openMachine"/> but not
5547	yet registered, or on unregistered machines after calling
5548	<link to="IVirtualBox::unregisterMachine"/>.
5549	</note>
5550	<note>
5551	The deleted machine settings file can be restored (saved again)
5552	by calling <link to="#saveSettings"/>.
5553	</note>
5554
5555	<result name="VBOX_E_INVALID_VM_STATE">
5556	Cannot delete settings of a registered machine or
5557	machine not mutable.
5558	</result>
5559	<result name="VBOX_E_IPRT_ERROR">
5560	Could not delete the settings file.
5561	</result>
5562
5563	</desc>
5564	</method>
5565
5566	<method name="export">
5567	<desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
5568	steps required to export VirtualBox machines to OVF.
5569	</desc>
5570
5571	<param name="aAppliance" type="IAppliance" dir="in">
5572	<desc>Appliance to export this machine to.</desc>
5573	</param>
5574	<param name="aDescription" type="IVirtualSystemDescription" dir="return">
5575	<desc>VirtualSystemDescription object which is created for this machine.</desc>
5576	</param>
5577	</method >
5578
5579	<method name="getSnapshot">
5580	<desc>
5581	Returns a snapshot of this machine with the given UUID.
5582	A @c null UUID can be used to obtain the first snapshot
5583	taken on this machine. This is useful if you want to traverse
5584	the whole tree of snapshots starting from the root.
5585
5586	<result name="VBOX_E_OBJECT_NOT_FOUND">
5587	Virtual machine has no snapshots or snapshot not found.
5588	</result>
5589
5590	</desc>
5591	<param name="id" type="uuid" mod="string" dir="in">
5592	<desc>UUID of the snapshot to get</desc>
5593	</param>
5594	<param name="snapshot" type="ISnapshot" dir="return">
5595	<desc>Snapshot object with the given UUID.</desc>
5596	</param>
5597	</method>
5598
5599	<method name="findSnapshot">
5600	<desc>
5601	Returns a snapshot of this machine with the given name.
5602
5603	<result name="VBOX_E_OBJECT_NOT_FOUND">
5604	Virtual machine has no snapshots or snapshot not found.
5605	</result>
5606
5607	</desc>
5608	<param name="name" type="wstring" dir="in">
5609	<desc>Name of the snapshot to find</desc>
5610	</param>
5611	<param name="snapshot" type="ISnapshot" dir="return">
5612	<desc>Snapshot object with the given name.</desc>
5613	</param>
5614	</method>
5615
5616	<method name="setCurrentSnapshot">
5617	<desc>
5618	Sets the current snapshot of this machine.
5619	<note>
5620	In the current implementation, this operation is not
5621	implemented.
5622	</note>
5623	</desc>
5624	<param name="id" type="uuid" mod="string" dir="in">
5625	<desc>UUID of the snapshot to set as the current snapshot.</desc>
5626	</param>
5627	</method>
5628
5629	<method name="createSharedFolder">
5630	<desc>
5631	Creates a new permanent shared folder by associating the given logical
5632	name with the given host path, adds it to the collection of shared
5633	folders and starts sharing it. Refer to the description of
5634	<link to="ISharedFolder"/> to read more about logical names.
5635
5636	<result name="VBOX_E_OBJECT_IN_USE">
5637	Shared folder already exists.
5638	</result>
5639	<result name="VBOX_E_FILE_ERROR">
5640	Shared folder @a hostPath not accessible.
5641	</result>
5642
5643	</desc>
5644	<param name="name" type="wstring" dir="in">
5645	<desc>Unique logical name of the shared folder.</desc>
5646	</param>
5647	<param name="hostPath" type="wstring" dir="in">
5648	<desc>Full path to the shared folder in the host file system.</desc>
5649	</param>
5650	<param name="writable" type="boolean" dir="in">
5651	<desc>Whether the share is writable or readonly</desc>
5652	</param>
5653	</method>
5654
5655	<method name="removeSharedFolder">
5656	<desc>
5657	Removes the permanent shared folder with the given name previously
5658	created by <link to="#createSharedFolder"/> from the collection of
5659	shared folders and stops sharing it.
5660
5661	<result name="VBOX_E_INVALID_VM_STATE">
5662	Virtual machine is not mutable.
5663	</result>
5664	<result name="VBOX_E_OBJECT_NOT_FOUND">
5665	Shared folder @a name does not exist.
5666	</result>
5667
5668	</desc>
5669	<param name="name" type="wstring" dir="in">
5670	<desc>Logical name of the shared folder to remove.</desc>
5671	</param>
5672	</method>
5673
5674	<method name="canShowConsoleWindow">
5675	<desc>
5676	Returns @c true if the VM console process can activate the
5677	console window and bring it to foreground on the desktop of
5678	the host PC.
5679	<note>
5680	This method will fail if a session for this machine is not
5681	currently open.
5682	</note>
5683
5684	<result name="VBOX_E_INVALID_VM_STATE">
5685	Machine session is not open.
5686	</result>
5687
5688	</desc>
5689	<param name="canShow" type="boolean" dir="return">
5690	<desc>
5691	@c true if the console window can be shown and @c false otherwise.
5692	</desc>
5693	</param>
5694	</method>
5695
5696	<method name="showConsoleWindow">
5697	<desc>
5698	Activates the console window and brings it to foreground on
5699	the desktop of the host PC. Many modern window managers on
5700	many platforms implement some sort of focus stealing
5701	prevention logic, so that it may be impossible to activate
5702	a window without the help of the currently active
5703	application. In this case, this method will return a non-zero
5704	identifier that represents the top-level window of the VM
5705	console process. The caller, if it represents a currently
5706	active process, is responsible to use this identifier (in a
5707	platform-dependent manner) to perform actual window
5708	activation.
5709	<note>
5710	This method will fail if a session for this machine is not
5711	currently open.
5712	</note>
5713
5714	<result name="VBOX_E_INVALID_VM_STATE">
5715	Machine session is not open.
5716	</result>
5717
5718	</desc>
5719	<param name="winId" type="unsigned long long" dir="return">
5720	<desc>
5721	Platform-dependent identifier of the top-level VM console
5722	window, or zero if this method has performed all actions
5723	necessary to implement the <i>show window</i> semantics for
5724	the given platform and/or VirtualBox front-end.
5725	</desc>
5726	</param>
5727	</method>
5728
5729	<method name="getGuestProperty" const="yes">
5730	<desc>
5731	Reads an entry from the machine's guest property store.
5732
5733	<result name="VBOX_E_INVALID_VM_STATE">
5734	Machine session is not open.
5735	</result>
5736
5737	</desc>
5738	<param name="name" type="wstring" dir="in">
5739	<desc>
5740	The name of the property to read.
5741	</desc>
5742	</param>
5743	<param name="value" type="wstring" dir="out">
5744	<desc>
5745	The value of the property. If the property does not exist then this
5746	will be empty.
5747	</desc>
5748	</param>
5749	<param name="timestamp" type="unsigned long long" dir="out">
5750	<desc>
5751	The time at which the property was last modified, as seen by the
5752	server process.
5753	</desc>
5754	</param>
5755	<param name="flags" type="wstring" dir="out">
5756	<desc>
5757	Additional property parameters, passed as a comma-separated list of
5758	"name=value" type entries.
5759	</desc>
5760	</param>
5761	</method>
5762
5763	<method name="getGuestPropertyValue" const="yes">
5764	<desc>
5765	Reads a value from the machine's guest property store.
5766
5767	<result name="VBOX_E_INVALID_VM_STATE">
5768	Machine session is not open.
5769	</result>
5770
5771	</desc>
5772	<param name="property" type="wstring" dir="in">
5773	<desc>
5774	The name of the property to read.
5775	</desc>
5776	</param>
5777	<param name="value" type="wstring" dir="return">
5778	<desc>
5779	The value of the property. If the property does not exist then this
5780	will be empty.
5781	</desc>
5782	</param>
5783	</method>
5784
5785	<method name="getGuestPropertyTimestamp" const="yes">
5786	<desc>
5787	Reads a property timestamp from the machine's guest property store.
5788
5789	<result name="VBOX_E_INVALID_VM_STATE">
5790	Machine session is not open.
5791	</result>
5792
5793	</desc>
5794	<param name="property" type="wstring" dir="in">
5795	<desc>
5796	The name of the property to read.
5797	</desc>
5798	</param>
5799	<param name="value" type="unsigned long long" dir="return">
5800	<desc>
5801	The timestamp. If the property does not exist then this will be
5802	empty.
5803	</desc>
5804	</param>
5805	</method>
5806
5807	<method name="setGuestProperty">
5808	<desc>
5809	Sets, changes or deletes an entry in the machine's guest property
5810	store.
5811
5812	<result name="E_ACCESSDENIED">
5813	Property cannot be changed.
5814	</result>
5815	<result name="E_INVALIDARG">
5816	Invalid @a flags.
5817	</result>
5818	<result name="VBOX_E_INVALID_VM_STATE">
5819	Virtual machine is not mutable or session not open.
5820	</result>
5821	<result name="VBOX_E_INVALID_OBJECT_STATE">
5822	Cannot set transient property when machine not running.
5823	</result>
5824
5825	</desc>
5826	<param name="property" type="wstring" dir="in">
5827	<desc>
5828	The name of the property to set, change or delete.
5829	</desc>
5830	</param>
5831	<param name="value" type="wstring" dir="in">
5832	<desc>
5833	The new value of the property to set, change or delete. If the
5834	property does not yet exist and value is non-empty, it will be
5835	created. If the value is @c null or empty, the property will be
5836	deleted if it exists.
5837	</desc>
5838	</param>
5839	<param name="flags" type="wstring" dir="in">
5840	<desc>
5841	Additional property parameters, passed as a comma-separated list of
5842	"name=value" type entries.
5843	</desc>
5844	</param>
5845	</method>
5846
5847	<method name="setGuestPropertyValue">
5848	<desc>
5849	Sets, changes or deletes a value in the machine's guest property
5850	store. The flags field will be left unchanged or created empty for a
5851	new property.
5852
5853	<result name="E_ACCESSDENIED">
5854	Property cannot be changed.
5855	</result>
5856	<result name="VBOX_E_INVALID_VM_STATE">
5857	Virtual machine is not mutable or session not open.
5858	</result>
5859	<result name="VBOX_E_INVALID_OBJECT_STATE">
5860	Cannot set transient property when machine not running.
5861	</result>
5862	</desc>
5863
5864	<param name="property" type="wstring" dir="in">
5865	<desc>
5866	The name of the property to set, change or delete.
5867	</desc>
5868	</param>
5869	<param name="value" type="wstring" dir="in">
5870	<desc>
5871	The new value of the property to set, change or delete. If the
5872	property does not yet exist and value is non-empty, it will be
5873	created. If the value is @c null or empty, the property will be
5874	deleted if it exists.
5875	</desc>
5876	</param>
5877	</method>
5878
5879	<method name="enumerateGuestProperties">
5880	<desc>
5881	Return a list of the guest properties matching a set of patterns along
5882	with their values, time stamps and flags.
5883	</desc>
5884	<param name="patterns" type="wstring" dir="in">
5885	<desc>
5886	The patterns to match the properties against, separated by '\|'
5887	characters. If this is empty or @c null, all properties will match.
5888	</desc>
5889	</param>
5890	<param name="name" type="wstring" dir="out" safearray="yes">
5891	<desc>
5892	The names of the properties returned.
5893	</desc>
5894	</param>
5895	<param name="value" type="wstring" dir="out" safearray="yes">
5896	<desc>
5897	The values of the properties returned. The array entries match the
5898	corresponding entries in the @a name array.
5899	</desc>
5900	</param>
5901	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
5902	<desc>
5903	The time stamps of the properties returned. The array entries match
5904	the corresponding entries in the @a name array.
5905	</desc>
5906	</param>
5907	<param name="flags" type="wstring" dir="out" safearray="yes">
5908	<desc>
5909	The flags of the properties returned. The array entries match the
5910	corresponding entries in the @a name array.
5911	</desc>
5912	</param>
5913	</method>
5914
5915	<method name="querySavedThumbnailSize">
5916	<desc>
5917	Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
5918	</desc>
5919	<param name="size" type="unsigned long" dir="out">
5920	<desc>
5921	Size of buffer required to store the bitmap.
5922	</desc>
5923	</param>
5924	<param name="width" type="unsigned long" dir="out">
5925	<desc>
5926	Bitmap width.
5927	</desc>
5928	</param>
5929	<param name="height" type="unsigned long" dir="out">
5930	<desc>
5931	Bitmap height.
5932	</desc>
5933	</param>
5934	</method>
5935
5936	<method name="readSavedThumbnailToArray">
5937	<desc>
5938	Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
5939	</desc>
5940	<param name="BGR" type="boolean" dir="in">
5941	<desc>
5942	How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
5943	bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
5944	</desc>
5945	</param>
5946	<param name="width" type="unsigned long" dir="out">
5947	<desc>
5948	Bitmap width.
5949	</desc>
5950	</param>
5951	<param name="height" type="unsigned long" dir="out">
5952	<desc>
5953	Bitmap height.
5954	</desc>
5955	</param>
5956	<param name="data" type="octet" dir="return" safearray="yes">
5957	<desc>
5958	Array with resulting bitmap data.
5959	</desc>
5960	</param>
5961	</method>
5962
5963	<method name="querySavedScreenshotPNGSize">
5964	<desc>
5965	Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
5966	</desc>
5967	<param name="size" type="unsigned long" dir="out">
5968	<desc>
5969	Size of buffer required to store the PNG binary data.
5970	</desc>
5971	</param>
5972	<param name="width" type="unsigned long" dir="out">
5973	<desc>
5974	Image width.
5975	</desc>
5976	</param>
5977	<param name="height" type="unsigned long" dir="out">
5978	<desc>
5979	Image height.
5980	</desc>
5981	</param>
5982	</method>
5983
5984	<method name="readSavedScreenshotPNGToArray">
5985	<desc>
5986	Screenshot in PNG format is retrieved to an array of bytes.
5987	</desc>
5988	<param name="width" type="unsigned long" dir="out">
5989	<desc>
5990	Image width.
5991	</desc>
5992	</param>
5993	<param name="height" type="unsigned long" dir="out">
5994	<desc>
5995	Image height.
5996	</desc>
5997	</param>
5998	<param name="data" type="octet" dir="return" safearray="yes">
5999	<desc>
6000	Array with resulting PNG data.
6001	</desc>
6002	</param>
6003	</method>
6004
6005	<method name="hotPlugCPU">
6006	<desc>
6007	Plugs a CPU into the machine.
6008	</desc>
6009	<param name="cpu" type="unsigned long" dir="in">
6010	<desc>
6011	The CPU id to insert.
6012	</desc>
6013	</param>
6014	</method>
6015
6016	<method name="hotUnplugCPU">
6017	<desc>
6018	Removes a CPU from the machine.
6019	</desc>
6020	<param name="cpu" type="unsigned long" dir="in">
6021	<desc>
6022	The CPU id to remove.
6023	</desc>
6024	</param>
6025	</method>
6026
6027	<method name="getCPUStatus">
6028	<desc>
6029	Returns the current status of the given CPU.
6030	</desc>
6031	<param name="cpu" type="unsigned long" dir="in">
6032	<desc>
6033	The CPU id to check for.
6034	</desc>
6035	</param>
6036	<param name="attached" type="boolean" dir="return">
6037	<desc>
6038	Status of the CPU.
6039	</desc>
6040	</param>
6041	</method>
6042
6043	<method name="queryLogFilename">
6044	<desc>
6045	Queries for the VM log file name of an given index. Returns an empty
6046	string if a log file with that index doesn't exists.
6047	</desc>
6048	<param name="idx" type="unsigned long" dir="in">
6049	<desc>
6050	Which log file name to query. 0=current log file.
6051	</desc>
6052	</param>
6053	<param name="filename" type="wstring" dir="return">
6054	<desc>
6055	On return the full path to the log file or an empty string on error.
6056	</desc>
6057	</param>
6058	</method>
6059
6060	<method name="readLog">
6061	<desc>
6062	Reads the VM log file. The chunk size is limited, so even if you
6063	ask for a big piece there might be less data returned.
6064	</desc>
6065	<param name="idx" type="unsigned long" dir="in">
6066	<desc>
6067	Which log file to read. 0=current log file.
6068	</desc>
6069	</param>
6070	<param name="offset" type="unsigned long long" dir="in">
6071	<desc>
6072	Offset in the log file.
6073	</desc>
6074	</param>
6075	<param name="size" type="unsigned long long" dir="in">
6076	<desc>
6077	Chunk size to read in the log file.
6078	</desc>
6079	</param>
6080	<param name="data" type="octet" dir="return" safearray="yes">
6081	<desc>
6082	Data read from the log file. A data size of 0 means end of file
6083	if the requested chunk size was not 0. This is the unprocessed
6084	file data, i.e. the line ending style depends on the platform of
6085	the system the server is running on.
6086	</desc>
6087	</param>
6088	</method>
6089	</interface>
6090
6091	<!--
6092	// IConsole
6093	/////////////////////////////////////////////////////////////////////////
6094	-->
6095
6096	<interface
6097	name="IConsoleCallback" extends="$unknown"
6098	uuid="60703f8d-81e4-4b45-a147-dcfd07692b19"
6099	wsmap="suppress"
6100	>
6101
6102	<desc>
6103	This interface is used by a client of the Main API that need to
6104	be notified of events. For example, a graphical user interface
6105	can use this to learn about machine state changes so they can
6106	update the list of virtual machines without having to rely
6107	on polling.
6108
6109	Whenever relevant events occur in VirtualBox, the callbacks in
6110	objects of this interface are called. In order for this to be
6111	useful, a client needs to create its own subclass that implements
6112	this interface in which the methods for the relevant callbacks
6113	are overridden. An instance of this subclass interface can then
6114	be passed to <link to="IConsole::registerCallback" />.
6115	</desc>
6116
6117	<method name="onMousePointerShapeChange">
6118	<desc>
6119	Notification when the guest mouse pointer shape has
6120	changed. The new shape data is given.
6121	</desc>
6122	<param name="visible" type="boolean" dir="in">
6123	<desc>
6124	Flag whether the pointer is visible.
6125	</desc>
6126	</param>
6127	<param name="alpha" type="boolean" dir="in">
6128	<desc>
6129	Flag whether the pointer has an alpha channel.
6130	</desc>
6131	</param>
6132	<param name="xHot" type="unsigned long" dir="in">
6133	<desc>
6134	The pointer hot spot x coordinate.
6135	</desc>
6136	</param>
6137	<param name="yHot" type="unsigned long" dir="in">
6138	<desc>
6139	The pointer hot spot y coordinate.
6140	</desc>
6141	</param>
6142	<param name="width" type="unsigned long" dir="in">
6143	<desc>
6144	Width of the pointer shape in pixels.
6145	</desc>
6146	</param>
6147	<param name="height" type="unsigned long" dir="in">
6148	<desc>
6149	Height of the pointer shape in pixels.
6150	</desc>
6151	</param>
6152	<param name="shape" type="octet" mod="ptr" dir="in">
6153	<desc>
6154	Address of the shape buffer.
6155
6156	The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
6157	followed by a 32-bpp XOR (color) mask.
6158
6159	For pointers without alpha channel the XOR mask pixels are 32
6160	bit values: (lsb)BGR0(msb). For pointers with alpha channel
6161	the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
6162
6163	An AND mask is used for pointers with alpha channel, so if the
6164	callback does not support alpha, the pointer could be
6165	displayed as a normal color pointer.
6166
6167	The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
6168	size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
6169	height</tt>. The padding bits at the end of each scanline are
6170	undefined.
6171
6172	The XOR mask follows the AND mask on the next 4-byte aligned
6173	offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
6174	Bytes in the gap between the AND and the XOR mask are undefined.
6175	The XOR mask scanlines have no gap between them and the size of
6176	the XOR mask is: <tt>cXor = width * 4 * height</tt>.
6177
6178	<note>
6179	If @a shape is 0, only the pointer visibility is changed.
6180	</note>
6181	</desc>
6182	</param>
6183	</method>
6184
6185	<method name="onMouseCapabilityChange">
6186	<desc>
6187	Notification when the mouse capabilities reported by the
6188	guest have changed. The new capabilities are passed.
6189	</desc>
6190	<param name="supportsAbsolute" type="boolean" dir="in"/>
6191	<param name="supportsRelative" type="boolean" dir="in"/>
6192	<param name="needsHostCursor" type="boolean" dir="in"/>
6193	</method>
6194
6195	<method name="onKeyboardLedsChange">
6196	<desc>
6197	Notification when the guest OS executes the KBD_CMD_SET_LEDS command
6198	to alter the state of the keyboard LEDs.
6199	</desc>
6200	<param name="numLock" type="boolean" dir="in"/>
6201	<param name="capsLock" type="boolean" dir="in"/>
6202	<param name="scrollLock" type="boolean" dir="in"/>
6203	</method>
6204
6205	<method name="onStateChange">
6206	<desc>
6207	Notification when the execution state of the machine has changed.
6208	The new state will be given.
6209	</desc>
6210	<param name="state" type="MachineState" dir="in"/>
6211	</method>
6212
6213	<method name="onAdditionsStateChange">
6214	<desc>
6215	Notification when a Guest Additions property changes.
6216	Interested callees should query IGuest attributes to
6217	find out what has changed.
6218	</desc>
6219	</method>
6220
6221	<method name="onNetworkAdapterChange">
6222	<desc>
6223	Notification when a property of one of the
6224	virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
6225	changes. Interested callees should use INetworkAdapter methods and
6226	attributes to find out what has changed.
6227	</desc>
6228	<param name="networkAdapter" type="INetworkAdapter" dir="in">
6229	<desc>Network adapter that is subject to change.</desc>
6230	</param>
6231	</method>
6232
6233	<method name="onSerialPortChange">
6234	<desc>
6235	Notification when a property of one of the
6236	virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
6237	Interested callees should use ISerialPort methods and attributes
6238	to find out what has changed.
6239	</desc>
6240	<param name="serialPort" type="ISerialPort" dir="in">
6241	<desc>Serial port that is subject to change.</desc>
6242	</param>
6243	</method>
6244
6245	<method name="onParallelPortChange">
6246	<desc>
6247	Notification when a property of one of the
6248	virtual <link to="IMachine::getParallelPort">parallel ports</link>
6249	changes. Interested callees should use ISerialPort methods and
6250	attributes to find out what has changed.
6251	</desc>
6252	<param name="parallelPort" type="IParallelPort" dir="in">
6253	<desc>Parallel port that is subject to change.</desc>
6254	</param>
6255	</method>
6256
6257	<method name="onStorageControllerChange">
6258	<desc>
6259	Notification when a property of one of the
6260	virtual <link to="IMachine::storageControllers">storage controllers</link>
6261	changes. Interested callees should query the corresponding collections
6262	to find out what has changed.
6263	</desc>
6264	</method>
6265
6266	<method name="onMediumChange">
6267	<desc>
6268	Notification when a
6269	<link to="IMachine::mediumAttachments">medium attachment</link>
6270	changes.
6271	</desc>
6272	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
6273	<desc>Medium attachment that is subject to change.</desc>
6274	</param>
6275	</method>
6276
6277	<method name="onCPUChange">
6278	<desc>
6279	Notification when a CPU changes.
6280	</desc>
6281	<param name="cpu" type="unsigned long" dir="in">
6282	<desc>The CPU which changed</desc>
6283	</param>
6284	<param name="add" type="boolean" dir="in">
6285	<desc>Flag whether the CPU was added or removed</desc>
6286	</param>
6287	</method>
6288
6289	<method name="onVRDPServerChange">
6290	<desc>
6291	Notification when a property of the
6292	<link to="IMachine::VRDPServer">VRDP server</link> changes.
6293	Interested callees should use IVRDPServer methods and attributes to
6294	find out what has changed.
6295	</desc>
6296	</method>
6297
6298	<method name="onRemoteDisplayInfoChange">
6299	<desc>
6300	Notification when the status of the VRDP server changes. Interested callees
6301	should use <link to="IConsole::RemoteDisplayInfo">IRemoteDisplayInfo</link>
6302	attributes to find out what is the current status.
6303	</desc>
6304	</method>
6305
6306	<method name="onUSBControllerChange">
6307	<desc>
6308	Notification when a property of the virtual
6309	<link to="IMachine::USBController">USB controller</link> changes.
6310	Interested callees should use IUSBController methods and attributes to
6311	find out what has changed.
6312	</desc>
6313	</method>
6314
6315	<method name="onUSBDeviceStateChange">
6316	<desc>
6317	Notification when a USB device is attached to or detached from
6318	the virtual USB controller.
6319
6320	This notification is sent as a result of the indirect
6321	request to attach the device because it matches one of the
6322	machine USB filters, or as a result of the direct request
6323	issued by <link to="IConsole::attachUSBDevice"/> or
6324	<link to="IConsole::detachUSBDevice"/>.
6325
6326	This notification is sent in case of both a succeeded and a
6327	failed request completion. When the request succeeds, the
6328	@a error parameter is @c null, and the given device has been
6329	already added to (when @a attached is @c true) or removed from
6330	(when @a attached is @c false) the collection represented by
6331	<link to="IConsole::USBDevices"/>. On failure, the collection
6332	doesn't change and the @a error parameter represents the error
6333	message describing the failure.
6334
6335	</desc>
6336	<param name="device" type="IUSBDevice" dir="in">
6337	<desc>Device that is subject to state change.</desc>
6338	</param>
6339	<param name="attached" type="boolean" dir="in">
6340	<desc>
6341	@c true if the device was attached and @c false otherwise.
6342	</desc>
6343	</param>
6344	<param name="error" type="IVirtualBoxErrorInfo" dir="in">
6345	<desc>
6346	@c null on success or an error message object on failure.
6347	</desc>
6348	</param>
6349	</method>
6350
6351	<method name="onSharedFolderChange">
6352	<desc>
6353	Notification when a shared folder is added or removed.
6354	The @a scope argument defines one of three scopes:
6355	<link to="IVirtualBox::sharedFolders">global shared folders</link>
6356	(<link to="Scope_Global">Global</link>),
6357	<link to="IMachine::sharedFolders">permanent shared folders</link> of
6358	the machine (<link to="Scope_Machine">Machine</link>) or <link
6359	to="IConsole::sharedFolders">transient shared folders</link> of the
6360	machine (<link to="Scope_Session">Session</link>). Interested callees
6361	should use query the corresponding collections to find out what has
6362	changed.
6363	</desc>
6364	<param name="scope" type="Scope" dir="in">
6365	<desc>Scope of the notification.</desc>
6366	</param>
6367	</method>
6368
6369	<method name="onRuntimeError">
6370	<desc>
6371	Notification when an error happens during the virtual
6372	machine execution.
6373
6374	There are three kinds of runtime errors:
6375	<ul>
6376	<li><i>fatal</i></li>
6377	<li><i>non-fatal with retry</i></li>
6378	<li><i>non-fatal warnings</i></li>
6379	</ul>
6380
6381	<b>Fatal</b> errors are indicated by the @a fatal parameter set
6382	to @c true. In case of fatal errors, the virtual machine
6383	execution is always paused before calling this notification, and
6384	the notification handler is supposed either to immediately save
6385	the virtual machine state using <link to="IConsole::saveState"/>
6386	or power it off using <link to="IConsole::powerDown"/>.
6387	Resuming the execution can lead to unpredictable results.
6388
6389	<b>Non-fatal</b> errors and warnings are indicated by the
6390	@a fatal parameter set to @c false. If the virtual machine
6391	is in the Paused state by the time the error notification is
6392	received, it means that the user can <i>try to resume</i> the machine
6393	execution after attempting to solve the problem that caused the
6394	error. In this case, the notification handler is supposed
6395	to show an appropriate message to the user (depending on the
6396	value of the @a id parameter) that offers several actions such
6397	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
6398	wants to retry, the notification handler should continue
6399	the machine execution using the <link to="IConsole::resume"/>
6400	call. If the machine execution is not Paused during this
6401	notification, then it means this notification is a <i>warning</i>
6402	(for example, about a fatal condition that can happen very soon);
6403	no immediate action is required from the user, the machine
6404	continues its normal execution.
6405
6406	Note that in either case the notification handler
6407	<b>must not</b> perform any action directly on a thread
6408	where this notification is called. Everything it is allowed to
6409	do is to post a message to another thread that will then talk
6410	to the user and take the corresponding action.
6411
6412	Currently, the following error identifiers are known:
6413	<ul>
6414	<li><tt>"HostMemoryLow"</tt></li>
6415	<li><tt>"HostAudioNotResponding"</tt></li>
6416	<li><tt>"VDIStorageFull"</tt></li>
6417	<li><tt>"3DSupportIncompatibleAdditions"</tt></li>
6418	</ul>
6419
6420	<note>
6421	This notification is not designed to be implemented by
6422	more than one callback at a time. If you have multiple
6423	IConsoleCallback instances registered on the given
6424	IConsole object, make sure you simply do nothing but
6425	return @c S_OK from all but one of them that does actual
6426	user notification and performs necessary actions.
6427	</note>
6428
6429	</desc>
6430	<param name="fatal" type="boolean" dir="in">
6431	<desc>Whether the error is fatal or not</desc>
6432	</param>
6433	<param name="id" type="wstring" dir="in">
6434	<desc>Error identifier</desc>
6435	</param>
6436	<param name="message" type="wstring" dir="in">
6437	<desc>Optional error message</desc>
6438	</param>
6439	</method>
6440
6441	<method name="onCanShowWindow">
6442	<desc>
6443	Notification when a call to
6444	<link to="IMachine::canShowConsoleWindow"/> is made by a
6445	front-end to check if a subsequent call to
6446	<link to="IMachine::showConsoleWindow"/> can succeed.
6447
6448	The callee should give an answer appropriate to the current
6449	machine state in the @a canShow argument. This answer must
6450	remain valid at least until the next
6451	<link to="IConsole::state">machine state</link> change.
6452
6453	<note>
6454	This notification is not designed to be implemented by
6455	more than one callback at a time. If you have multiple
6456	IConsoleCallback instances registered on the given
6457	IConsole object, make sure you simply do nothing but
6458	return @c true and @c S_OK from all but one of them that
6459	actually manages console window activation.
6460	</note>
6461	</desc>
6462	<param name="canShow" type="boolean" dir="return">
6463	<desc>
6464	@c true if the console window can be shown and @c false otherwise.
6465	</desc>
6466	</param>
6467	</method>
6468
6469	<method name="onShowWindow">
6470	<desc>
6471	Notification when a call to
6472	<link to="IMachine::showConsoleWindow"/>
6473	requests the console window to be activated and brought to
6474	foreground on the desktop of the host PC.
6475
6476	This notification should cause the VM console process to
6477	perform the requested action as described above. If it is
6478	impossible to do it at a time of this notification, this
6479	method should return a failure.
6480
6481	Note that many modern window managers on many platforms
6482	implement some sort of focus stealing prevention logic, so
6483	that it may be impossible to activate a window without the
6484	help of the currently active application (which is supposedly
6485	an initiator of this notification). In this case, this method
6486	must return a non-zero identifier that represents the
6487	top-level window of the VM console process. The caller, if it
6488	represents a currently active process, is responsible to use
6489	this identifier (in a platform-dependent manner) to perform
6490	actual window activation.
6491
6492	This method must set @a winId to zero if it has performed all
6493	actions necessary to complete the request and the console
6494	window is now active and in foreground, to indicate that no
6495	further action is required on the caller's side.
6496
6497	<note>
6498	This notification is not designed to be implemented by
6499	more than one callback at a time. If you have multiple
6500	IConsoleCallback instances registered on the given
6501	IConsole object, make sure you simply do nothing but
6502	return @c S_OK from all but one of them that actually
6503	manages console window activation.
6504	</note>
6505	</desc>
6506	<param name="winId" type="unsigned long long" dir="return">
6507	<desc>
6508	Platform-dependent identifier of the top-level VM console
6509	window, or zero if this method has performed all actions
6510	necessary to implement the <i>show window</i> semantics for
6511	the given platform and/or this VirtualBox front-end.
6512	</desc>
6513	</param>
6514	</method>
6515
6516	</interface>
6517
6518	<interface
6519	name="IRemoteDisplayInfo" extends="$unknown"
6520	uuid="b3741084-806f-4c3b-8c42-ebad1a81e45a"
6521	wsmap="struct"
6522	>
6523	<desc>
6524	Contains information about the remote display (VRDP) capabilities and status.
6525	This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
6526	</desc>
6527
6528	<attribute name="active" type="boolean" readonly="yes">
6529	<desc>
6530	Whether the remote display connection is active.
6531	</desc>
6532	</attribute>
6533
6534	<attribute name="port" type="long" readonly="yes">
6535	<desc>
6536	VRDP server port number. If this property is equal to <tt>0</tt>, then
6537	the VRDP server failed to start, usually because there are no free TCP
6538	ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDP
6539	server has not yet been started.
6540	</desc>
6541	</attribute>
6542
6543	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
6544	<desc>
6545	How many times a client connected.
6546	</desc>
6547	</attribute>
6548
6549	<attribute name="beginTime" type="long long" readonly="yes">
6550	<desc>
6551	When the last connection was established, in milliseconds since 1970-01-01 UTC.
6552	</desc>
6553	</attribute>
6554
6555	<attribute name="endTime" type="long long" readonly="yes">
6556	<desc>
6557	When the last connection was terminated or the current time, if
6558	connection is still active, in milliseconds since 1970-01-01 UTC.
6559	</desc>
6560	</attribute>
6561
6562	<attribute name="bytesSent" type="unsigned long long" readonly="yes">
6563	<desc>
6564	How many bytes were sent in last or current, if still active, connection.
6565	</desc>
6566	</attribute>
6567
6568	<attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
6569	<desc>
6570	How many bytes were sent in all connections.
6571	</desc>
6572	</attribute>
6573
6574	<attribute name="bytesReceived" type="unsigned long long" readonly="yes">
6575	<desc>
6576	How many bytes were received in last or current, if still active, connection.
6577	</desc>
6578	</attribute>
6579
6580	<attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
6581	<desc>
6582	How many bytes were received in all connections.
6583	</desc>
6584	</attribute>
6585
6586	<attribute name="user" type="wstring" readonly="yes">
6587	<desc>
6588	Login user name supplied by the client.
6589	</desc>
6590	</attribute>
6591
6592	<attribute name="domain" type="wstring" readonly="yes">
6593	<desc>
6594	Login domain name supplied by the client.
6595	</desc>
6596	</attribute>
6597
6598	<attribute name="clientName" type="wstring" readonly="yes">
6599	<desc>
6600	The client name supplied by the client.
6601	</desc>
6602	</attribute>
6603
6604	<attribute name="clientIP" type="wstring" readonly="yes">
6605	<desc>
6606	The IP address of the client.
6607	</desc>
6608	</attribute>
6609
6610	<attribute name="clientVersion" type="unsigned long" readonly="yes">
6611	<desc>
6612	The client software version number.
6613	</desc>
6614	</attribute>
6615
6616	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
6617	<desc>
6618	Public key exchange method used when connection was established.
6619	Values: 0 - RDP4 public key exchange scheme.
6620	1 - X509 certificates were sent to client.
6621	</desc>
6622	</attribute>
6623
6624	</interface>
6625
6626	<interface
6627	name="IConsole" extends="$unknown"
6628	uuid="6375231a-c17c-464b-92cb-ae9e128d71c3"
6629	wsmap="managed"
6630	>
6631	<desc>
6632	The IConsole interface represents an interface to control virtual
6633	machine execution.
6634
6635	The console object that implements the IConsole interface is obtained
6636	from a session object after the session for the given machine has been
6637	opened using one of <link to="IVirtualBox::openSession"/>,
6638	<link to="IVirtualBox::openRemoteSession"/> or
6639	<link to="IVirtualBox::openExistingSession"/> methods.
6640
6641	Methods of the IConsole interface allow the caller to query the current
6642	virtual machine execution state, pause the machine or power it down, save
6643	the machine state or take a snapshot, attach and detach removable media
6644	and so on.
6645
6646	<see>ISession</see>
6647	</desc>
6648
6649	<attribute name="machine" type="IMachine" readonly="yes">
6650	<desc>
6651	Machine object this console is sessioned with.
6652	<note>
6653	This is a convenience property, it has the same value as
6654	<link to="ISession::machine"/> of the corresponding session
6655	object.
6656	</note>
6657	</desc>
6658	</attribute>
6659
6660	<attribute name="state" type="MachineState" readonly="yes">
6661	<desc>
6662	Current execution state of the machine.
6663	<note>
6664	This property always returns the same value as the corresponding
6665	property of the IMachine object this console is sessioned with.
6666	For the process that owns (executes) the VM, this is the
6667	preferable way of querying the VM state, because no IPC
6668	calls are made.
6669	</note>
6670	</desc>
6671	</attribute>
6672
6673	<attribute name="guest" type="IGuest" readonly="yes">
6674	<desc>Guest object.</desc>
6675	</attribute>
6676
6677	<attribute name="keyboard" type="IKeyboard" readonly="yes">
6678	<desc>
6679	Virtual keyboard object.
6680	<note>
6681	If the machine is not running, any attempt to use
6682	the returned object will result in an error.
6683	</note>
6684	</desc>
6685	</attribute>
6686
6687	<attribute name="mouse" type="IMouse" readonly="yes">
6688	<desc>
6689	Virtual mouse object.
6690	<note>
6691	If the machine is not running, any attempt to use
6692	the returned object will result in an error.
6693	</note>
6694	</desc>
6695	</attribute>
6696
6697	<attribute name="display" type="IDisplay" readonly="yes">
6698	<desc>Virtual display object.
6699	<note>
6700	If the machine is not running, any attempt to use
6701	the returned object will result in an error.
6702	</note>
6703	</desc>
6704	</attribute>
6705
6706	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
6707	<desc>Debugging interface.</desc>
6708	</attribute>
6709
6710	<attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
6711	<desc>
6712	Collection of USB devices currently attached to the virtual
6713	USB controller.
6714	<note>
6715	The collection is empty if the machine is not running.
6716	</note>
6717	</desc>
6718	</attribute>
6719
6720	<attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6721	<desc>
6722	List of USB devices currently attached to the remote VRDP client.
6723	Once a new device is physically attached to the remote host computer,
6724	it appears in this list and remains there until detached.
6725	</desc>
6726	</attribute>
6727
6728	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
6729	<desc>
6730	Collection of shared folders for the current session. These folders
6731	are called transient shared folders because they are available to the
6732	guest OS running inside the associated virtual machine only for the
6733	duration of the session (as opposed to
6734	<link to="IMachine::sharedFolders"/> which represent permanent shared
6735	folders). When the session is closed (e.g. the machine is powered down),
6736	these folders are automatically discarded.
6737
6738	New shared folders are added to the collection using
6739	<link to="#createSharedFolder"/>. Existing shared folders can be
6740	removed using <link to="#removeSharedFolder"/>.
6741	</desc>
6742	</attribute>
6743
6744	<attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
6745	<desc>
6746	Interface that provides information on Remote Display (VRDP) connection.
6747	</desc>
6748	</attribute>
6749
6750	<method name="powerUp">
6751	<desc>
6752	Starts the virtual machine execution using the current machine
6753	state (that is, its current execution state, current settings and
6754	current storage devices).
6755
6756	If the machine is powered off or aborted, the execution will
6757	start from the beginning (as if the real hardware were just
6758	powered on).
6759
6760	If the machine is in the <link to="MachineState_Saved"/> state,
6761	it will continue its execution the point where the state has
6762	been saved.
6763
6764	<note>
6765	Unless you are trying to write a new VirtualBox front-end that
6766	performs direct machine execution (like the VirtualBox or VBoxSDL
6767	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
6768	session opened by <link to="IVirtualBox::openSession"/> and use this
6769	session only to change virtual machine settings. If you simply want to
6770	start virtual machine execution using one of the existing front-ends
6771	(for example the VirtualBox GUI or headless server), simply use
6772	<link to="IVirtualBox::openRemoteSession"/>; these front-ends will
6773	power up the machine automatically for you.
6774	</note>
6775
6776	<see>#saveState</see>
6777	<result name="VBOX_E_INVALID_VM_STATE">
6778	Virtual machine already running.
6779	</result>
6780	<result name="VBOX_E_HOST_ERROR">
6781	Host interface does not exist or name not set.
6782	</result>
6783	<result name="VBOX_E_FILE_ERROR">
6784	Invalid saved state file.
6785	</result>
6786	</desc>
6787	<param name="progress" type="IProgress" dir="return">
6788	<desc>Progress object to track the operation completion.</desc>
6789	</param>
6790	</method>
6791
6792	<method name="powerUpPaused">
6793	<desc>
6794	Identical to powerUp except that the VM will enter the
6795	<link to="MachineState_Paused"/> state, instead of
6796	<link to="MachineState_Running"/>.
6797
6798	<see>#powerUp</see>
6799	<result name="VBOX_E_INVALID_VM_STATE">
6800	Virtual machine already running.
6801	</result>
6802	<result name="VBOX_E_HOST_ERROR">
6803	Host interface does not exist or name not set.
6804	</result>
6805	<result name="VBOX_E_FILE_ERROR">
6806	Invalid saved state file.
6807	</result>
6808	</desc>
6809	<param name="progress" type="IProgress" dir="return">
6810	<desc>Progress object to track the operation completion.</desc>
6811	</param>
6812	</method>
6813
6814	<method name="powerDown">
6815	<desc>
6816	Initiates the power down procedure to stop the virtual machine
6817	execution.
6818
6819	The completion of the power down procedure is tracked using the returned
6820	IProgress object. After the operation is complete, the machine will go
6821	to the PoweredOff state.
6822	<result name="VBOX_E_INVALID_VM_STATE">
6823	Virtual machine must be Running, Paused or Stuck to be powered down.
6824	</result>
6825	</desc>
6826	<param name="progress" type="IProgress" dir="return">
6827	<desc>Progress object to track the operation completion.</desc>
6828	</param>
6829	</method>
6830
6831	<method name="reset">
6832	<desc>Resets the virtual machine.
6833	<result name="VBOX_E_INVALID_VM_STATE">
6834	Virtual machine not in Running state.
6835	</result>
6836	<result name="VBOX_E_VM_ERROR">
6837	Virtual machine error in reset operation.
6838	</result>
6839	</desc>
6840	</method>
6841
6842	<method name="pause">
6843	<desc>Pauses the virtual machine execution.
6844	<result name="VBOX_E_INVALID_VM_STATE">
6845	Virtual machine not in Running state.
6846	</result>
6847	<result name="VBOX_E_VM_ERROR">
6848	Virtual machine error in suspend operation.
6849	</result>
6850	</desc>
6851	</method>
6852
6853	<method name="resume">
6854	<desc>Resumes the virtual machine execution.
6855	<result name="VBOX_E_INVALID_VM_STATE">
6856	Virtual machine not in Paused state.
6857	</result>
6858	<result name="VBOX_E_VM_ERROR">
6859	Virtual machine error in resume operation.
6860	</result>
6861	</desc>
6862	</method>
6863
6864	<method name="powerButton">
6865	<desc>Sends the ACPI power button event to the guest.
6866	<result name="VBOX_E_INVALID_VM_STATE">
6867	Virtual machine not in Running state.
6868	</result>
6869	<result name="VBOX_E_PDM_ERROR">
6870	Controlled power off failed.
6871	</result>
6872	</desc>
6873	</method>
6874
6875	<method name="sleepButton">
6876	<desc>Sends the ACPI sleep button event to the guest.
6877	<result name="VBOX_E_INVALID_VM_STATE">
6878	Virtual machine not in Running state.
6879	</result>
6880	<result name="VBOX_E_PDM_ERROR">
6881	Sending sleep button event failed.
6882	</result>
6883	</desc>
6884	</method>
6885
6886	<method name="getPowerButtonHandled">
6887	<desc>Checks if the last power button event was handled by guest.
6888	<result name="VBOX_E_PDM_ERROR">
6889	Checking if the event was handled by the guest OS failed.
6890	</result>
6891	</desc>
6892	<param name="handled" type="boolean" dir="return"/>
6893	</method>
6894
6895	<method name="getGuestEnteredACPIMode">
6896	<desc>Checks if the guest entered the ACPI mode G0 (working) or
6897	G1 (sleeping). If this method returns @c false, the guest will
6898	most likely not respond to external ACPI events.
6899	<result name="VBOX_E_INVALID_VM_STATE">
6900	Virtual machine not in Running state.
6901	</result>
6902	</desc>
6903	<param name="entered" type="boolean" dir="return"/>
6904	</method>
6905
6906	<method name="saveState">
6907	<desc>
6908	Saves the current execution state of a running virtual machine
6909	and stops its execution.
6910
6911	After this operation completes, the machine will go to the
6912	Saved state. Next time it is powered up, this state will
6913	be restored and the machine will continue its execution from
6914	the place where it was saved.
6915
6916	This operation differs from taking a snapshot to the effect
6917	that it doesn't create new differencing media. Also, once
6918	the machine is powered up from the state saved using this method,
6919	the saved state is deleted, so it will be impossible to return
6920	to this state later.
6921
6922	<note>
6923	On success, this method implicitly calls
6924	<link to="IMachine::saveSettings"/> to save all current machine
6925	settings (including runtime changes to the DVD medium, etc.).
6926	Together with the impossibility to change any VM settings when it is
6927	in the Saved state, this guarantees adequate hardware
6928	configuration of the machine when it is restored from the saved
6929	state file.
6930	</note>
6931
6932	<note>
6933	The machine must be in the Running or Paused state, otherwise
6934	the operation will fail.
6935	</note>
6936	<result name="VBOX_E_INVALID_VM_STATE">
6937	Virtual machine state neither Running nor Paused.
6938	</result>
6939	<result name="VBOX_E_FILE_ERROR">
6940	Failed to create directory for saved state file.
6941	</result>
6942
6943	<see><link to="#takeSnapshot"/></see>
6944	</desc>
6945	<param name="progress" type="IProgress" dir="return">
6946	<desc>Progress object to track the operation completion.</desc>
6947	</param>
6948	</method>
6949
6950	<method name="adoptSavedState">
6951	<desc>
6952	Associates the given saved state file to the virtual machine.
6953
6954	On success, the machine will go to the Saved state. Next time it is
6955	powered up, it will be restored from the adopted saved state and
6956	continue execution from the place where the saved state file was
6957	created.
6958
6959	The specified saved state file path may be absolute or relative to the
6960	folder the VM normally saves the state to (usually,
6961	<link to="IMachine::snapshotFolder"/>).
6962
6963	<note>
6964	It's a caller's responsibility to make sure the given saved state
6965	file is compatible with the settings of this virtual machine that
6966	represent its virtual hardware (memory size, storage disk configuration
6967	etc.). If there is a mismatch, the behavior of the virtual machine
6968	is undefined.
6969	</note>
6970	<result name="VBOX_E_INVALID_VM_STATE">
6971	Virtual machine state neither PoweredOff nor Aborted.
6972	</result>
6973	</desc>
6974	<param name="savedStateFile" type="wstring" dir="in">
6975	<desc>Path to the saved state file to adopt.</desc>
6976	</param>
6977	</method>
6978
6979	<method name="forgetSavedState">
6980	<desc>
6981	Forgets the saved state of the virtual machine previously created
6982	by <link to="#saveState"/>. Next time the machine is powered up, a
6983	clean boot will occur. If @a remove is @c true the saved state file
6984	is deleted.
6985	<note>
6986	This operation is equivalent to resetting or powering off
6987	the machine without doing a proper shutdown in the guest OS.
6988	</note>
6989	<result name="VBOX_E_INVALID_VM_STATE">
6990	Virtual machine not in state Saved.
6991	</result>
6992	</desc>
6993	<param name="remove" type="boolean" dir="in">
6994	<desc>If @c true remove the saved state file.</desc>
6995	</param>
6996	</method>
6997
6998	<method name="getDeviceActivity">
6999	<desc>
7000	Gets the current activity type of a given device or device group.
7001	<result name="E_INVALIDARG">
7002	Invalid device type.
7003	</result>
7004	</desc>
7005	<param name="type" type="DeviceType" dir="in"/>
7006	<param name="activity" type="DeviceActivity" dir="return"/>
7007	</method>
7008
7009	<method name="attachUSBDevice">
7010	<desc>
7011	Attaches a host USB device with the given UUID to the
7012	USB controller of the virtual machine.
7013
7014	The device needs to be in one of the following states:
7015	<link to="USBDeviceState_Busy"/>,
7016	<link to="USBDeviceState_Available"/> or
7017	<link to="USBDeviceState_Held"/>,
7018	otherwise an error is immediately returned.
7019
7020	When the device state is
7021	<link to="USBDeviceState_Busy">Busy</link>, an error may also
7022	be returned if the host computer refuses to release it for some reason.
7023
7024	<see>IUSBController::deviceFilters, USBDeviceState</see>
7025	<result name="VBOX_E_INVALID_VM_STATE">
7026	Virtual machine state neither Running nor Paused.
7027	</result>
7028	<result name="VBOX_E_PDM_ERROR">
7029	Virtual machine does not have a USB controller.
7030	</result>
7031	</desc>
7032	<param name="id" type="uuid" mod="string" dir="in">
7033	<desc>UUID of the host USB device to attach.</desc>
7034	</param>
7035	</method>
7036
7037	<method name="detachUSBDevice">
7038	<desc>
7039	Detaches an USB device with the given UUID from the USB controller
7040	of the virtual machine.
7041
7042	After this method succeeds, the VirtualBox server re-initiates
7043	all USB filters as if the device were just physically attached
7044	to the host, but filters of this machine are ignored to avoid
7045	a possible automatic re-attachment.
7046
7047	<see>IUSBController::deviceFilters, USBDeviceState</see>
7048
7049	<result name="VBOX_E_PDM_ERROR">
7050	Virtual machine does not have a USB controller.
7051	</result>
7052	<result name="E_INVALIDARG">
7053	USB device not attached to this virtual machine.
7054	</result>
7055	</desc>
7056	<param name="id" type="uuid" mod="string" dir="in">
7057	<desc>UUID of the USB device to detach.</desc>
7058	</param>
7059	<param name="device" type="IUSBDevice" dir="return">
7060	<desc>Detached USB device.</desc>
7061	</param>
7062	</method>
7063
7064	<method name="findUSBDeviceByAddress">
7065	<desc>
7066	Searches for a USB device with the given host address.
7067
7068	<result name="VBOX_E_OBJECT_NOT_FOUND">
7069	Given @c name does not correspond to any USB device.
7070	</result>
7071
7072	<see>IUSBDevice::address</see>
7073	</desc>
7074	<param name="name" type="wstring" dir="in">
7075	<desc>
7076	Address of the USB device (as assigned by the host) to
7077	search for.
7078	</desc>
7079	</param>
7080	<param name="device" type="IUSBDevice" dir="return">
7081	<desc>Found USB device object.</desc>
7082	</param>
7083	</method>
7084
7085	<method name="findUSBDeviceById">
7086	<desc>
7087	Searches for a USB device with the given UUID.
7088
7089	<result name="VBOX_E_OBJECT_NOT_FOUND">
7090	Given @c id does not correspond to any USB device.
7091	</result>
7092
7093	<see>IUSBDevice::id</see>
7094	</desc>
7095	<param name="id" type="uuid" mod="string" dir="in">
7096	<desc>UUID of the USB device to search for.</desc>
7097	</param>
7098	<param name="device" type="IUSBDevice" dir="return">
7099	<desc>Found USB device object.</desc>
7100	</param>
7101	</method>
7102
7103	<method name="createSharedFolder">
7104	<desc>
7105	Creates a transient new shared folder by associating the given logical
7106	name with the given host path, adds it to the collection of shared
7107	folders and starts sharing it. Refer to the description of
7108	<link to="ISharedFolder"/> to read more about logical names.
7109
7110	<result name="VBOX_E_INVALID_VM_STATE">
7111	Virtual machine in Saved state or currently changing state.
7112	</result>
7113	<result name="VBOX_E_FILE_ERROR">
7114	Shared folder already exists or not accessible.
7115	</result>
7116	</desc>
7117	<param name="name" type="wstring" dir="in">
7118	<desc>Unique logical name of the shared folder.</desc>
7119	</param>
7120	<param name="hostPath" type="wstring" dir="in">
7121	<desc>Full path to the shared folder in the host file system.</desc>
7122	</param>
7123	<param name="writable" type="boolean" dir="in">
7124	<desc>Whether the share is writable or readonly</desc>
7125	</param>
7126	</method>
7127
7128	<method name="removeSharedFolder">
7129	<desc>
7130	Removes a transient shared folder with the given name previously
7131	created by <link to="#createSharedFolder"/> from the collection of
7132	shared folders and stops sharing it.
7133	<result name="VBOX_E_INVALID_VM_STATE">
7134	Virtual machine in Saved state or currently changing state.
7135	</result>
7136	<result name="VBOX_E_FILE_ERROR">
7137	Shared folder does not exists.
7138	</result>
7139	</desc>
7140	<param name="name" type="wstring" dir="in">
7141	<desc>Logical name of the shared folder to remove.</desc>
7142	</param>
7143	</method>
7144
7145	<method name="takeSnapshot">
7146	<desc>
7147	Saves the current execution state
7148	and all settings of the machine and creates differencing images
7149	for all normal (non-independent) media.
7150	See <link to="ISnapshot" /> for an introduction to snapshots.
7151
7152	This method can be called for a PoweredOff, Saved (see
7153	<link to="#saveState"/>), Running or
7154	Paused virtual machine. When the machine is PoweredOff, an
7155	offline snapshot is created. When the machine is Running a live
7156	snapshot is created, and an online snapshot is is created when Paused.
7157
7158	The taken snapshot is always based on the
7159	<link to="IMachine::currentSnapshot">current snapshot</link>
7160	of the associated virtual machine and becomes a new current snapshot.
7161
7162	<note>
7163	This method implicitly calls <link to="IMachine::saveSettings"/> to
7164	save all current machine settings before taking an offline snapshot.
7165	</note>
7166
7167	<result name="VBOX_E_INVALID_VM_STATE">
7168	Virtual machine currently changing state.
7169	</result>
7170	</desc>
7171	<param name="name" type="wstring" dir="in">
7172	<desc>Short name for the snapshot.</desc>
7173	</param>
7174	<param name="description" type="wstring" dir="in">
7175	<desc>Optional description of the snapshot.</desc>
7176	</param>
7177	<param name="progress" type="IProgress" dir="return">
7178	<desc>Progress object to track the operation completion.</desc>
7179	</param>
7180	</method>
7181
7182	<method name="deleteSnapshot">
7183	<desc>
7184	Starts deleting the specified snapshot asynchronously.
7185	See <link to="ISnapshot" /> for an introduction to snapshots.
7186
7187	The execution state and settings of the associated machine stored in
7188	the snapshot will be deleted. The contents of all differencing media of
7189	this snapshot will be merged with the contents of their dependent child
7190	media to keep the medium chain valid (in other words, all changes
7191	represented by media being deleted will be propagated to their child
7192	medium). After that, this snapshot's differencing medium will be
7193	deleted. The parent of this snapshot will become a new parent for all
7194	its child snapshots.
7195
7196	If the deleted snapshot is the current one, its parent snapshot will
7197	become a new current snapshot. The current machine state is not directly
7198	affected in this case, except that currently attached differencing
7199	media based on media of the deleted snapshot will be also merged as
7200	described above.
7201
7202	If the deleted snapshot is the first or current snapshot, then the
7203	respective IMachine attributes will be adjusted. Deleting the current
7204	snapshot will also implicitly call <link to="IMachine::saveSettings"/>
7205	to make all current machine settings permanent.
7206
7207	Deleting a snapshot has the following preconditions:
7208
7209	<ul>
7210	<li>Child media of all normal media of the deleted snapshot
7211	must be accessible (see <link to="IMedium::state"/>) for this
7212	operation to succeed. In particular, this means that all virtual
7213	machines, whose media are directly or indirectly based on the
7214	media of deleted snapshot, must be powered off.</li>
7215
7216	<li>You cannot delete the snapshot if a medium attached to it has
7217	more than once child medium (differencing images) because otherwise
7218	merging would be impossible. This might be the case if there is
7219	more than one child snapshot or differencing images were created
7220	for other reason (e.g. implicitly because of multiple machine
7221	attachments).</li>
7222	</ul>
7223
7224
7225	The virtual machine's <link to="IMachine::state">state</link> is changed to "DeletingSnapshot"
7226	while this operation is in progress.
7227
7228	<note>
7229	Merging medium contents can be very time and disk space
7230	consuming, if these media are big in size and have many
7231	children. However, if the snapshot being deleted is the last
7232	(head) snapshot on the branch, the operation will be rather
7233	quick.
7234	</note>
7235	<result name="VBOX_E_INVALID_VM_STATE">
7236	Virtual machine is running.
7237	</result>
7238	</desc>
7239	<param name="id" type="uuid" mod="string" dir="in">
7240	<desc>UUID of the snapshot to delete.</desc>
7241	</param>
7242	<param name="progress" type="IProgress" dir="return">
7243	<desc>Progress object to track the operation completion.</desc>
7244	</param>
7245	</method>
7246
7247	<method name="restoreSnapshot">
7248	<desc>
7249	Starts resetting the machine's current state to the state contained
7250	in the given snapshot, asynchronously. All current settings of the
7251	machine will be reset and changes stored in differencing media
7252	will be lost.
7253	See <link to="ISnapshot" /> for an introduction to snapshots.
7254
7255	After this operation is successfully completed, new empty differencing
7256	media are created for all normal media of the machine.
7257
7258	If the given snapshot is an online snapshot, the machine will go to
7259	the <link to="MachineState_Saved"> saved state</link>, so that the
7260	next time it is powered on, the execution state will be restored
7261	from the state of the snapshot.
7262
7263	<note>
7264	The machine must not be running, otherwise the operation will fail.
7265	</note>
7266
7267	<note>
7268	If the machine state is <link to="MachineState_Saved">Saved</link>
7269	prior to this operation, the saved state file will be implicitly
7270	deleted (as if <link to="IConsole::forgetSavedState"/> were
7271	called).
7272	</note>
7273
7274	<result name="VBOX_E_INVALID_VM_STATE">
7275	Virtual machine is running.
7276	</result>
7277	</desc>
7278	<param name="snapshot" type="ISnapshot" dir="in">
7279	<desc>The snapshot to restore the VM state from.</desc>
7280	</param>
7281	<param name="progress" type="IProgress" dir="return">
7282	<desc>Progress object to track the operation completion.</desc>
7283	</param>
7284	</method>
7285
7286	<method name="teleport">
7287	<desc>
7288	Teleport the VM to a different host machine or process.
7289
7290	TODO explain the details.
7291
7292	<result name="VBOX_E_INVALID_VM_STATE">
7293	Virtual machine not running or paused.
7294	</result>
7295	</desc>
7296	<param name="hostname" type="wstring" dir="in">
7297	<desc>The name or IP of the host to teleport to.</desc>
7298	</param>
7299	<param name="tcpport" type="unsigned long" dir="in">
7300	<desc>The TCP port to connect to (1..65535).</desc>
7301	</param>
7302	<param name="password" type="wstring" dir="in">
7303	<desc>The password.</desc>
7304	</param>
7305	<param name="maxDowntime" type="unsigned long" dir="in">
7306	<desc>
7307	The maximum allowed downtime given as milliseconds. 0 is not a valid
7308	value. Recommended value: 250 ms.
7309
7310	The higher the value is, the greater the chance for a successful
7311	teleportation. A small value may easily result in the teleportation
7312	process taking hours and eventually fail.
7313
7314	<note>
7315	The current implementation treats this a guideline, not as an
7316	absolute rule.
7317	</note>
7318	</desc>
7319	</param>
7320	<param name="progress" type="IProgress" dir="return">
7321	<desc>Progress object to track the operation completion.</desc>
7322	</param>
7323	</method>
7324
7325	<method name="registerCallback">
7326	<desc>
7327	Registers a new console callback on this instance. The methods of the
7328	callback interface will be called by this instance when the appropriate
7329	event occurs.
7330	</desc>
7331	<param name="callback" type="IConsoleCallback" dir="in"/>
7332	</method>
7333
7334	<method name="unregisterCallback">
7335	<desc>
7336	Unregisters the console callback previously registered using
7337	<link to="#registerCallback"/>.
7338	<result name="E_INVALIDARG">
7339	Given @a callback handler is not registered.
7340	</result>
7341	</desc>
7342	<param name="callback" type="IConsoleCallback" dir="in"/>
7343	</method>
7344	</interface>
7345
7346	<!--
7347	// IHost
7348	/////////////////////////////////////////////////////////////////////////
7349	-->
7350
7351	<enum
7352	name="HostNetworkInterfaceMediumType"
7353	uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
7354	>
7355	<desc>
7356	Type of encapsulation. Ethernet encapsulation includes both wired and
7357	wireless Ethernet connections.
7358	<see>IHostNetworkInterface</see>
7359	</desc>
7360
7361	<const name="Unknown" value="0">
7362	<desc>
7363	The type of interface cannot be determined.
7364	</desc>
7365	</const>
7366	<const name="Ethernet" value="1">
7367	<desc>
7368	Ethernet frame encapsulation.
7369	</desc>
7370	</const>
7371	<const name="PPP" value="2">
7372	<desc>
7373	Point-to-point protocol encapsulation.
7374	</desc>
7375	</const>
7376	<const name="SLIP" value="3">
7377	<desc>
7378	Serial line IP encapsulation.
7379	</desc>
7380	</const>
7381	</enum>
7382
7383	<enum
7384	name="HostNetworkInterfaceStatus"
7385	uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
7386	>
7387	<desc>
7388	Current status of the interface.
7389	<see>IHostNetworkInterface</see>
7390	</desc>
7391
7392	<const name="Unknown" value="0">
7393	<desc>
7394	The state of interface cannot be determined.
7395	</desc>
7396	</const>
7397	<const name="Up" value="1">
7398	<desc>
7399	The interface is fully operational.
7400	</desc>
7401	</const>
7402	<const name="Down" value="2">
7403	<desc>
7404	The interface is not functioning.
7405	</desc>
7406	</const>
7407	</enum>
7408
7409	<enum
7410	name="HostNetworkInterfaceType"
7411	uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
7412	>
7413	<desc>
7414	Network interface type.
7415	</desc>
7416	<const name="Bridged" value="1"/>
7417	<const name="HostOnly" value="2"/>
7418	</enum>
7419
7420	<interface
7421	name="IHostNetworkInterface" extends="$unknown"
7422	uuid="ce6fae58-7642-4102-b5db-c9005c2320a8"
7423	wsmap="managed"
7424	>
7425	<desc>
7426	Represents one of host's network interfaces. IP V6 address and network
7427	mask are strings of 32 hexdecimal digits grouped by four. Groups are
7428	separated by colons.
7429	For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
7430	</desc>
7431	<attribute name="name" type="wstring" readonly="yes">
7432	<desc>Returns the host network interface name.</desc>
7433	</attribute>
7434
7435	<attribute name="id" type="uuid" mod="string" readonly="yes">
7436	<desc>Returns the interface UUID.</desc>
7437	</attribute>
7438
7439	<attribute name="networkName" type="wstring" readonly="yes">
7440	<desc>Returns the name of a virtual network the interface gets attached to.</desc>
7441	</attribute>
7442
7443	<attribute name="dhcpEnabled" type="boolean" readonly="yes">
7444	<desc>Specifies whether the DHCP is enabled for the interface.</desc>
7445	</attribute>
7446
7447	<attribute name="IPAddress" type="wstring" readonly="yes">
7448	<desc>Returns the IP V4 address of the interface.</desc>
7449	</attribute>
7450
7451	<attribute name="networkMask" type="wstring" readonly="yes">
7452	<desc>Returns the network mask of the interface.</desc>
7453	</attribute>
7454
7455	<attribute name="IPV6Supported" type="boolean" readonly="yes">
7456	<desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
7457	</attribute>
7458
7459	<attribute name="IPV6Address" type="wstring" readonly="yes">
7460	<desc>Returns the IP V6 address of the interface.</desc>
7461	</attribute>
7462
7463	<attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
7464	<desc>Returns the length IP V6 network mask prefix of the interface.</desc>
7465	</attribute>
7466
7467	<attribute name="hardwareAddress" type="wstring" readonly="yes">
7468	<desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
7469	</attribute>
7470
7471	<attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
7472	<desc>Type of protocol encapsulation used.</desc>
7473	</attribute>
7474
7475	<attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
7476	<desc>Status of the interface.</desc>
7477	</attribute>
7478
7479	<attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
7480	<desc>specifies the host interface type.</desc>
7481	</attribute>
7482
7483	<method name="enableStaticIpConfig">
7484	<desc>sets and enables the static IP V4 configuration for the given interface.</desc>
7485	<param name="IPAddress" type="wstring" dir="in">
7486	<desc>
7487	IP address.
7488	</desc>
7489	</param>
7490	<param name="networkMask" type="wstring" dir="in">
7491	<desc>
7492	network mask.
7493	</desc>
7494	</param>
7495	</method>
7496
7497	<method name="enableStaticIpConfigV6">
7498	<desc>sets and enables the static IP V6 configuration for the given interface.</desc>
7499	<param name="IPV6Address" type="wstring" dir="in">
7500	<desc>
7501	IP address.
7502	</desc>
7503	</param>
7504	<param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
7505	<desc>
7506	network mask.
7507	</desc>
7508	</param>
7509	</method>
7510
7511	<method name="enableDynamicIpConfig">
7512	<desc>enables the dynamic IP configuration.</desc>
7513	</method>
7514
7515	<method name="dhcpRediscover">
7516	<desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
7517	</method>
7518
7519	</interface>
7520
7521	<interface
7522	name="IHost" extends="$unknown"
7523	uuid="e380cbfc-ae65-4fa6-899e-45ded6b3132a"
7524	wsmap="managed"
7525	>
7526	<desc>
7527	The IHost interface represents the physical machine that this VirtualBox
7528	installation runs on.
7529
7530	An object implementing this interface is returned by the
7531	<link to="IVirtualBox::host" /> attribute. This interface contains
7532	read-only information about the host's physical hardware (such as what
7533	processors and disks are available, what the host operating system is,
7534	and so on) and also allows for manipulating some of the host's hardware,
7535	such as global USB device filters and host interface networking.
7536
7537	</desc>
7538	<attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
7539	<desc>List of DVD drives available on the host.</desc>
7540	</attribute>
7541
7542	<attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
7543	<desc>List of floppy drives available on the host.</desc>
7544	</attribute>
7545
7546	<attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
7547	<desc>
7548	List of USB devices currently attached to the host.
7549	Once a new device is physically attached to the host computer,
7550	it appears in this list and remains there until detached.
7551
7552	<note>
7553	If USB functionality is not available in the given edition of
7554	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7555	</note>
7556	</desc>
7557	</attribute>
7558
7559	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
7560	<desc>
7561	List of USB device filters in action.
7562	When a new device is physically attached to the host computer,
7563	filters from this list are applied to it (in order they are stored
7564	in the list). The first matched filter will determine the
7565	<link to="IHostUSBDeviceFilter::action">action</link>
7566	performed on the device.
7567
7568	Unless the device is ignored by these filters, filters of all
7569	currently running virtual machines
7570	(<link to="IUSBController::deviceFilters"/>) are applied to it.
7571
7572	<note>
7573	If USB functionality is not available in the given edition of
7574	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7575	</note>
7576
7577	<see>IHostUSBDeviceFilter, USBDeviceState</see>
7578	</desc>
7579	</attribute>
7580
7581	<attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
7582	<desc>List of host network interfaces currently defined on the host.</desc>
7583	</attribute>
7584
7585	<attribute name="processorCount" type="unsigned long" readonly="yes">
7586	<desc>Number of (logical) CPUs installed in the host system.</desc>
7587	</attribute>
7588
7589	<attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
7590	<desc>Number of (logical) CPUs online in the host system.</desc>
7591	</attribute>
7592
7593	<method name="getProcessorSpeed">
7594	<desc>Query the (approximate) maximum speed of a specified host CPU in
7595	Megahertz.
7596	</desc>
7597	<param name="cpuId" type="unsigned long" dir="in">
7598	<desc>
7599	Identifier of the CPU.
7600	</desc>
7601	</param>
7602	<param name="speed" type="unsigned long" dir="return">
7603	<desc>
7604	Speed value. 0 is returned if value is not known or @a cpuId is
7605	invalid.
7606	</desc>
7607	</param>
7608	</method>
7609
7610	<method name="getProcessorFeature">
7611	<desc>Query whether a CPU feature is supported or not.</desc>
7612	<param name="feature" type="ProcessorFeature" dir="in">
7613	<desc>
7614	CPU Feature identifier.
7615	</desc>
7616	</param>
7617	<param name="supported" type="boolean" dir="return">
7618	<desc>
7619	Feature is supported or not.
7620	</desc>
7621	</param>
7622	</method>
7623
7624	<method name="getProcessorDescription">
7625	<desc>Query the model string of a specified host CPU.
7626	</desc>
7627	<param name="cpuId" type="unsigned long" dir="in">
7628	<desc>
7629	Identifier of the CPU.
7630	<note>
7631	The current implementation might not necessarily return the
7632	description for this exact CPU.
7633	</note>
7634	</desc>
7635	</param>
7636	<param name="description" type="wstring" dir="return">
7637	<desc>
7638	Model string. An empty string is returned if value is not known or
7639	@a cpuId is invalid.
7640	</desc>
7641	</param>
7642	</method>
7643
7644	<method name="getProcessorCPUIDLeaf">
7645	<desc>
7646	Returns the CPU cpuid information for the specified leaf.
7647	</desc>
7648	<param name="cpuId" type="unsigned long" dir="in">
7649	<desc>
7650	Identifier of the CPU. The CPU most be online.
7651	<note>
7652	The current implementation might not necessarily return the
7653	description for this exact CPU.
7654	</note>
7655	</desc>
7656	</param>
7657	<param name="leaf" type="unsigned long" dir="in">
7658	<desc>
7659	CPUID leaf index (eax).
7660	</desc>
7661	</param>
7662	<param name="subLeaf" type="unsigned long" dir="in">
7663	<desc>
7664	CPUID leaf sub index (ecx). This currently only applies to cache
7665	information on Intel CPUs. Use 0 if retriving values for
7666	<link to="IMachine::setCPUIDLeaf"/>.
7667	</desc>
7668	</param>
7669	<param name="valEax" type="unsigned long" dir="out">
7670	<desc>
7671	CPUID leaf value for register eax.
7672	</desc>
7673	</param>
7674	<param name="valEbx" type="unsigned long" dir="out">
7675	<desc>
7676	CPUID leaf value for register ebx.
7677	</desc>
7678	</param>
7679	<param name="valEcx" type="unsigned long" dir="out">
7680	<desc>
7681	CPUID leaf value for register ecx.
7682	</desc>
7683	</param>
7684	<param name="valEdx" type="unsigned long" dir="out">
7685	<desc>
7686	CPUID leaf value for register edx.
7687	</desc>
7688	</param>
7689	</method>
7690
7691	<attribute name="memorySize" type="unsigned long" readonly="yes">
7692	<desc>Amount of system memory in megabytes installed in the host system.</desc>
7693	</attribute>
7694
7695	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
7696	<desc>Available system memory in the host system.</desc>
7697	</attribute>
7698
7699	<attribute name="operatingSystem" type="wstring" readonly="yes">
7700	<desc>Name of the host system's operating system.</desc>
7701	</attribute>
7702
7703	<attribute name="OSVersion" type="wstring" readonly="yes">
7704	<desc>Host operating system's version string.</desc>
7705	</attribute>
7706
7707	<attribute name="UTCTime" type="long long" readonly="yes">
7708	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
7709	</attribute>
7710
7711	<attribute name="Acceleration3DAvailable" type="boolean" readonly="yes">
7712	<desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
7713	</attribute>
7714
7715	<method name="createHostOnlyNetworkInterface">
7716	<desc>
7717	Creates a new adapter for Host Only Networking.
7718	<result name="E_INVALIDARG">
7719	Host network interface @a name already exists.
7720	</result>
7721	</desc>
7722	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
7723	<desc>
7724	Created host interface object.
7725	</desc>
7726	</param>
7727	<param name="progress" type="IProgress" dir="return">
7728	<desc>
7729	Progress object to track the operation completion.
7730	</desc>
7731	</param>
7732	</method>
7733
7734	<method name="removeHostOnlyNetworkInterface">
7735	<desc>
7736	Removes the given Host Only Networking interface.
7737	<result name="VBOX_E_OBJECT_NOT_FOUND">
7738	No host network interface matching @a id found.
7739	</result>
7740	</desc>
7741	<param name="id" type="uuid" mod="string" dir="in">
7742	<desc>
7743	Adapter GUID.
7744	</desc>
7745	</param>
7746	<param name="progress" type="IProgress" dir="return">
7747	<desc>
7748	Progress object to track the operation completion.
7749	</desc>
7750	</param>
7751	</method>
7752
7753	<method name="createUSBDeviceFilter">
7754	<desc>
7755	Creates a new USB device filter. All attributes except
7756	the filter name are set to empty (any match),
7757	<i>active</i> is @c false (the filter is not active).
7758
7759	The created filter can be added to the list of filters using
7760	<link to="#insertUSBDeviceFilter"/>.
7761
7762	<see>#USBDeviceFilters</see>
7763	</desc>
7764	<param name="name" type="wstring" dir="in">
7765	<desc>
7766	Filter name. See <link to="IHostUSBDeviceFilter::name"/>
7767	for more info.
7768	</desc>
7769	</param>
7770	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
7771	<desc>Created filter object.</desc>
7772	</param>
7773	</method>
7774
7775	<method name="insertUSBDeviceFilter">
7776	<desc>
7777	Inserts the given USB device to the specified position
7778	in the list of filters.
7779
7780	Positions are numbered starting from @c 0. If the specified
7781	position is equal to or greater than the number of elements in
7782	the list, the filter is added at the end of the collection.
7783
7784	<note>
7785	Duplicates are not allowed, so an attempt to insert a
7786	filter already in the list is an error.
7787	</note>
7788	<note>
7789	If USB functionality is not available in the given edition of
7790	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7791	</note>
7792
7793	<see>#USBDeviceFilters</see>
7794
7795	<result name="VBOX_E_INVALID_OBJECT_STATE">
7796	USB device filter is not created within this VirtualBox instance.
7797	</result>
7798	<result name="E_INVALIDARG">
7799	USB device filter already in list.
7800	</result>
7801
7802	</desc>
7803	<param name="position" type="unsigned long" dir="in">
7804	<desc>Position to insert the filter to.</desc>
7805	</param>
7806	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
7807	<desc>USB device filter to insert.</desc>
7808	</param>
7809	</method>
7810
7811	<method name="removeUSBDeviceFilter">
7812	<desc>
7813	Removes a USB device filter from the specified position in the
7814	list of filters.
7815
7816	Positions are numbered starting from @c 0. Specifying a
7817	position equal to or greater than the number of elements in
7818	the list will produce an error.
7819
7820	<note>
7821	If USB functionality is not available in the given edition of
7822	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7823	</note>
7824
7825	<see>#USBDeviceFilters</see>
7826
7827	<result name="E_INVALIDARG">
7828	USB device filter list empty or invalid @a position.
7829	</result>
7830
7831	</desc>
7832	<param name="position" type="unsigned long" dir="in">
7833	<desc>Position to remove the filter from.</desc>
7834	</param>
7835	</method>
7836
7837	<method name="findHostDVDDrive">
7838	<desc>
7839	Searches for a host DVD drive with the given @c name.
7840
7841	<result name="VBOX_E_OBJECT_NOT_FOUND">
7842	Given @c name does not correspond to any host drive.
7843	</result>
7844
7845	</desc>
7846	<param name="name" type="wstring" dir="in">
7847	<desc>Name of the host drive to search for</desc>
7848	</param>
7849	<param name="drive" type="IMedium" dir="return">
7850	<desc>Found host drive object</desc>
7851	</param>
7852	</method>
7853
7854	<method name="findHostFloppyDrive">
7855	<desc>
7856	Searches for a host floppy drive with the given @c name.
7857
7858	<result name="VBOX_E_OBJECT_NOT_FOUND">
7859	Given @c name does not correspond to any host floppy drive.
7860	</result>
7861
7862	</desc>
7863	<param name="name" type="wstring" dir="in">
7864	<desc>Name of the host floppy drive to search for</desc>
7865	</param>
7866	<param name="drive" type="IMedium" dir="return">
7867	<desc>Found host floppy drive object</desc>
7868	</param>
7869	</method>
7870
7871	<method name="findHostNetworkInterfaceByName">
7872	<desc>
7873	Searches through all host network interfaces for an interface with
7874	the given @c name.
7875	<note>
7876	The method returns an error if the given @c name does not
7877	correspond to any host network interface.
7878	</note>
7879	</desc>
7880	<param name="name" type="wstring" dir="in">
7881	<desc>Name of the host network interface to search for.</desc>
7882	</param>
7883	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
7884	<desc>Found host network interface object.</desc>
7885	</param>
7886	</method>
7887	<method name="findHostNetworkInterfaceById">
7888	<desc>
7889	Searches through all host network interfaces for an interface with
7890	the given GUID.
7891	<note>
7892	The method returns an error if the given GUID does not
7893	correspond to any host network interface.
7894	</note>
7895	</desc>
7896	<param name="id" type="uuid" mod="string" dir="in">
7897	<desc>GUID of the host network interface to search for.</desc>
7898	</param>
7899	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
7900	<desc>Found host network interface object.</desc>
7901	</param>
7902	</method>
7903	<method name="findHostNetworkInterfacesOfType">
7904	<desc>
7905	Searches through all host network interfaces and returns a list of interfaces of the specified type
7906	</desc>
7907	<param name="type" type="HostNetworkInterfaceType" dir="in">
7908	<desc>type of the host network interfaces to search for.</desc>
7909	</param>
7910	<param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
7911	<desc>Found host network interface objects.</desc>
7912	</param>
7913	</method>
7914
7915	<method name="findUSBDeviceById">
7916	<desc>
7917	Searches for a USB device with the given UUID.
7918
7919	<result name="VBOX_E_OBJECT_NOT_FOUND">
7920	Given @c id does not correspond to any USB device.
7921	</result>
7922
7923	<see>IHostUSBDevice::id</see>
7924	</desc>
7925	<param name="id" type="uuid" mod="string" dir="in">
7926	<desc>UUID of the USB device to search for.</desc>
7927	</param>
7928	<param name="device" type="IHostUSBDevice" dir="return">
7929	<desc>Found USB device object.</desc>
7930	</param>
7931	</method>
7932
7933	<method name="findUSBDeviceByAddress">
7934	<desc>
7935	Searches for a USB device with the given host address.
7936
7937	<result name="VBOX_E_OBJECT_NOT_FOUND">
7938	Given @c name does not correspond to any USB device.
7939	</result>
7940
7941	<see>IHostUSBDevice::address</see>
7942	</desc>
7943	<param name="name" type="wstring" dir="in">
7944	<desc>
7945	Address of the USB device (as assigned by the host) to
7946	search for.
7947	</desc>
7948	</param>
7949	<param name="device" type="IHostUSBDevice" dir="return">
7950	<desc>Found USB device object.</desc>
7951	</param>
7952	</method>
7953
7954	</interface>
7955
7956	<!--
7957	// ISystemProperties
7958	/////////////////////////////////////////////////////////////////////////
7959	-->
7960
7961	<interface
7962	name="ISystemProperties"
7963	extends="$unknown"
7964	uuid="07c3ffd8-8f59-49cc-b608-53a332e85cc3"
7965	wsmap="managed"
7966	>
7967	<desc>
7968	The ISystemProperties interface represents global properties of the given
7969	VirtualBox installation.
7970
7971	These properties define limits and default values for various attributes
7972	and parameters. Most of the properties are read-only, but some can be
7973	changed by a user.
7974	</desc>
7975
7976	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
7977	<desc>Minimum guest system memory in Megabytes.</desc>
7978	</attribute>
7979
7980	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
7981	<desc>Maximum guest system memory in Megabytes.</desc>
7982	</attribute>
7983
7984	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
7985	<desc>Minimum guest video memory in Megabytes.</desc>
7986	</attribute>
7987
7988	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
7989	<desc>Maximum guest video memory in Megabytes.</desc>
7990	</attribute>
7991
7992	<attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
7993	<desc>Minimum CPU count.</desc>
7994	</attribute>
7995
7996	<attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
7997	<desc>Maximum CPU count.</desc>
7998	</attribute>
7999
8000	<attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
8001	<desc>Maximum of monitors which could be connected.</desc>
8002	</attribute>
8003
8004	<attribute name="maxVDISize" type="unsigned long long" readonly="yes">
8005	<desc>Maximum size of a virtual disk image in Megabytes.</desc>
8006	</attribute>
8007
8008	<attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
8009	<desc>
8010	Number of network adapters associated with every
8011	<link to="IMachine"/> instance.
8012	</desc>
8013	</attribute>
8014
8015	<attribute name="serialPortCount" type="unsigned long" readonly="yes">
8016	<desc>
8017	Number of serial ports associated with every
8018	<link to="IMachine"/> instance.
8019	</desc>
8020	</attribute>
8021
8022	<attribute name="parallelPortCount" type="unsigned long" readonly="yes">
8023	<desc>
8024	Number of parallel ports associated with every
8025	<link to="IMachine"/> instance.
8026	</desc>
8027	</attribute>
8028
8029	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
8030	<desc>
8031	Maximum device position in the boot order. This value corresponds
8032	to the total number of devices a machine can boot from, to make it
8033	possible to include all possible devices to the boot list.
8034	<see><link to="IMachine::setBootOrder"/></see>
8035	</desc>
8036	</attribute>
8037
8038	<attribute name="defaultMachineFolder" type="wstring">
8039	<desc>
8040	Full path to the default directory used to create new or open
8041	existing machines when a settings file name contains no
8042	path.
8043
8044	The initial value of this property is
8045	<tt><</tt><link to="IVirtualBox::homeFolder">
8046	VirtualBox_home</link><tt>>/Machines</tt>.
8047
8048	<note>
8049	Setting this property to @c null or an empty string will restore the
8050	initial value.
8051	</note>
8052	<note>
8053	When settings this property, the specified path can be
8054	absolute (full path) or relative
8055	to the <link to="IVirtualBox::homeFolder">
8056	VirtualBox home directory</link>.
8057	When reading this property, a full path is
8058	always returned.
8059	</note>
8060	<note>
8061	The specified path may not exist, it will be created
8062	when necessary.
8063	</note>
8064
8065	<see>
8066	<link to="IVirtualBox::createMachine"/>,
8067	<link to="IVirtualBox::openMachine"/>
8068	</see>
8069	</desc>
8070	</attribute>
8071
8072	<attribute name="defaultHardDiskFolder" type="wstring">
8073	<desc>
8074	Full path to the default directory used to create new or open existing
8075	virtual disks.
8076
8077	This path is used when the storage unit of a hard disk is a regular file
8078	in the host's file system and only a file name that contains no path is
8079	given.
8080
8081	The initial value of this property is
8082	<tt><</tt>
8083	<link to="IVirtualBox::homeFolder">VirtualBox_home</link>
8084	<tt>>/HardDisks</tt>.
8085
8086	<note>
8087	Setting this property to @c null or empty string will restore the
8088	initial value.
8089	</note>
8090	<note>
8091	When settings this property, the specified path can be relative
8092	to the
8093	<link to="IVirtualBox::homeFolder">VirtualBox home directory</link> or
8094	absolute. When reading this property, a full path is
8095	always returned.
8096	</note>
8097	<note>
8098	The specified path may not exist, it will be created
8099	when necessary.
8100	</note>
8101
8102	<see>
8103	IMedium,
8104	<link to="IVirtualBox::createHardDisk"/>,
8105	<link to="IVirtualBox::openHardDisk"/>,
8106	<link to="IMedium::location"/>
8107	</see>
8108	</desc>
8109	</attribute>
8110
8111	<attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
8112	<desc>
8113	List of all medium storage formats supported by this VirtualBox
8114	installation.
8115
8116	Keep in mind that the medium format identifier
8117	(<link to="IMediumFormat::id"/>) used in other API calls like
8118	<link to="IVirtualBox::createHardDisk"/> to refer to a particular
8119	medium format is a case-insensitive string. This means that, for
8120	example, all of the following strings:
8121	<pre>
8122	"VDI"
8123	"vdi"
8124	"VdI"</pre>
8125	refer to the same medium format.
8126
8127	Note that the virtual medium framework is backend-based, therefore
8128	the list of supported formats depends on what backends are currently
8129	installed.
8130
8131	<see>
8132	<link to="IMediumFormat"/>,
8133	</see>
8134	</desc>
8135	</attribute>
8136
8137	<attribute name="defaultHardDiskFormat" type="wstring">
8138	<desc>
8139	Identifier of the default medium format used by VirtualBox.
8140
8141	The medium format set by this attribute is used by VirtualBox
8142	when the medium format was not specified explicitly. One example is
8143	<link to="IVirtualBox::createHardDisk"/> with the empty
8144	format argument. A more complex example is implicit creation of
8145	differencing media when taking a snapshot of a virtual machine:
8146	this operation will try to use a format of the parent medium first
8147	and if this format does not support differencing media the default
8148	format specified by this argument will be used.
8149
8150	The list of supported medium formats may be obtained by the
8151	<link to="#mediaFormats"/> call. Note that the default medium
8152	format must have a capability to create differencing media;
8153	otherwise operations that create media implicitly may fail
8154	unexpectedly.
8155
8156	The initial value of this property is <tt>"VDI"</tt> in the current
8157	version of the VirtualBox product, but may change in the future.
8158
8159	<note>
8160	Setting this property to @c null or empty string will restore the
8161	initial value.
8162	</note>
8163
8164	<see>
8165	<link to="#mediaFormats"/>,
8166	<link to="IMediumFormat::id"/>,
8167	<link to="IVirtualBox::createHardDisk"/>
8168	</see>
8169	</desc>
8170	</attribute>
8171
8172	<attribute name="freeDiskSpaceWarning" type="unsigned long long">
8173	<desc>Issue a warning if the free disk space is below (or in some disk
8174	intensive operation is expected to go below) the given size in
8175	Megabytes.</desc>
8176	</attribute>
8177
8178	<attribute name="freeDiskSpacePercentWarning" type="unsigned long">
8179	<desc>Issue a warning if the free disk space is below (or in some disk
8180	intensive operation is expected to go below) the given percentage.</desc>
8181	</attribute>
8182
8183	<attribute name="freeDiskSpaceError" type="unsigned long long">
8184	<desc>Issue an error if the free disk space is below (or in some disk
8185	intensive operation is expected to go below) the given size in
8186	Megabytes.</desc>
8187	</attribute>
8188
8189	<attribute name="freeDiskSpacePercentError" type="unsigned long">
8190	<desc>Issue an error if the free disk space is below (or in some disk
8191	intensive operation is expected to go below) the given percentage.</desc>
8192	</attribute>
8193
8194	<attribute name="remoteDisplayAuthLibrary" type="wstring">
8195	<desc>
8196	Library that provides authentication for VRDP clients. The library
8197	is used if a virtual machine's authentication type is set to "external"
8198	in the VM RemoteDisplay configuration.
8199
8200	The system library extension (".DLL" or ".so") must be omitted.
8201	A full path can be specified; if not, then the library must reside on the
8202	system's default library path.
8203
8204	The default value of this property is <tt>"VRDPAuth"</tt>. There is a library
8205	of that name in one of the default VirtualBox library directories.
8206
8207	For details about VirtualBox authentication libraries and how to implement
8208	them, please refer to the VirtualBox manual.
8209
8210	<note>
8211	Setting this property to @c null or empty string will restore the
8212	initial value.
8213	</note>
8214	</desc>
8215	</attribute>
8216
8217	<attribute name="webServiceAuthLibrary" type="wstring">
8218	<desc>
8219	Library that provides authentication for webservice clients. The library
8220	is used if a virtual machine's authentication type is set to "external"
8221	in the VM RemoteDisplay configuration and will be called from
8222	within the <link to="IWebsessionManager::logon" /> implementation.
8223
8224	As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
8225	there is no per-VM setting for this, as the webservice is a global
8226	resource (if it is running). Only for this setting (for the webservice),
8227	setting this value to a literal <tt>"null"</tt> string disables authentication,
8228	meaning that <link to="IWebsessionManager::logon" /> will always succeed,
8229	no matter what user name and password are supplied.
8230
8231	The initial value of this property is <tt>"VRDPAuth"</tt>,
8232	meaning that the webservice will use the same authentication
8233	library that is used by default for VBoxVRDP (again, see
8234	<link to="ISystemProperties::remoteDisplayAuthLibrary" />).
8235	The format and calling convention of authentication libraries
8236	is the same for the webservice as it is for VBoxVRDP.
8237
8238	<note>
8239	Setting this property to @c null or empty string will restore the
8240	initial value.
8241	</note>
8242	</desc>
8243	</attribute>
8244
8245	<attribute name="LogHistoryCount" type="unsigned long">
8246	<desc>
8247	This value specifies how many old release log files are kept.
8248	</desc>
8249	</attribute>
8250
8251	<attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
8252	<desc>This value hold the default audio driver for the current
8253	system.</desc>
8254	</attribute>
8255
8256	<method name="getMaxDevicesPerPortForStorageBus">
8257	<desc>Returns the maximum number of devices which can be attached to a port
8258	for the given storage bus.</desc>
8259
8260	<param name="bus" type="StorageBus" dir="in">
8261	<desc>The storage bus type to get the value for.</desc>
8262	</param>
8263
8264	<param name="maxDevicesPerPort" type="unsigned long" dir="return">
8265	<desc>The maximum number of devices which can eb attached to the port for the given
8266	storage bus.</desc>
8267	</param>
8268	</method>
8269
8270	<method name="getMinPortCountForStorageBus">
8271	<desc>Returns the minimum number of ports the given storage bus supports.</desc>
8272
8273	<param name="bus" type="StorageBus" dir="in">
8274	<desc>The storage bus type to get the value for.</desc>
8275	</param>
8276
8277	<param name="minPortCount" type="unsigned long" dir="return">
8278	<desc>The minimum number of ports for the given storage bus.</desc>
8279	</param>
8280	</method>
8281
8282	<method name="getMaxPortCountForStorageBus">
8283	<desc>Returns the maximum number of ports the given storage bus supports.</desc>
8284
8285	<param name="bus" type="StorageBus" dir="in">
8286	<desc>The storage bus type to get the value for.</desc>
8287	</param>
8288
8289	<param name="maxPortCount" type="unsigned long" dir="return">
8290	<desc>The maximum number of ports for the given storage bus.</desc>
8291	</param>
8292	</method>
8293
8294	<method name="getMaxInstancesOfStorageBus">
8295	<desc>Returns the maximum number of storage bus instances which
8296	can be configured for each VM. This corresponds to the number of
8297	storage controllers one can have.</desc>
8298
8299	<param name="bus" type="StorageBus" dir="in">
8300	<desc>The storage bus type to get the value for.</desc>
8301	</param>
8302
8303	<param name="maxInstances" type="unsigned long" dir="return">
8304	<desc>The maximum number of instances for the given storage bus.</desc>
8305	</param>
8306	</method>
8307
8308	<method name="getDeviceTypesForStorageBus">
8309	<desc>Returns list of all the supported device types
8310	(<link to="DeviceType"/>) for the given type of storage
8311	bus.</desc>
8312
8313	<param name="bus" type="StorageBus" dir="in">
8314	<desc>The storage bus type to get the value for.</desc>
8315	</param>
8316
8317	<param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
8318	<desc>The list of all supported device types for the given storage bus.</desc>
8319	</param>
8320	</method>
8321	</interface>
8322
8323	<!--
8324	// IGuest
8325	/////////////////////////////////////////////////////////////////////////
8326	-->
8327
8328	<interface
8329	name="IGuestOSType" extends="$unknown"
8330	uuid="8aa950f6-668c-4388-b251-3809b404e862"
8331	wsmap="struct"
8332	>
8333	<desc>
8334	</desc>
8335
8336	<attribute name="familyId" type="wstring" readonly="yes">
8337	<desc>Guest OS family identifier string.</desc>
8338	</attribute>
8339
8340	<attribute name="familyDescription" type="wstring" readonly="yes">
8341	<desc>Human readable description of the guest OS family.</desc>
8342	</attribute>
8343
8344	<attribute name="id" type="wstring" readonly="yes">
8345	<desc>Guest OS identifier string.</desc>
8346	</attribute>
8347
8348	<attribute name="description" type="wstring" readonly="yes">
8349	<desc>Human readable description of the guest OS.</desc>
8350	</attribute>
8351
8352	<attribute name="is64Bit" type="boolean" readonly="yes">
8353	<desc>Returns @c true if the given OS is 64-bit</desc>
8354	</attribute>
8355
8356	<attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
8357	<desc>Returns @c true if IO APIC recommended for this OS type.</desc>
8358	</attribute>
8359
8360	<attribute name="recommendedVirtEx" type="boolean" readonly="yes">
8361	<desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
8362	</attribute>
8363
8364	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
8365	<desc>Recommended RAM size in Megabytes.</desc>
8366	</attribute>
8367
8368	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
8369	<desc>Recommended video RAM size in Megabytes.</desc>
8370	</attribute>
8371
8372	<attribute name="recommendedHDD" type="unsigned long" readonly="yes">
8373	<desc>Recommended hard disk size in Megabytes.</desc>
8374	</attribute>
8375
8376	<attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
8377	<desc>Returns recommended network adapter for this OS type.</desc>
8378	</attribute>
8379
8380	<attribute name="recommendedPae" type="boolean" readonly="yes">
8381	<desc>Returns @c true if using PAE is recommended for this OS type.</desc>
8382	</attribute>
8383
8384	<attribute name="recommendedDvdStorageController" type="StorageControllerType" readonly="yes">
8385	<desc>Recommended storage controller type for DVD/CD drives.</desc>
8386	</attribute>
8387
8388	<attribute name="recommendedDvdStorageBus" type="StorageBus" readonly="yes">
8389	<desc>Recommended storage bus type for DVD/CD drives.</desc>
8390	</attribute>
8391
8392	<attribute name="recommendedHdStorageController" type="StorageControllerType" readonly="yes">
8393	<desc>Recommended storage controller type for HD drives.</desc>
8394	</attribute>
8395
8396	<attribute name="recommendedHdStorageBus" type="StorageBus" readonly="yes">
8397	<desc>Recommended storage bus type for HD drives.</desc>
8398	</attribute>
8399
8400	<attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
8401	<desc>Recommended firmware type.</desc>
8402	</attribute>
8403
8404	<attribute name="recommendedUsbHid" type="boolean" readonly="yes">
8405	<desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
8406	</attribute>
8407
8408	<attribute name="recommendedHpet" type="boolean" readonly="yes">
8409	<desc>Returns @c true if using HPET is recommended for this OS type.</desc>
8410	</attribute>
8411
8412	<attribute name="recommendedUsbTablet" type="boolean" readonly="yes">
8413	<desc>Returns @c true if using a USB Tablet is recommended.</desc>
8414	</attribute>
8415
8416	<attribute name="recommendedRtcUseUtc" type="boolean" readonly="yes">
8417	<desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
8418	</attribute>
8419
8420	</interface>
8421
8422	<interface
8423	name="IGuest" extends="$unknown"
8424	uuid="d073545f-9635-489e-b36f-d468a10f8987"
8425	wsmap="managed"
8426	>
8427	<desc>
8428	The IGuest interface represents information about the operating system
8429	running inside the virtual machine. Used in
8430	<link to="IConsole::guest"/>.
8431
8432	IGuest provides information about the guest operating system, whether
8433	Guest Additions are installed and other OS-specific virtual machine
8434	properties.
8435	</desc>
8436
8437	<attribute name="OSTypeId" type="wstring" readonly="yes">
8438	<desc>
8439	Identifier of the Guest OS type as reported by the Guest
8440	Additions.
8441	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
8442	an IGuestOSType object representing details about the given
8443	Guest OS type.
8444	<note>
8445	If Guest Additions are not installed, this value will be
8446	the same as <link to="IMachine::OSTypeId"/>.
8447	</note>
8448	</desc>
8449	</attribute>
8450
8451	<attribute name="additionsActive" type="boolean" readonly="yes">
8452	<desc>
8453	Flag whether the Guest Additions are installed and active
8454	in which case their version will be returned by the
8455	<link to="#additionsVersion"/> property.
8456	</desc>
8457	</attribute>
8458
8459	<attribute name="additionsVersion" type="wstring" readonly="yes">
8460	<desc>
8461	Version of the Guest Additions (3 decimal numbers separated
8462	by dots) or empty when the Additions are not installed. The
8463	Additions may also report a version but yet not be active as
8464	the version might be refused by VirtualBox (incompatible) or
8465	other failures occurred.
8466	</desc>
8467	</attribute>
8468
8469	<attribute name="supportsSeamless" type="boolean" readonly="yes">
8470	<desc>
8471	Flag whether seamless guest display rendering (seamless desktop
8472	integration) is supported.
8473	</desc>
8474	</attribute>
8475
8476	<attribute name="supportsGraphics" type="boolean" readonly="yes">
8477	<desc>
8478	Flag whether the guest is in graphics mode. If it is not, then
8479	seamless rendering will not work, resize hints are not immediately
8480	acted on and guest display resizes are probably not initiated by
8481	the guest additions.
8482	</desc>
8483	</attribute>
8484
8485	<attribute name="memoryBalloonSize" type="unsigned long">
8486	<desc>Guest system memory balloon size in megabytes (transient property).</desc>
8487	</attribute>
8488
8489	<attribute name="statisticsUpdateInterval" type="unsigned long">
8490	<desc>Interval to update guest statistics in seconds.</desc>
8491	</attribute>
8492
8493	<method name="internalGetStatistics">
8494	<desc>
8495	Internal method; do not use as it might change at any time
8496	</desc>
8497	<param name="cpuUser" type="unsigned long" dir="out">
8498	<desc>Percentage of processor time spent in user mode as seen by the guest</desc>
8499	</param>
8500	<param name="cpuKernel" type="unsigned long" dir="out">
8501	<desc>Percentage of processor time spent in kernel mode as seen by the guest</desc>
8502	</param>
8503	<param name="cpuIdle" type="unsigned long" dir="out">
8504	<desc>Percentage of processor time spent idling as seen by the guest</desc>
8505	</param>
8506	<param name="memTotal" type="unsigned long" dir="out">
8507	<desc>Total amount of physical guest RAM</desc>
8508	</param>
8509	<param name="memFree" type="unsigned long" dir="out">
8510	<desc>Free amount of physical guest RAM</desc>
8511	</param>
8512	<param name="memBalloon" type="unsigned long" dir="out">
8513	<desc>Amount of ballooned physical guest RAM</desc>
8514	</param>
8515	<param name="memCache" type="unsigned long" dir="out">
8516	<desc>Total amount of guest (disk) cache memory</desc>
8517	</param>
8518	<param name="pagedTotal" type="unsigned long" dir="out">
8519	<desc>Total amount of space in the page file</desc>
8520	</param>
8521	<param name="memAllocTotal" type="unsigned long" dir="out">
8522	<desc>Total amount of memory allocated by the hypervisor</desc>
8523	</param>
8524	<param name="memFreeTotal" type="unsigned long" dir="out">
8525	<desc>Total amount of free memory available in the hypervisor</desc>
8526	</param>
8527	<param name="memBalloonTotal" type="unsigned long" dir="out">
8528	<desc>Total amount of memory ballooned by the hypervisor</desc>
8529	</param>
8530	</method>
8531
8532	<method name="setCredentials">
8533	<desc>
8534	Store login credentials that can be queried by guest operating
8535	systems with Additions installed. The credentials are transient
8536	to the session and the guest may also choose to erase them. Note
8537	that the caller cannot determine whether the guest operating system
8538	has queried or made use of the credentials.
8539
8540	<result name="VBOX_E_VM_ERROR">
8541	VMM device is not available.
8542	</result>
8543
8544	</desc>
8545	<param name="userName" type="wstring" dir="in">
8546	<desc>User name string, can be empty</desc>
8547	</param>
8548	<param name="password" type="wstring" dir="in">
8549	<desc>Password string, can be empty</desc>
8550	</param>
8551	<param name="domain" type="wstring" dir="in">
8552	<desc>Domain name (guest logon scheme specific), can be empty</desc>
8553	</param>
8554	<param name="allowInteractiveLogon" type="boolean" dir="in">
8555	<desc>
8556	Flag whether the guest should alternatively allow the user to
8557	interactively specify different credentials. This flag might
8558	not be supported by all versions of the Additions.
8559	</desc>
8560	</param>
8561	</method>
8562
8563	<method name="executeProcess">
8564	<desc>
8565	Executes an existing program inside the guest VM.
8566
8567	<result name="VBOX_E_IPRT_ERROR">
8568	Could not execute process.
8569	</result>
8570
8571	</desc>
8572	<param name="execName" type="wstring" dir="in">
8573	<desc>
8574	Full path name of the command to execute on the guest; the
8575	commands has to exists in the guest VM in order to be executed.
8576	</desc>
8577	</param>
8578	<param name="flags" type="unsigned long" dir="in">
8579	<desc>
8580	Execution flags - currently not supported and therefore
8581	has to be set to 0.
8582	</desc>
8583	</param>
8584	<param name="arguments" type="wstring" safearray="yes" dir="in">
8585	<desc>
8586	Array of arguments passed to the execution command.
8587	</desc>
8588	</param>
8589	<param name="environment" type="wstring" safearray="yes" dir="in">
8590	<desc>
8591	Environment variables that can be set while the command is being
8592	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
8593	variable just set its name ("NAME") without a value.
8594	</desc>
8595	</param>
8596	<param name="stdIn" type="wstring" dir="in">
8597	<desc>
8598	What to do with the standard input (stdin) of the command being
8599	executed. Currently not used and has to be set to an empty value.
8600	</desc>
8601	</param>
8602	<param name="stdOut" type="wstring" dir="in">
8603	<desc>
8604	What to do with the standard output (stdout) of the command being
8605	executed. Currently not used and has to be set to an empty value.
8606	</desc>
8607	</param>
8608	<param name="stdErr" type="wstring" dir="in">
8609	<desc>
8610	What to do with the standard error (stderr) of the command being
8611	executed. Currently not used and has to be set to an empty value.
8612	</desc>
8613	</param>
8614	<param name="userName" type="wstring" dir="in">
8615	<desc>
8616	User name under which the command will be executed; has to exist
8617	and have the appropriate rights to execute programs in the VM.
8618	</desc>
8619	</param>
8620	<param name="password" type="wstring" dir="in">
8621	<desc>
8622	Password of the user account specified.
8623	</desc>
8624	</param>
8625	<param name="timeoutMS" type="unsigned long" dir="in">
8626	<desc>
8627	The maximum timeout value (in msec) to wait for finished program
8628	execution. Pass 0 for an infinite timeout.
8629	</desc>
8630	</param>
8631	<param name="pid" type="unsigned long" dir="out">
8632	<desc>
8633	The PID (process ID) of the started command for later reference.
8634	</desc>
8635	</param>
8636	<param name="progress" type="IProgress" dir="return">
8637	<desc>Progress object to track the operation completion.</desc>
8638	</param>
8639	</method>
8640
8641	<method name="getProcessOutput">
8642	<desc>
8643	Retrieves output of a formerly started process.
8644
8645	<result name="VBOX_E_IPRT_ERROR">
8646	Could not retrieve output.
8647	</result>
8648
8649	</desc>
8650	<param name="pid" type="unsigned long" dir="in">
8651	<desc>
8652	Process id returned by earlier executeProcess() call.
8653	</desc>
8654	</param>
8655	<param name="flags" type="unsigned long" dir="in">
8656	<desc>
8657	Flags describing which output to retrieve.
8658	</desc>
8659	</param>
8660	<param name="timeoutMS" type="unsigned long" dir="in">
8661	<desc>
8662	The maximum timeout value (in msec) to wait for output
8663	data. Pass 0 for an infinite timeout.
8664	</desc>
8665	</param>
8666	<param name="size" type="unsigned long long" dir="in">
8667	<desc>
8668	Size in bytes to read in the buffer.
8669	</desc>
8670	</param>
8671	<param name="data" type="octet" dir="return" safearray="yes">
8672	<desc>
8673	Buffer for retrieving the actual output. A data size of 0 means end of file
8674	if the requested size was not 0. This is the unprocessed
8675	output data, i.e. the line ending style depends on the platform of
8676	the system the server is running on.
8677	</desc>
8678	</param>
8679	</method>
8680
8681	<method name="getProcessStatus">
8682	<desc>
8683	Retrieves status, exit code and the exit reason of a formerly started process.
8684
8685	<result name="VBOX_E_IPRT_ERROR">
8686	Process with specified PID was not found.
8687	</result>
8688
8689	</desc>
8690	<param name="pid" type="unsigned long" dir="in">
8691	<desc>
8692	Process id returned by earlier executeProcess() call.
8693	</desc>
8694	</param>
8695	<param name="exitcode" type="unsigned long" dir="out">
8696	<desc>
8697	The exit code (if available).
8698	</desc>
8699	</param>
8700	<param name="flags" type="unsigned long" dir="out">
8701	<desc>
8702	Additional flags of process status (not used at the moment).
8703	</desc>
8704	</param>
8705	<param name="reason" type="unsigned long" dir="return">
8706	<desc>
8707	The current process status.
8708	</desc>
8709	</param>
8710	</method>
8711
8712	</interface>
8713
8714
8715	<!--
8716	// IProgress
8717	/////////////////////////////////////////////////////////////////////////
8718	-->
8719
8720	<interface
8721	name="IProgress" extends="$unknown"
8722	uuid="856aa038-853f-42e2-acf7-6e7b02dbe294"
8723	wsmap="managed"
8724	>
8725	<desc>
8726	The IProgress interface is used to track and control
8727	asynchronous tasks within VirtualBox.
8728
8729	An instance of this is returned every time VirtualBox starts
8730	an asynchronous task (in other words, a separate thread) which
8731	continues to run after a method call returns. For example,
8732	<link to="IConsole::saveState" />, which saves the state of
8733	a running virtual machine, can take a long time to complete.
8734	To be able to display a progress bar, a user interface such as
8735	the VirtualBox graphical user interface can use the IProgress
8736	object returned by that method.
8737
8738	Note that IProgress is a "read-only" interface in the sense
8739	that only the VirtualBox internals behind the Main API can
8740	create and manipulate progress objects, whereas client code
8741	can only use the IProgress object to monitor a task's
8742	progress and, if <link to="#cancelable" /> is @c true,
8743	cancel the task by calling <link to="#cancel" />.
8744
8745	A task represented by IProgress consists of either one or
8746	several sub-operations that run sequentially, one by one (see
8747	<link to="#operation" /> and <link to="#operationCount" />).
8748	Every operation is identified by a number (starting from 0)
8749	and has a separate description.
8750
8751	You can find the individual percentage of completion of the current
8752	operation in <link to="#operationPercent" /> and the
8753	percentage of completion of the task as a whole
8754	in <link to="#percent" />.
8755
8756	Similarly, you can wait for the completion of a particular
8757	operation via <link to="#waitForOperationCompletion" /> or
8758	for the completion of the whole task via
8759	<link to="#waitForCompletion" />.
8760	</desc>
8761
8762	<attribute name="id" type="uuid" mod="string" readonly="yes">
8763	<desc>ID of the task.</desc>
8764	</attribute>
8765
8766	<attribute name="description" type="wstring" readonly="yes">
8767	<desc>Description of the task.</desc>
8768	</attribute>
8769
8770	<attribute name="initiator" type="$unknown" readonly="yes">
8771	<desc>Initiator of the task.</desc>
8772	</attribute>
8773
8774	<attribute name="cancelable" type="boolean" readonly="yes">
8775	<desc>Whether the task can be interrupted.</desc>
8776	</attribute>
8777
8778	<attribute name="percent" type="unsigned long" readonly="yes">
8779	<desc>
8780	Current progress value of the task as a whole, in percent.
8781	This value depends on how many operations are already complete.
8782	Returns 100 if <link to="#completed" /> is @c true.
8783	</desc>
8784	</attribute>
8785
8786	<attribute name="timeRemaining" type="long" readonly="yes">
8787	<desc>
8788	Estimated remaining time until the task completes, in
8789	seconds. Returns 0 once the task has completed; returns -1
8790	if the remaining time cannot be computed, in particular if
8791	the current progress is 0.
8792
8793	Even if a value is returned, the estimate will be unreliable
8794	for low progress values. It will become more reliable as the
8795	task progresses; it is not recommended to display an ETA
8796	before at least 20% of a task have completed.
8797	</desc>
8798	</attribute>
8799
8800	<attribute name="completed" type="boolean" readonly="yes">
8801	<desc>Whether the task has been completed.</desc>
8802	</attribute>
8803
8804	<attribute name="canceled" type="boolean" readonly="yes">
8805	<desc>Whether the task has been canceled.</desc>
8806	</attribute>
8807
8808	<attribute name="resultCode" type="long" readonly="yes">
8809	<desc>
8810	Result code of the progress task.
8811	Valid only if <link to="#completed"/> is @c true.
8812	</desc>
8813	</attribute>
8814
8815	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
8816	<desc>
8817	Extended information about the unsuccessful result of the
8818	progress operation. May be @c null if no extended information
8819	is available.
8820	Valid only if <link to="#completed"/> is @c true and
8821	<link to="#resultCode"/> indicates a failure.
8822	</desc>
8823	</attribute>
8824
8825	<attribute name="operationCount" type="unsigned long" readonly="yes">
8826	<desc>
8827	Number of sub-operations this task is divided into.
8828	Every task consists of at least one suboperation.
8829	</desc>
8830	</attribute>
8831
8832	<attribute name="operation" type="unsigned long" readonly="yes">
8833	<desc>Number of the sub-operation being currently executed.</desc>
8834	</attribute>
8835
8836	<attribute name="operationDescription" type="wstring" readonly="yes">
8837	<desc>
8838	Description of the sub-operation being currently executed.
8839	</desc>
8840	</attribute>
8841
8842	<attribute name="operationPercent" type="unsigned long" readonly="yes">
8843	<desc>Progress value of the current sub-operation only, in percent.</desc>
8844	</attribute>
8845
8846	<attribute name="timeout" type="unsigned long">
8847	<desc>
8848	When non-zero, this specifies the number of milliseconds after which
8849	the operation will automatically be canceled. This can only be set on
8850	cancelable objects.
8851	</desc>
8852	</attribute>
8853
8854	<method name="setCurrentOperationProgress">
8855	<desc>Internal method, not to be called externally.</desc>
8856	<param name="percent" type="unsigned long" dir="in" />
8857	</method>
8858	<method name="setNextOperation">
8859	<desc>Internal method, not to be called externally.</desc>
8860	<param name="nextOperationDescription" type="wstring" dir="in" />
8861	<param name="nextOperationsWeight" type="unsigned long" dir="in" />
8862	</method>
8863
8864	<method name="waitForCompletion">
8865	<desc>
8866	Waits until the task is done (including all sub-operations)
8867	with a given timeout in milliseconds; specify -1 for an indefinite wait.
8868
8869	<result name="VBOX_E_IPRT_ERROR">
8870	Failed to wait for task completion.
8871	</result>
8872	</desc>
8873
8874	<param name="timeout" type="long" dir="in">
8875	<desc>
8876	Maximum time in milliseconds to wait or -1 to wait indefinitely.
8877	</desc>
8878	</param>
8879	</method>
8880
8881	<method name="waitForOperationCompletion">
8882	<desc>
8883	Waits until the given operation is done with a given timeout in
8884	milliseconds; specify -1 for an indefinite wait.
8885
8886	<result name="VBOX_E_IPRT_ERROR">
8887	Failed to wait for operation completion.
8888	</result>
8889
8890	</desc>
8891	<param name="operation" type="unsigned long" dir="in">
8892	<desc>
8893	Number of the operation to wait for.
8894	Must be less than <link to="#operationCount"/>.
8895	</desc>
8896	</param>
8897	<param name="timeout" type="long" dir="in">
8898	<desc>
8899	Maximum time in milliseconds to wait or -1 to wait indefinitely.
8900	</desc>
8901	</param>
8902	</method>
8903
8904	<method name="cancel">
8905	<desc>
8906	Cancels the task.
8907	<note>
8908	If <link to="#cancelable"/> is @c false, then this method will fail.
8909	</note>
8910
8911	<result name="VBOX_E_INVALID_OBJECT_STATE">
8912	Operation cannot be canceled.
8913	</result>
8914
8915	</desc>
8916	</method>
8917
8918	</interface>
8919
8920
8921	<!--
8922	// ISnapshot
8923	/////////////////////////////////////////////////////////////////////////
8924	-->
8925
8926	<interface
8927	name="ISnapshot" extends="$unknown"
8928	uuid="1a2d0551-58a4-4107-857e-ef414fc42ffc"
8929	wsmap="managed"
8930	>
8931	<desc>
8932	The ISnapshot interface represents a snapshot of the virtual
8933	machine.
8934
8935	Together with the differencing media that are created
8936	when a snapshot is taken, a machine can be brought back to
8937	the exact state it was in when the snapshot was taken.
8938
8939	The ISnapshot interface has no methods, only attributes; snapshots
8940	are controlled through methods of the <link to="IConsole" /> interface
8941	which also manage the media associated with the snapshot.
8942	The following operations exist:
8943
8944	<ul>
8945	<li><link to="IConsole::takeSnapshot"/>: creates a new snapshot
8946	by creating new, empty differencing images for the machine's
8947	media and saving the VM settings and (if the VM is running)
8948	the current VM state in the snapshot.
8949
8950	The differencing images will then receive all data written to
8951	the machine's media, while their parent (base) images
8952	remain unmodified after the snapshot has been taken (see
8953	<link to="IMedium" /> for details about differencing images).
8954	This simplifies restoring a machine to the state of a snapshot:
8955	only the differencing images need to be deleted.
8956
8957	The current machine state is not changed by taking a snapshot.
8958	If the machine is running, it will resume execution after the
8959	snapshot has been taken.
8960	</li>
8961
8962	<li><link to="IConsole::restoreSnapshot"/>: this goes back to
8963	a previous snapshot. This resets the machine's state to that of
8964	the previous snapshot by deleting the differencing image of each
8965	of the machine's media and setting the machine's settings
8966	and state to the state that was saved in the snapshot (if any).
8967
8968	This destroys the machine's current state.
8969	</li>
8970
8971	<li><link to="IConsole::deleteSnapshot"/>: deletes a snapshot
8972	without affecting the current machine state.
8973
8974	This does not change the machine, but instead frees the resources
8975	allocated when the snapshot was taken: the settings and machine state
8976	is deleted (if any), and the snapshot's differencing image for each
8977	of the machine's media gets merged with its parent image.
8978
8979	Neither the current machine state nor other snapshots are affected
8980	by this operation, except that parent media will be modified
8981	to contain the disk data associated with the snapshot being deleted.
8982	</li>
8983	</ul>
8984
8985	Each snapshot contains the settings of the virtual machine (hardware
8986	configuration etc.). In addition, if the machine was running when the
8987	snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
8988	the current VM state is saved in the snapshot (similarly to what happens
8989	when a VM's state is saved). The snapshot is then said to
8990	be <i>online</i> because when restoring it, the VM will be running.
8991
8992	If the machine is saved (<link to="MachineState_Saved"/>), the snapshot
8993	receives a copy of the execution state file (<link to="IMachine::stateFilePath"/>).
8994
8995	Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
8996	or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
8997	it then contains a so-called "zero execution state", representing a
8998	machine that is powered off.
8999
9000	<h3>Snapshot branches and the "current" snapshot</h3>
9001
9002	Snapshots can be chained, whereby every next snapshot is based on the
9003	previous one. This chaining is related to medium branching
9004	(see the <link to="IMedium"/> description) in that every time
9005	a new snapshot is created, a new differencing medium is implicitly
9006	created for all normal media attached to the machine.
9007
9008	Each virtual machine has a "current snapshot", identified by
9009	<link to="IMachine::currentSnapshot"/>. Presently, this is always set
9010	to the last snapshot in the chain. In a future version of VirtualBox,
9011	it will be possible to reset a machine's current state to that of an
9012	earlier snapshot without deleting the current state so that it will be
9013	possible to create alternative snapshot paths in a snapshot tree.
9014
9015	In the current implementation, multiple snapshot branches within one
9016	virtual machine are not allowed. Every machine has a single branch,
9017	and <link to="IConsole::takeSnapshot"/> operation adds a new
9018	snapshot to the top of that branch.
9019	</desc>
9020
9021	<attribute name="id" type="uuid" mod="string" readonly="yes">
9022	<desc>UUID of the snapshot.</desc>
9023	</attribute>
9024
9025	<attribute name="name" type="wstring">
9026	<desc>Short name of the snapshot.</desc>
9027	</attribute>
9028
9029	<attribute name="description" type="wstring">
9030	<desc>Optional description of the snapshot.</desc>
9031	</attribute>
9032
9033	<attribute name="timeStamp" type="long long" readonly="yes">
9034	<desc>
9035	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
9036	</desc>
9037	</attribute>
9038
9039	<attribute name="online" type="boolean" readonly="yes">
9040	<desc>
9041	@c true if this snapshot is an online snapshot and @c false otherwise.
9042
9043	When this attribute is @c true, the
9044	<link to="IMachine::stateFilePath"/> attribute of the
9045	<link to="#machine"/> object associated with this snapshot
9046	will point to the saved state file. Otherwise, it will be
9047	an empty string.
9048	</desc>
9049	</attribute>
9050
9051	<attribute name="machine" type="IMachine" readonly="yes">
9052	<desc>
9053	Virtual machine this snapshot is taken on. This object
9054	stores all settings the machine had when taking this snapshot.
9055	<note>
9056	The returned machine object is immutable, i.e. no
9057	any settings can be changed.
9058	</note>
9059	</desc>
9060	</attribute>
9061
9062	<attribute name="parent" type="ISnapshot" readonly="yes">
9063	<desc>
9064	Parent snapshot (a snapshot this one is based on), or
9065	@c null if the snapshot has no parent (i.e. is the first snapshot).
9066	</desc>
9067	</attribute>
9068
9069	<attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
9070	<desc>
9071	Child snapshots (all snapshots having this one as a parent).
9072	</desc>
9073	</attribute>
9074
9075	</interface>
9076
9077
9078	<!--
9079	// IMedium
9080	/////////////////////////////////////////////////////////////////////////
9081	-->
9082
9083	<enum
9084	name="MediumState"
9085	uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
9086	>
9087	<desc>
9088	Virtual medium state.
9089	<see>IMedium</see>
9090	</desc>
9091
9092	<const name="NotCreated" value="0">
9093	<desc>
9094	Associated medium storage does not exist (either was not created yet or
9095	was deleted).
9096	</desc>
9097	</const>
9098	<const name="Created" value="1">
9099	<desc>
9100	Associated storage exists and accessible; this gets set if the
9101	accessibility check performed by <link to="IMedium::refreshState" />
9102	was successful.
9103	</desc>
9104	</const>
9105	<const name="LockedRead" value="2">
9106	<desc>
9107	Medium is locked for reading (see <link to="IMedium::lockRead"/>),
9108	no data modification is possible.
9109	</desc>
9110	</const>
9111	<const name="LockedWrite" value="3">
9112	<desc>
9113	Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
9114	no concurrent data reading or modification is possible.
9115	</desc>
9116	</const>
9117	<const name="Inaccessible" value="4">
9118	<desc>
9119	Medium accessiblity check (see <link to="IMedium::refreshState" />) has
9120	not yet been performed, or else, associated medium storage is not
9121	accessible. In the first case, <link to="IMedium::lastAccessError"/>
9122	is empty, in the second case, it describes the error that occured.
9123	</desc>
9124	</const>
9125	<const name="Creating" value="5">
9126	<desc>
9127	Associated medium storage is being created.
9128	</desc>
9129	</const>
9130	<const name="Deleting" value="6">
9131	<desc>
9132	Associated medium storage is being deleted.
9133	</desc>
9134	</const>
9135	</enum>
9136
9137	<enum
9138	name="MediumType"
9139	uuid="11f6f7a5-0327-409a-9d42-7db6a0cec578"
9140	>
9141	<desc>
9142	Virtual medium type.
9143	<see>IMedium</see>
9144	</desc>
9145
9146	<const name="Normal" value="0">
9147	<desc>
9148	Normal medium (attached directly or indirectly, preserved
9149	when taking snapshots).
9150	</desc>
9151	</const>
9152	<const name="Immutable" value="1">
9153	<desc>
9154	Immutable medium (attached indirectly, changes are wiped out
9155	the next time the virtual machine is started).
9156	</desc>
9157	</const>
9158	<const name="Writethrough" value="2">
9159	<desc>
9160	Write through medium (attached directly, ignored when
9161	taking snapshots).
9162	</desc>
9163	</const>
9164	</enum>
9165
9166	<enum
9167	name="MediumVariant"
9168	uuid="584ea502-143b-4ab0-ad14-d1028fdf0316"
9169	>
9170	<desc>
9171	Virtual medium image variant. More than one flag may be set.
9172	<see>IMedium</see>
9173	</desc>
9174
9175	<const name="Standard" value="0">
9176	<desc>
9177	No particular variant requested, results in using the backend default.
9178	</desc>
9179	</const>
9180	<const name="VmdkSplit2G" value="0x01">
9181	<desc>
9182	VMDK image split in chunks of less than 2GByte.
9183	</desc>
9184	</const>
9185	<const name="VmdkStreamOptimized" value="0x04">
9186	<desc>
9187	VMDK streamOptimized image. Special import/export format which is
9188	read-only/append-only.
9189	</desc>
9190	</const>
9191	<const name="VmdkESX" value="0x08">
9192	<desc>
9193	VMDK format variant used on ESX products.
9194	</desc>
9195	</const>
9196	<const name="Fixed" value="0x10000">
9197	<desc>
9198	Fixed image. Only allowed for base images.
9199	</desc>
9200	</const>
9201	<const name="Diff" value="0x20000">
9202	<desc>
9203	Fixed image. Only allowed for base images.
9204	</desc>
9205	</const>
9206	</enum>
9207
9208	<interface
9209	name="IMediumAttachment" extends="$unknown"
9210	uuid="e58eb3eb-8627-428b-bdf8-34487c848de5"
9211	wsmap="struct"
9212	>
9213	<desc>
9214	The IMediumAttachment interface represents the attachment
9215	of a storage medium to a virtual machine. Each machine contains
9216	an array of its medium attachments in <link to="IMachine::mediumAttachments"/>.
9217
9218	Each medium attachment specifies a storage controller as well as a port
9219	and device number. Fixed media (hard disks) will always also specify
9220	an instance of IMedium in <link to="#medium" />, referring to the hard disk
9221	medium. For removeable media, the IMedia instance is optional; it can be
9222	@c null if no media is mounted (see <link to="IMachine::mountMedium" />).
9223	</desc>
9224
9225	<attribute name="medium" type="IMedium" readonly="yes">
9226	<desc>Medium object associated with this attachment; it
9227	can be @c null for removable devices.</desc>
9228	</attribute>
9229
9230	<attribute name="controller" type="wstring" readonly="yes">
9231	<desc>Name of the storage controller of this attachment; this
9232	refers to one of the controllers in <link to="IMachine::storageControllers" />
9233	by name.</desc>
9234	</attribute>
9235
9236	<attribute name="port" type="long" readonly="yes">
9237	<desc>Port number of this attachment.</desc>
9238	</attribute>
9239
9240	<attribute name="device" type="long" readonly="yes">
9241	<desc>Device slot number of this attachment.</desc>
9242	</attribute>
9243
9244	<attribute name="type" type="DeviceType" readonly="yes">
9245	<desc>Device type of this attachment.</desc>
9246	</attribute>
9247
9248	<attribute name="passthrough" type="boolean" readonly="yes">
9249	<desc>Pass I/O requests through to a device on the host.</desc>
9250	</attribute>
9251
9252	</interface>
9253
9254	<interface
9255	name="IMedium" extends="$unknown"
9256	uuid="d709160c-303f-4ead-b7ef-53ffa26aa861"
9257	wsmap="managed"
9258	>
9259	<desc>
9260	The IMedium interface represents virtual storage for a machine's
9261	hard disks, CD/DVD or floppy drives. It will typically represent
9262	a disk image on the host, for example a VDI or VMDK file representing
9263	a virtual hard disk, or an ISO or RAW file representing virtual
9264	removable media, but can also point to a network location (e.g.
9265	for iSCSI targets).
9266
9267	Instances of IMedium are connected to virtual machines by way of
9268	medium attachments (see <link to="IMediumAttachment" />), which link
9269	the storage medium to a particular device slot of a storage controller
9270	of the virtual machine.
9271	In the VirtualBox API, virtual storage is therefore always represented
9272	by the following chain of object links:
9273
9274	<ul>
9275	<li><link to="IMachine::storageControllers"/> contains an array of
9276	storage controllers (IDE, SATA, SCSI or a floppy controller;
9277	these are instances of <link to="IStorageController"/>).</li>
9278	<li><link to="IMachine::mediumAttachments"/> contains an array of
9279	medium attachments (instances of <link to="IMediumAttachment"/>),
9280	each containing a storage controller from the above array, a
9281	port/device specification, and an instance of IMedium representing
9282	the medium storage (image file).
9283
9284	For removable media, the storage medium is optional; a medium
9285	attachment with no medium represents a CD/DVD or floppy drive
9286	with no medium inserted. By contrast, hard disk attachments
9287	will always have an IMedium object attached.</li>
9288	<li>Each IMedium in turn points to a storage unit (such as a file
9289	on the host computer or a network resource) that holds actual
9290	data. This location is represented by the <link to="#location"/>
9291	attribute.</li>
9292	</ul>
9293
9294	Existing media are opened using the following methods, depending on the
9295	media type:
9296	<ul>
9297	<li><link to="IVirtualBox::openHardDisk"/></li>
9298	<li><link to="IVirtualBox::openDVDImage"/></li>
9299	<li><link to="IVirtualBox::openFloppyImage"/></li>
9300	</ul>
9301
9302	New hard disk media can be created with the VirtualBox API using the
9303	<link to="IVirtualBox::createHardDisk"/> method.
9304
9305	CD/DVD and floppy images (ISO and RAW files) are usually created outside
9306	VirtualBox, e.g. by storing a copy of the real medium of the corresponding
9307	type in a regular file.
9308
9309	Only for CD/DVDs and floppies, an IMedium instance can also represent a host
9310	drive; in that case the <link to="#id" /> attribute contains the UUID of
9311	one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
9312
9313	<h3>Known media</h3>
9314
9315	When an existing medium is opened for the first time, it is automatically
9316	remembered by the given VirtualBox installation or, in other words, becomes
9317	a <i>known medium</i>. Known media are stored in the media
9318	registry transparently maintained by VirtualBox and stored in settings
9319	files so that this registry is preserved when VirtualBox is not running.
9320
9321	Newly created virtual media are remembered only when the associated
9322	storage unit is actually created.
9323
9324	All known media can be enumerated using
9325	<link to="IVirtualBox::hardDisks"/>,
9326	<link to="IVirtualBox::DVDImages"/> and
9327	<link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
9328	quickly found by UUID using <link to="IVirtualBox::getHardDisk"/>
9329	and similar methods or by location using
9330	<link to="IVirtualBox::findHardDisk"/> and similar methods.
9331
9332	Only known media can be attached to virtual machines.
9333
9334	Removing known media from the media registry is performed when the given
9335	medium is closed using the <link to="#close"/> method or when its
9336	associated storage unit is deleted.
9337
9338	<h3>Accessibility checks</h3>
9339
9340	VirtualBox defers media accessibility checks until the <link to="#refreshState" />
9341	method is called explicitly on a medium. This is done to make the VirtualBox object
9342	ready for serving requests as fast as possible and let the end-user
9343	application decide if it needs to check media accessibility right away or not.
9344
9345	As a result, when VirtualBox starts up (e.g. the VirtualBox
9346	object gets created for the first time), all known media are in the
9347	"Inaccessible" state, but the value of the <link to="#lastAccessError"/>
9348	attribute is an empty string because no actual accessibility check has
9349	been made yet.
9350
9351	After calling <link to="#refreshState" />, a medium is considered
9352	<i>accessible</i> if its storage unit can be read. In that case, the
9353	<link to="#state"/> attribute has a value of "Created". If the storage
9354	unit cannot be read (for example, because it is located on a disconnected
9355	network resource, or was accidentally deleted outside VirtualBox),
9356	the medium is considered <i>inaccessible</i>, which is indicated by the
9357	"Inaccessible" state. The exact reason why the medium is inaccessible can be
9358	obtained by reading the <link to="#lastAccessError"/> attribute.
9359
9360	<h3>Medium types</h3>
9361
9362	There are three types of medium behavior (see <link to="MediumType" />):
9363	"normal", "immutable" and "writethrough", represented by the
9364	<link to="#type"/> attribute. The type of the medium defines how the
9365	medium is attached to a virtual machine and what happens when a
9366	<link to="ISnapshot">snapshot</link> of the virtual machine with the
9367	attached medium is taken. At the moment DVD and floppy media are always
9368	of type "writethrough".
9369
9370	All media can be also divided in two groups: <i>base</i> media and
9371	<i>differencing</i> media. A base medium contains all sectors of the
9372	medium data in its own storage and therefore can be used independently.
9373	In contrast, a differencing mediun is a "delta" to some other medium and
9374	contains only those sectors which differ from that other medium, which is
9375	then called a <i>parent</i>. The differencing medium is said to be
9376	<i>linked to</i> that parent. The parent may be itself a differencing
9377	medium, thus forming a chain of linked media. The last element in that
9378	chain must always be a base medium. Note that several differencing
9379	media may be linked to the same parent medium.
9380
9381	Differencing media can be distinguished from base media by querying the
9382	<link to="#parent"/> attribute: base media do not have parents they would
9383	depend on, so the value of this attribute is always @c null for them.
9384	Using this attribute, it is possible to walk up the medium tree (from the
9385	child medium to its parent). It is also possible to walk down the tree
9386	using the <link to="#children"/> attribute.
9387
9388	Note that the type of all differencing media is "Normal"; all other
9389	values are meaningless for them. Base media may be of any type.
9390
9391	<h3>Creating hard disks</h3>
9392
9393	New base hard disks are created using
9394	<link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
9395	opened using <link to="IVirtualBox::openHardDisk"/>. Differencing hard
9396	disks are usually implicitly created by VirtualBox when needed but may
9397	also be created explicitly using <link to="#createDiffStorage"/>.
9398
9399	After the hard disk is successfully created (including the storage unit)
9400	or opened, it becomes a known hard disk (remembered in the internal media
9401	registry). Known hard disks can be attached to a virtual machine, accessed
9402	through <link to="IVirtualBox::getHardDisk"/> and
9403	<link to="IVirtualBox::findHardDisk"/> methods or enumerated using the
9404	<link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
9405
9406	The following methods, besides <link to="IMedium::close"/>,
9407	automatically remove the hard disk from the media registry:
9408	<ul>
9409	<li><link to="#deleteStorage"/></li>
9410	<li><link to="#mergeTo"/></li>
9411	</ul>
9412
9413	If the storage unit of the hard disk is a regular file in the host's
9414	file system then the rules stated in the description of the
9415	<link to="IMedium::location"/> attribute apply when setting its value. In
9416	addition, a plain file name without any path may be given, in which case
9417	the <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
9418	folder</link> will be prepended to it.
9419
9420	<h4>Automatic composition of the file name part</h4>
9421
9422	Another extension to the <link to="IMedium::location"/> attribute is that
9423	there is a possibility to cause VirtualBox to compose a unique value for
9424	the file name part of the location using the UUID of the hard disk. This
9425	applies only to hard disks in <link to="MediumState_NotCreated"/> state,
9426	e.g. before the storage unit is created, and works as follows. You set the
9427	value of the <link to="IMedium::location"/> attribute to a location
9428	specification which only contains the path specification but not the file
9429	name part and ends with either a forward slash or a backslash character.
9430	In response, VirtualBox will generate a new UUID for the hard disk and
9431	compose the file name using the following pattern:
9432	<pre>
9433	<path>/{<uuid>}.<ext>
9434	</pre>
9435	where <tt><path></tt> is the supplied path specification,
9436	<tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
9437	is the default extension for the storage format of this hard disk. After
9438	that, you may call any of the methods that create a new hard disk storage
9439	unit and they will use the generated UUID and file name.
9440
9441	<h3>Attaching Hard Disks</h3>
9442
9443	Hard disks are attached to virtual machines using the
9444	<link to="IMachine::attachDevice"/> method and detached using the
9445	<link to="IMachine::detachDevice"/> method. Depending on their
9446	<link to="#type"/>, hard disks are attached either
9447	<i>directly</i> or <i>indirectly</i>.
9448
9449	When a hard disk is being attached directly, it is associated with the
9450	virtual machine and used for hard disk operations when the machine is
9451	running. When a hard disk is being attached indirectly, a new differencing
9452	hard disk linked to it is implicitly created and this differencing hard
9453	disk is associated with the machine and used for hard disk operations.
9454	This also means that if <link to="IMachine::attachDevice"/> performs
9455	a direct attachment then the same hard disk will be returned in response
9456	to the subsequent <link to="IMachine::getMedium"/> call; however if
9457	an indirect attachment is performed then
9458	<link to="IMachine::getMedium"/> will return the implicitly created
9459	differencing hard disk, not the original one passed to <link
9460	to="IMachine::attachDevice"/>. In detail:
9461
9462	<ul>
9463	<li><b>Normal base</b> hard disks that do not have children (i.e.
9464	differencing hard disks linked to them) and that are not already
9465	attached to virtual machines in snapshots are attached <b>directly</b>.
9466	Otherwise, they are attached <b>indirectly</b> because having
9467	dependent children or being part of the snapshot makes it impossible
9468	to modify hard disk contents without breaking the integrity of the
9469	dependent party. The <link to="#readOnly"/> attribute allows to
9470	quickly determine the kind of the attachment for the given hard
9471	disk. Note that if a normal base hard disk is to be indirectly
9472	attached to a virtual machine with snapshots then a special
9473	procedure called <i>smart attachment</i> is performed (see below).</li>
9474	<li><b>Normal differencing</b> hard disks are like normal base hard disks:
9475	they are attached <b>directly</b> if they do not have children and are
9476	not attached to virtual machines in snapshots, and <b>indirectly</b>
9477	otherwise. Note that the smart attachment procedure is never performed
9478	for differencing hard disks.</li>
9479	<li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
9480	they are designed to be non-writable. If an immutable hard disk is
9481	attached to a virtual machine with snapshots then a special
9482	procedure called smart attachment is performed (see below).</li>
9483	<li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
9484	also as designed. This also means that writethrough hard disks cannot
9485	have other hard disks linked to them at all.</li>
9486	</ul>
9487
9488	Note that the same hard disk, regardless of its type, may be attached to
9489	more than one virtual machine at a time. In this case, the machine that is
9490	started first gains exclusive access to the hard disk and attempts to
9491	start other machines having this hard disk attached will fail until the
9492	first machine is powered down.
9493
9494	Detaching hard disks is performed in a <i>deferred</i> fashion. This means
9495	that the given hard disk remains associated with the given machine after a
9496	successful <link to="IMachine::detachDevice"/> call until
9497	<link to="IMachine::saveSettings"/> is called to save all changes to
9498	machine settings to disk. This deferring is necessary to guarantee that
9499	the hard disk configuration may be restored at any time by a call to
9500	<link to="IMachine::discardSettings"/> before the settings
9501	are saved (committed).
9502
9503	Note that if <link to="IMachine::discardSettings"/> is called after
9504	indirectly attaching some hard disks to the machine but before a call to
9505	<link to="IMachine::saveSettings"/> is made, it will implicitly delete
9506	all differencing hard disks implicitly created by
9507	<link to="IMachine::attachDevice"/> for these indirect attachments.
9508	Such implicitly created hard disks will also be immediately deleted when
9509	detached explicitly using the <link to="IMachine::detachDevice"/>
9510	call if it is made before <link to="IMachine::saveSettings"/>. This
9511	implicit deletion is safe because newly created differencing hard
9512	disks do not contain any user data.
9513
9514	However, keep in mind that detaching differencing hard disks that were
9515	implicitly created by <link to="IMachine::attachDevice"/>
9516	before the last <link to="IMachine::saveSettings"/> call will
9517	<b>not</b> implicitly delete them as they may already contain some data
9518	(for example, as a result of virtual machine execution). If these hard
9519	disks are no more necessary, the caller can always delete them explicitly
9520	using <link to="#deleteStorage"/> after they are actually de-associated
9521	from this machine by the <link to="IMachine::saveSettings"/> call.
9522
9523	<h3>Smart Attachment</h3>
9524
9525	When normal base or immutable hard disks are indirectly attached to a
9526	virtual machine then some additional steps are performed to make sure the
9527	virtual machine will have the most recent "view" of the hard disk being
9528	attached. These steps include walking through the machine's snapshots
9529	starting from the current one and going through ancestors up to the first
9530	snapshot. Hard disks attached to the virtual machine in all
9531	of the encountered snapshots are checked whether they are descendants of
9532	the given normal base or immutable hard disk. The first found child (which
9533	is the differencing hard disk) will be used instead of the normal base or
9534	immutable hard disk as a parent for creating a new differencing hard disk
9535	that will be actually attached to the machine. And only if no descendants
9536	are found or if the virtual machine does not have any snapshots then the
9537	normal base or immutable hard disk will be used itself as a parent for
9538	this differencing hard disk.
9539
9540	It is easier to explain what smart attachment does using the
9541	following example:
9542	<pre>
9543	BEFORE attaching B.vdi: AFTER attaching B.vdi:
9544
9545	Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
9546	Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
9547	Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
9548	Snapshot 4 (none) Snapshot 4 (none)
9549	CurState (none) CurState (D3->D2.vdi)
9550
9551	NOT
9552	...
9553	CurState (D3->B.vdi)
9554	</pre>
9555	The first column is the virtual machine configuration before the base hard
9556	disk <tt>B.vdi</tt> is attached, the second column shows the machine after
9557	this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
9558	mean that the hard disk that is actually attached to the machine is a
9559	differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
9560	another hard disk, <tt>B.vdi</tt>.
9561
9562	As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
9563	from the machine before taking Snapshot 4. Later, after Snapshot 4 was
9564	taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
9565	dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
9566	it cannot be attached directly and needs an indirect attachment (i.e.
9567	implicit creation of a new differencing hard disk). Due to the smart
9568	attachment procedure, the new differencing hard disk
9569	(<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
9570	<tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
9571	<tt>B.vdi</tt> existing for this snapshot branch of the given virtual
9572	machine.
9573
9574	Note that if there is more than one descendant hard disk of the given base
9575	hard disk found in a snapshot, and there is an exact device, channel and
9576	bus match, then this exact match will be used. Otherwise, the youngest
9577	descendant will be picked up.
9578
9579	There is one more important aspect of the smart attachment procedure which
9580	is not related to snapshots at all. Before walking through the snapshots
9581	as described above, the backup copy of the current list of hard disk
9582	attachment is searched for descendants. This backup copy is created when
9583	the hard disk configuration is changed for the first time after the last
9584	<link to="IMachine::saveSettings"/> call and used by
9585	<link to="IMachine::discardSettings"/> to undo the recent hard disk
9586	changes. When such a descendant is found in this backup copy, it will be
9587	simply re-attached back, without creating a new differencing hard disk for
9588	it. This optimization is necessary to make it possible to re-attach the
9589	base or immutable hard disk to a different bus, channel or device slot
9590	without losing the contents of the differencing hard disk actually
9591	attached to the machine in place of it.
9592	</desc>
9593
9594	<attribute name="id" type="uuid" mod="string" readonly="yes">
9595	<desc>
9596	UUID of the medium. For a newly created medium, this value is a randomly
9597	generated UUID.
9598
9599	<note>
9600	For media in one of MediumState_NotCreated, MediumState_Creating or
9601	MediumState_Deleting states, the value of this property is undefined
9602	and will most likely be an empty UUID.
9603	</note>
9604	</desc>
9605	</attribute>
9606
9607	<attribute name="description" type="wstring">
9608	<desc>
9609	Optional description of the medium. For a newly created medium the value
9610	of this attribute is an empty string.
9611
9612	Medium types that don't support this attribute will return E_NOTIMPL in
9613	attempt to get or set this attribute's value.
9614
9615	<note>
9616	For some storage types, reading this attribute may return an outdated
9617	(last known) value when <link to="#state"/> is <link
9618	to="MediumState_Inaccessible"/> or <link
9619	to="MediumState_LockedWrite"/> because the value of this attribute is
9620	stored within the storage unit itself. Also note that changing the
9621	attribute value is not possible in such case, as well as when the
9622	medium is the <link to="MediumState_LockedRead"/> state.
9623	</note>
9624	</desc>
9625	</attribute>
9626
9627	<attribute name="state" type="MediumState" readonly="yes">
9628	<desc>
9629	Returns the current medium state, which is the last state set by
9630	the accessibility check performed by <link to="#refreshState"/>.
9631	If that method has not yet been called on the medium, the state
9632	is "Inaccessible"; as opposed to truly inaccessible media, the
9633	value of <link to="#lastAccessError"/> will be an empty string in
9634	that case.
9635
9636	<note>As of version 3.1, this no longer performs an accessibility check
9637	automatically; call <link to="#refreshState"/> for that.
9638	</note>
9639	</desc>
9640	</attribute>
9641
9642	<attribute name="location" type="wstring">
9643	<desc>
9644	Location of the storage unit holding medium data.
9645
9646	The format of the location string is medium type specific. For medium
9647	types using regular files in a host's file system, the location
9648	string is the full file name.
9649
9650	Some medium types may support changing the storage unit location by
9651	simply changing the value of this property. If this operation is not
9652	supported, the implementation will return E_NOTIMPL in attempt to set
9653	this attribute's value.
9654
9655	When setting a value of the location attribute which is a regular file
9656	in the host's file system, the given file name may be either relative to
9657	the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
9658	absolute. Note that if the given location specification does not contain
9659	the file extension part then a proper default extension will be
9660	automatically appended by the implementation depending on the medium type.
9661	</desc>
9662	</attribute>
9663
9664	<attribute name="name" type="wstring" readonly="yes">
9665	<desc>
9666	Name of the storage unit holding medium data.
9667
9668	The returned string is a short version of the <link to="#location"/>
9669	attribute that is suitable for representing the medium in situations
9670	where the full location specification is too long (such as lists
9671	and comboboxes in GUI frontends). This string is also used by frontends
9672	to sort the media list alphabetically when needed.
9673
9674	For example, for locations that are regular files in the host's file
9675	system, the value of this attribute is just the file name (+ extension),
9676	without the path specification.
9677
9678	Note that as opposed to the <link to="#location"/> attribute, the name
9679	attribute will not necessary be unique for a list of media of the
9680	given type and format.
9681	</desc>
9682	</attribute>
9683
9684	<attribute name="deviceType" type="DeviceType" readonly="yes">
9685	<desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
9686	medium.</desc>
9687	</attribute>
9688
9689	<attribute name="hostDrive" type="boolean" readonly="yes">
9690	<desc>True if this corresponds to a drive on the host.</desc>
9691	</attribute>
9692
9693	<attribute name="size" type="unsigned long long" readonly="yes">
9694	<desc>
9695	Physical size of the storage unit used to hold medium data (in bytes).
9696
9697	<note>
9698	For media whose <link to="#state"/> is <link
9699	to="MediumState_Inaccessible"/>, the value of this property is the
9700	last known size. For <link to="MediumState_NotCreated"/> media,
9701	the returned value is zero.
9702	</note>
9703	</desc>
9704	</attribute>
9705
9706	<attribute name="format" type="wstring" readonly="yes">
9707	<desc>
9708	Storage format of this medium.
9709
9710	The value of this attribute is a string that specifies a backend used
9711	to store medium data. The storage format is defined when you create a
9712	new medium or automatically detected when you open an existing medium,
9713	and cannot be changed later.
9714
9715	The list of all storage formats supported by this VirtualBox
9716	installation can be obtained using
9717	<link to="ISystemProperties::mediumFormats"/>.
9718	</desc>
9719	</attribute>
9720
9721	<attribute name="type" type="MediumType">
9722	<desc>
9723	Type (role) of this medium.
9724
9725	The following constraints apply when changing the value of this
9726	attribute:
9727	<ul>
9728	<li>If a medium is attached to a virtual machine (either in the
9729	current state or in one of the snapshots), its type cannot be
9730	changed.
9731	</li>
9732	<li>As long as the medium has children, its type cannot be set
9733	to <link to="MediumType_Writethrough"/>.
9734	</li>
9735	<li>The type of all differencing media is
9736	<link to="MediumType_Normal"/> and cannot be changed.
9737	</li>
9738	</ul>
9739
9740	The type of a newly created or opened medium is set to
9741	<link to="MediumType_Normal"/>, except for DVD and floppy media,
9742	which have a type of <link to="MediumType_Writethrough"/>.
9743	</desc>
9744	</attribute>
9745
9746	<attribute name="parent" type="IMedium" readonly="yes">
9747	<desc>
9748	Parent of this medium (the medium this medium is directly based
9749	on).
9750
9751	Only differencing media have parents. For base (non-differencing)
9752	media, @c null is returned.
9753	</desc>
9754	</attribute>
9755
9756	<attribute name="children" type="IMedium" safearray="yes" readonly="yes">
9757	<desc>
9758	Children of this medium (all differencing media directly based
9759	on this medium). A @c null array is returned if this medium
9760	does not have any children.
9761	</desc>
9762	</attribute>
9763
9764	<attribute name="base" type="IMedium" readonly="yes">
9765	<desc>
9766	Base medium of this medium.
9767
9768	If this is a differencing medium, its base medium is the medium
9769	the given medium branch starts from. For all other types of media, this
9770	property returns the medium object itself (i.e. the same object this
9771	property is read on).
9772	</desc>
9773	</attribute>
9774
9775	<attribute name="readOnly" type="boolean" readonly="yes">
9776	<desc>
9777	Returns @c true if this medium is read-only and @c false otherwise.
9778
9779	A medium is considered to be read-only when its contents cannot be
9780	modified without breaking the integrity of other parties that depend on
9781	this medium such as its child media or snapshots of virtual machines
9782	where this medium is attached to these machines. If there are no
9783	children and no such snapshots then there is no dependency and the
9784	medium is not read-only.
9785
9786	The value of this attribute can be used to determine the kind of the
9787	attachment that will take place when attaching this medium to a
9788	virtual machine. If the value is @c false then the medium will
9789	be attached directly. If the value is @c true then the medium
9790	will be attached indirectly by creating a new differencing child
9791	medium for that. See the interface description for more information.
9792
9793	Note that all <link to="MediumType_Immutable">Immutable</link> media
9794	are always read-only while all
9795	<link to="MediumType_Writethrough">Writethrough</link> media are
9796	always not.
9797
9798	<note>
9799	The read-only condition represented by this attribute is related to
9800	the medium type and usage, not to the current
9801	<link to="IMedium::state">medium state</link> and not to the read-only
9802	state of the storage unit.
9803	</note>
9804	</desc>
9805	</attribute>
9806
9807	<attribute name="logicalSize" type="unsigned long long" readonly="yes">
9808	<desc>
9809	Logical size of this medium (in megabytes), as reported to the
9810	guest OS running inside the virtual machine this medium is
9811	attached to. The logical size is defined when the medium is created
9812	and cannot be changed later.
9813
9814	<note>
9815	Reading this property on a differencing medium will return the size
9816	of its <link to="#base"/> medium.
9817	</note>
9818	<note>
9819	For media whose state is <link to="#state"/> is <link
9820	to="MediumState_Inaccessible"/>, the value of this property is the
9821	last known logical size. For <link to="MediumaState_NotCreated"/>
9822	media, the returned value is zero.
9823	</note>
9824	</desc>
9825	</attribute>
9826
9827	<attribute name="autoReset" type="boolean">
9828	<desc>
9829	Whether this differencing medium will be automatically reset each
9830	time a virtual machine it is attached to is powered up. This
9831	attribute is automatically set to @c true for the last
9832	differencing image of an "immutable" medium (see
9833	<link to="MediumType" />).
9834
9835	See <link to="#reset"/> for more information about resetting
9836	differencing media.
9837
9838	<note>
9839	Reading this property on a base (non-differencing) medium will
9840	always @c false. Changing the value of this property in this
9841	case is not supported.
9842	</note>
9843
9844	<result name="VBOX_E_NOT_SUPPORTED">
9845	This is not a differencing medium (when changing the attribute
9846	value).
9847	</result>
9848	</desc>
9849	</attribute>
9850
9851	<attribute name="lastAccessError" type="wstring" readonly="yes">
9852	<desc>
9853	Text message that represents the result of the last accessibility
9854	check performed by <link to="#refreshState"/>.
9855
9856	An empty string is returned if the last accessibility check
9857	was successful or has not yet been called. As a result, if
9858	<link to="#state" /> is "Inaccessible" and this attribute is empty,
9859	then <link to="#refreshState"/> has yet to be called; this is the
9860	default value of media after VirtualBox initialization.
9861	A non-empty string indicates a failure and should normally describe
9862	a reason of the failure (for example, a file read error).
9863	</desc>
9864	</attribute>
9865
9866	<attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
9867	<desc>
9868	Array of UUIDs of all machines this medium is attached to.
9869
9870	A @c null array is returned if this medium is not attached to any
9871	machine or to any machine's snapshot.
9872
9873	<note>
9874	The returned array will include a machine even if this medium is not
9875	attached to that machine in the current state but attached to it in
9876	one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
9877	details.
9878	</note>
9879	</desc>
9880	</attribute>
9881
9882	<method name="refreshState">
9883	<desc>
9884	If the current medium state (see <link to="MediumState"/>) is one of
9885	"Created", "Inaccessible" or "LockedRead", then this performs an
9886	accessibility check on the medium and sets the value of the <link to="#state"/>
9887	attribute accordingly; that value is also returned for convenience.
9888
9889	For all other state values, this does not perform a refresh but returns
9890	the state only.
9891
9892	The refresh, if performed, may take a long time (several seconds or even
9893	minutes, depending on the storage unit location and format) because it performs an
9894	accessibility check of the storage unit. This check may cause a significant
9895	delay if the storage unit of the given medium is, for example, a file located
9896	on a network share which is not currently accessible due to connectivity
9897	problems. In that case, the call will not return until a timeout
9898	interval defined by the host OS for this operation expires. For this reason,
9899	it is recommended to never read this attribute on the main UI thread to avoid
9900	making the UI unresponsive.
9901
9902	If the last known state of the medium is "Created" and the accessibility
9903	check fails, then the state would be set to "Inaccessible", and
9904	<link to="#lastAccessError"/> may be used to get more details about the
9905	failure. If the state of the medium is "LockedRead", then it remains the
9906	same, and a non-empty value of <link to="#lastAccessError"/> will
9907	indicate a failed accessibility check in this case.
9908
9909	Note that not all medium states are applicable to all medium types.
9910	</desc>
9911	<param name="state" type="MediumState" dir="return">
9912	<desc>
9913	New medium state.
9914	</desc>
9915	</param>
9916	</method>
9917
9918	<method name="getSnapshotIds">
9919	<desc>
9920	Returns an array of UUIDs of all snapshots of the given machine where
9921	this medium is attached to.
9922
9923	If the medium is attached to the machine in the current state, then the
9924	first element in the array will always be the ID of the queried machine
9925	(i.e. the value equal to the @c machineId argument), followed by
9926	snapshot IDs (if any).
9927
9928	If the medium is not attached to the machine in the current state, then
9929	the array will contain only snapshot IDs.
9930
9931	The returned array may be @c null if this medium is not attached
9932	to the given machine at all, neither in the current state nor in one of
9933	the snapshots.
9934	</desc>
9935	<param name="machineId" type="uuid" mod="string" dir="in">
9936	<desc>
9937	UUID of the machine to query.
9938	</desc>
9939	</param>
9940	<param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
9941	<desc>
9942	Array of snapshot UUIDs of the given machine using this medium.
9943	</desc>
9944	</param>
9945	</method>
9946
9947	<method name="lockRead">
9948	<desc>
9949	Locks this medium for reading.
9950
9951	A read lock is shared: many clients can simultaneously lock the
9952	same medium for reading unless it is already locked for writing (see
9953	<link to="#lockWrite"/>) in which case an error is returned.
9954
9955	When the medium is locked for reading, it cannot be modified
9956	from within VirtualBox. This means that any method that changes
9957	the properties of this medium or contents of the storage unit
9958	will return an error (unless explicitly stated otherwise). That
9959	includes an attempt to start a virtual machine that wants to
9960	write to the the medium.
9961
9962	When the virtual machine is started up, it locks for reading all
9963	media it uses in read-only mode. If some medium cannot be locked
9964	for reading, the startup procedure will fail.
9965	A medium is typically locked for reading while it is used by a running
9966	virtual machine but has a depending differencing image that receives
9967	the actual write operations. This way one base medium can have
9968	multiple child differencing images which can be written to
9969	simultaneously. Read-only media such as DVD and floppy images are
9970	also locked for reading only (so they can be in use by multiple
9971	machines simultaneously).
9972
9973	A medium is also locked for reading when it is the source of a
9974	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
9975
9976	The medium locked for reading must be unlocked using the <link
9977	to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
9978	can be nested and must be followed by the same number of paired
9979	<link to="#unlockRead"/> calls.
9980
9981	This method sets the medium state (see <link to="#state"/>) to
9982	"LockedRead" on success. The medium's previous state must be
9983	one of "Created", "Inaccessible" or "LockedRead".
9984
9985	Locking an inaccessible medium is not an error; this method performs
9986	a logical lock that prevents modifications of this medium through
9987	the VirtualBox API, not a physical file-system lock of the underlying
9988	storage unit.
9989
9990	This method returns the current state of the medium
9991	<i>before</i> the operation.
9992
9993	<result name="VBOX_E_INVALID_OBJECT_STATE">
9994	Invalid medium state (e.g. not created, locked, inaccessible,
9995	creating, deleting).
9996	</result>
9997
9998	</desc>
9999	<param name="state" type="MediumState" dir="return">
10000	<desc>
10001	State of the medium after the operation.
10002	</desc>
10003	</param>
10004	</method>
10005
10006	<method name="unlockRead">
10007	<desc>
10008	Cancels the read lock previously set by <link to="#lockRead"/>.
10009
10010	For both success and failure, this method returns the current state
10011	of the medium <i>after</i> the operation.
10012
10013	See <link to="#lockRead"/> for more details.
10014
10015	<result name="VBOX_E_INVALID_OBJECT_STATE">
10016	Medium not locked for reading.
10017	</result>
10018
10019	</desc>
10020	<param name="state" type="MediumState" dir="return">
10021	<desc>
10022	State of the medium after the operation.
10023	</desc>
10024	</param>
10025	</method>
10026
10027	<method name="lockWrite">
10028	<desc>
10029	Locks this medium for writing.
10030
10031	A write lock, as opposed to <link to="#lockRead"/>, is
10032	exclusive: there may be only one client holding a write lock,
10033	and there may be no read locks while the write lock is held.
10034	As a result, read-locking fails if a write lock is held, and
10035	write-locking fails if either a read or another write lock is held.
10036
10037	When a medium is locked for writing, it cannot be modified
10038	from within VirtualBox, and it is not guaranteed that the values
10039	of its properties are up-to-date. Any method that changes the
10040	properties of this medium or contents of the storage unit will
10041	return an error (unless explicitly stated otherwise).
10042
10043	When a virtual machine is started up, it locks for writing all
10044	media it uses to write data to. If any medium could not be locked
10045	for writing, the startup procedure will fail. If a medium has
10046	differencing images, then while the machine is running, only
10047	the last ("leaf") differencing image is locked for writing,
10048	whereas its parents are locked for reading only.
10049
10050	A medium is also locked for writing when it is the target of a
10051	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
10052
10053	The medium locked for writing must be unlocked using the <link
10054	to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
10055
10056	This method sets the medium state (see <link to="#state"/>) to
10057	"LockedWrite" on success. The medium's previous state must be
10058	either "Created" or "Inaccessible".
10059
10060	Locking an inaccessible medium is not an error; this method performs
10061	a logical lock that prevents modifications of this medium through
10062	the VirtualBox API, not a physical file-system lock of the underlying
10063	storage unit.
10064
10065	For both, success and failure, this method returns the current
10066	state of the medium <i>before</i> the operation.
10067
10068	<result name="VBOX_E_INVALID_OBJECT_STATE">
10069	Invalid medium state (e.g. not created, locked, inaccessible,
10070	creating, deleting).
10071	</result>
10072
10073	</desc>
10074	<param name="state" type="MediumState" dir="return">
10075	<desc>
10076	State of the medium after the operation.
10077	</desc>
10078	</param>
10079	</method>
10080
10081	<method name="unlockWrite">
10082	<desc>
10083	Cancels the write lock previously set by <link to="#lockWrite"/>.
10084
10085	For both success and failure, this method returns the current
10086	state of the medium <i>after</i> the operation.
10087
10088	See <link to="#lockWrite"/> for more details.
10089
10090	<result name="VBOX_E_INVALID_OBJECT_STATE">
10091	Medium not locked for writing.
10092	</result>
10093
10094	</desc>
10095	<param name="state" type="MediumState" dir="return">
10096	<desc>
10097	State of the medium after the operation.
10098	</desc>
10099	</param>
10100	</method>
10101
10102	<method name="close">
10103	<desc>
10104	Closes this medium.
10105
10106	The medium must not be attached to any known virtual machine
10107	and must not have any known child media, otherwise the
10108	operation will fail.
10109
10110	When the medium is successfully closed, it gets removed from
10111	the list of remembered media, but its storage unit is not
10112	deleted. In particular, this means that this medium can be
10113	later opened again using the <link
10114	to="IVirtualBox::openHardDisk"/> call.
10115
10116	Note that after this method successfully returns, the given medium
10117	object becomes uninitialized. This means that any attempt
10118	to call any of its methods or attributes will fail with the
10119	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
10120
10121	<result name="VBOX_E_INVALID_OBJECT_STATE">
10122	Invalid medium state (other than not created, created or
10123	inaccessible).
10124	</result>
10125	<result name="VBOX_E_OBJECT_IN_USE">
10126	Medium attached to virtual machine.
10127	</result>
10128	<result name="VBOX_E_FILE_ERROR">
10129	Settings file not accessible.
10130	</result>
10131	<result name="VBOX_E_XML_ERROR">
10132	Could not parse the settings file.
10133	</result>
10134
10135	</desc>
10136	</method>
10137
10138	<!-- storage methods -->
10139
10140	<method name="getProperty">
10141	<desc>
10142	Returns the value of the custom medium property with the given name.
10143
10144	The list of all properties supported by the given medium format can
10145	be obtained with <link to="IMediumFormat::describeProperties"/>.
10146
10147	Note that if this method returns an empty string in @a value, the
10148	requested property is supported but currently not assigned any value.
10149
10150	<result name="VBOX_E_OBJECT_NOT_FOUND">
10151	Requested property does not exist (not supported by the format).
10152	</result>
10153	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
10154	</desc>
10155	<param name="name" type="wstring" dir="in">
10156	<desc>Name of the property to get.</desc>
10157	</param>
10158	<param name="value" type="wstring" dir="return">
10159	<desc>Current property value.</desc>
10160	</param>
10161	</method>
10162
10163	<method name="setProperty">
10164	<desc>
10165	Sets the value of the custom medium property with the given name.
10166
10167	The list of all properties supported by the given medium format can
10168	be obtained with <link to="IMediumFormat::describeProperties"/>.
10169
10170	Note that setting the property value to @c null or an empty string is
10171	equivalent to deleting the existing value. A default value (if it is
10172	defined for this property) will be used by the format backend in this
10173	case.
10174
10175	<result name="VBOX_E_OBJECT_NOT_FOUND">
10176	Requested property does not exist (not supported by the format).
10177	</result>
10178	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
10179	</desc>
10180	<param name="name" type="wstring" dir="in">
10181	<desc>Name of the property to set.</desc>
10182	</param>
10183	<param name="value" type="wstring" dir="in">
10184	<desc>Property value to set.</desc>
10185	</param>
10186	</method>
10187
10188	<method name="getProperties">
10189	<desc>
10190	Returns values for a group of properties in one call.
10191
10192	The names of the properties to get are specified using the @a names
10193	argument which is a list of comma-separated property names or
10194	an empty string if all properties are to be returned. Note that currently
10195	the value of this argument is ignored and the method always returns all
10196	existing properties.
10197
10198	The list of all properties supported by the given medium format can
10199	be obtained with <link to="IMediumFormat::describeProperties"/>.
10200
10201	The method returns two arrays, the array of property names corresponding
10202	to the @a names argument and the current values of these properties.
10203	Both arrays have the same number of elements with each elemend at the
10204	given index in the first array corresponds to an element at the same
10205	index in the second array.
10206
10207	Note that for properties that do not have assigned values,
10208	an empty string is returned at the appropriate index in the
10209	@a returnValues array.
10210
10211	</desc>
10212	<param name="names" type="wstring" dir="in">
10213	<desc>
10214	Names of properties to get.
10215	</desc>
10216	</param>
10217	<param name="returnNames" type="wstring" safearray="yes" dir="out">
10218	<desc>Names of returned properties.</desc>
10219	</param>
10220	<param name="returnValues" type="wstring" safearray="yes" dir="return">
10221	<desc>Values of returned properties.</desc>
10222	</param>
10223	</method>
10224
10225	<method name="setProperties">
10226	<desc>
10227	Sets values for a group of properties in one call.
10228
10229	The names of the properties to set are passed in the @a names
10230	array along with the new values for them in the @a values array. Both
10231	arrays have the same number of elements with each elemend at the given
10232	index in the first array corresponding to an element at the same index
10233	in the second array.
10234
10235	If there is at least one property name in @a names that is not valid,
10236	the method will fail before changing the values of any other properties
10237	from the @a names array.
10238
10239	Using this method over <link to="#setProperty"/> is preferred if you
10240	need to set several properties at once since it will result into less
10241	IPC calls.
10242
10243	The list of all properties supported by the given medium format can
10244	be obtained with <link to="IMediumFormat::describeProperties"/>.
10245
10246	Note that setting the property value to @c null or an empty string is
10247	equivalent to deleting the existing value. A default value (if it is
10248	defined for this property) will be used by the format backend in this
10249	case.
10250	</desc>
10251	<param name="names" type="wstring" safearray="yes" dir="in">
10252	<desc>Names of properties to set.</desc>
10253	</param>
10254	<param name="values" type="wstring" safearray="yes" dir="in">
10255	<desc>Values of properties to set.</desc>
10256	</param>
10257	</method>
10258
10259	<!-- storage methods -->
10260
10261	<method name="createBaseStorage">
10262	<desc>
10263	Starts creating a hard disk storage unit (fixed/dynamic, according
10264	to the variant flags) in in the background. The previous storage unit
10265	created for this object, if any, must first be deleted using
10266	<link to="#deleteStorage"/>, otherwise the operation will fail.
10267
10268	Before the operation starts, the medium is placed in
10269	<link to="MediumState_Creating"/> state. If the create operation
10270	fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
10271	state.
10272
10273	After the returned progress object reports that the operation has
10274	successfully completed, the medium state will be set to <link
10275	to="MediumState_Created"/>, the medium will be remembered by this
10276	VirtualBox installation and may be attached to virtual machines.
10277
10278	<result name="VBOX_E_NOT_SUPPORTED">
10279	The variant of storage creation operation is not supported. See <link
10280	to="IMediumFormat::capabilities"/>.
10281	</result>
10282	</desc>
10283	<param name="logicalSize" type="unsigned long long" dir="in">
10284	<desc>Maximum logical size of the medium in megabytes.</desc>
10285	</param>
10286	<param name="variant" type="MediumVariant" dir="in">
10287	<desc>Exact image variant which should be created.</desc>
10288	</param>
10289	<param name="progress" type="IProgress" dir="return">
10290	<desc>Progress object to track the operation completion.</desc>
10291	</param>
10292	</method>
10293
10294	<method name="deleteStorage">
10295	<desc>
10296	Starts deleting the storage unit of this medium.
10297
10298	The medium must not be attached to any known virtual machine and must
10299	not have any known child media, otherwise the operation will fail.
10300	It will also fail if there is no storage unit to delete or if deletion
10301	is already in progress, or if the medium is being in use (locked for
10302	read or for write) or inaccessible. Therefore, the only valid state for
10303	this operation to succeed is <link to="MediumState_Created"/>.
10304
10305	Before the operation starts, the medium is placed in
10306	<link to="MediumState_Deleting"/> state and gets removed from the list
10307	of remembered hard disks (media registry). If the delete operation
10308	fails, the medium will be remembered again and placed back to
10309	<link to="MediumState_Created"/> state.
10310
10311	After the returned progress object reports that the operation is
10312	complete, the medium state will be set to
10313	<link to="MediumState_NotCreated"/> and you will be able to use one of
10314	the storage creation methods to create it again.
10315
10316	<see>#close()</see>
10317
10318	<result name="VBOX_E_OBJECT_IN_USE">
10319	Medium is attached to a virtual machine.
10320	</result>
10321	<result name="VBOX_E_NOT_SUPPORTED">
10322	Storage deletion is not allowed because neither of storage creation
10323	operations are supported. See
10324	<link to="IMediumFormat::capabilities"/>.
10325	</result>
10326
10327	<note>
10328	If the deletion operation fails, it is not guaranteed that the storage
10329	unit still exists. You may check the <link to="IMedium::state"/> value
10330	to answer this question.
10331	</note>
10332	</desc>
10333	<param name="progress" type="IProgress" dir="return">
10334	<desc>Progress object to track the operation completion.</desc>
10335	</param>
10336	</method>
10337
10338	<!-- diff methods -->
10339
10340	<method name="createDiffStorage">
10341	<desc>
10342	Starts creating an empty differencing storage unit based on this
10343	medium in the format and at the location defined by the @a target
10344	argument.
10345
10346	The target medium must be in <link to="MediumState_NotCreated"/>
10347	state (i.e. must not have an existing storage unit). Upon successful
10348	completion, this operation will set the type of the target medium to
10349	<link to="MediumType_Normal"/> and create a storage unit necessary to
10350	represent the differencing medium data in the given format (according
10351	to the storage format of the target object).
10352
10353	After the returned progress object reports that the operation is
10354	successfully complete, the target medium gets remembered by this
10355	VirtualBox installation and may be attached to virtual machines.
10356
10357	<note>
10358	The medium will be set to <link to="MediumState_LockedRead"/>
10359	state for the duration of this operation.
10360	</note>
10361	<result name="VBOX_E_OBJECT_IN_USE">
10362	Medium not in @c NotCreated state.
10363	</result>
10364	</desc>
10365	<param name="target" type="IMedium" dir="in">
10366	<desc>Target medium.</desc>
10367	</param>
10368	<param name="variant" type="MediumVariant" dir="in">
10369	<desc>Exact image variant which should be created.</desc>
10370	</param>
10371	<param name="progress" type="IProgress" dir="return">
10372	<desc>Progress object to track the operation completion.</desc>
10373	</param>
10374	</method>
10375
10376	<method name="mergeTo">
10377	<desc>
10378	Starts merging the contents of this medium and all intermediate
10379	differencing media in the chain to the given target medium.
10380
10381	The target medium must be either a descendant of this medium or
10382	its ancestor (otherwise this method will immediately return a failure).
10383	It follows that there are two logical directions of the merge operation:
10384	from ancestor to descendant (<i>forward merge</i>) and from descendant to
10385	ancestor (<i>backward merge</i>). Let us consider the following medium
10386	chain:
10387
10388	<pre>Base <- Diff_1 <- Diff_2</pre>
10389
10390	Here, calling this method on the <tt>Base</tt> medium object with
10391	<tt>Diff_2</tt> as an argument will be a forward merge; calling it on
10392	<tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
10393	merge. Note that in both cases the contents of the resulting medium
10394	will be the same, the only difference is the medium object that takes
10395	the result of the merge operation. In case of the forward merge in the
10396	above example, the result will be written to <tt>Diff_2</tt>; in case of
10397	the backward merge, the result will be written to <tt>Base</tt>. In
10398	other words, the result of the operation is always stored in the target
10399	medium.
10400
10401	Upon successful operation completion, the storage units of all media in
10402	the chain between this (source) medium and the target medium, including
10403	the source medium itself, will be automatically deleted and the
10404	relevant medium objects (including this medium) will become
10405	uninitialized. This means that any attempt to call any of
10406	their methods or attributes will fail with the
10407	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
10408	example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
10409	delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
10410	Note that <tt>Diff_2</tt> in this case will become a base medium
10411	itself since it will no longer be based on any other medium.
10412
10413	Considering the above, all of the following conditions must be met in
10414	order for the merge operation to succeed:
10415	<ul>
10416	<li>
10417	Neither this (source) medium nor any intermediate
10418	differencing medium in the chain between it and the target
10419	medium is attached to any virtual machine.
10420	</li>
10421	<li>
10422	Neither the source medium nor the target medium is an
10423	<link to="MediumType_Immutable"/> medium.
10424	</li>
10425	<li>
10426	The part of the medium tree from the source medium to the
10427	target medium is a linear chain, i.e. all medium in this
10428	chain have exactly one child which is the next medium in this
10429	chain. The only exception from this rule is the target medium in
10430	the forward merge operation; it is allowed to have any number of
10431	child media because the merge operation will not change its
10432	logical contents (as it is seen by the guest OS or by children).
10433	</li>
10434	<li>
10435	None of the involved media are in
10436	<link to="MediumState_LockedRead"/> or
10437	<link to="MediumState_LockedWrite"/> state.
10438	</li>
10439	</ul>
10440
10441	<note>
10442	This (source) medium and all intermediates will be placed to <link
10443	to="MediumState_Deleting"/> state and the target medium will be
10444	placed to <link to="MediumState_LockedWrite"/> state and for the
10445	duration of this operation.
10446	</note>
10447	</desc>
10448	<param name="target" type="IMedium" dir="in">
10449	<desc>Target medium.</desc>
10450	</param>
10451	<param name="progress" type="IProgress" dir="return">
10452	<desc>Progress object to track the operation completion.</desc>
10453	</param>
10454	</method>
10455
10456	<!-- clone method -->
10457
10458	<method name="cloneTo">
10459	<desc>
10460	Starts creating a clone of this medium in the format and at the
10461	location defined by the @a target argument.
10462
10463	The target medium must be either in <link to="MediumState_NotCreated"/>
10464	state (i.e. must not have an existing storage unit) or in
10465	<link to="MediumState_Created"/> state (i.e. created and not locked, and
10466	big enough to hold the data or else the copy will be partial). Upon
10467	successful completion, the cloned medium will contain exactly the
10468	same sector data as the medium being cloned, except that in the
10469	first case a new UUID for the clone will be randomly generated, and in
10470	the second case the UUID will remain unchanged.
10471
10472	The @a parent argument defines which medium will be the parent
10473	of the clone. Passing a @c null reference indicates that the clone will
10474	be a base image, i.e. completely independent. It is possible to specify
10475	an arbitrary medium for this parameter, including the parent of the
10476	medium which is being cloned. Even cloning to a child of the source
10477	medium is possible. Note that when cloning to an existing image, the
10478	@a parent irgument is ignored.
10479
10480	After the returned progress object reports that the operation is
10481	successfully complete, the target medium gets remembered by this
10482	VirtualBox installation and may be attached to virtual machines.
10483
10484	<note>
10485	This medium will be placed to <link to="MediumState_LockedRead"/>
10486	state for the duration of this operation.
10487	</note>
10488	<result name="E_NOTIMPL">
10489	The specified cloning variant is not supported at the moment.
10490	</result>
10491	</desc>
10492	<param name="target" type="IMedium" dir="in">
10493	<desc>Target medium.</desc>
10494	</param>
10495	<param name="variant" type="MediumVariant" dir="in">
10496	<desc>Exact image variant which should be created.</desc>
10497	</param>
10498	<param name="parent" type="IMedium" dir="in">
10499	<desc>Parent of the cloned medium.</desc>
10500	</param>
10501	<param name="progress" type="IProgress" dir="return">
10502	<desc>Progress object to track the operation completion.</desc>
10503	</param>
10504	</method>
10505
10506	<!-- other methods -->
10507
10508	<method name="compact">
10509	<desc>
10510	Starts compacting of this medium. This means that the medium is
10511	transformed into a possibly more compact storage representation.
10512	This potentially creates temporary images, which can require a
10513	substantial amount of additional disk space.
10514
10515	This medium will be placed to <link to="MediumState_LockedWrite"/>
10516	state and all its parent media (if any) will be placed to
10517	<link to="MediumState_LockedRead"/> state for the duration of this
10518	operation.
10519
10520	Please note that the results can be either returned straight away,
10521	or later as the result of the background operation via the object
10522	returned via the @a progress parameter.
10523
10524	<result name="VBOX_E_NOT_SUPPORTED">
10525	Medium format does not support compacting (but potentially
10526	needs it).
10527	</result>
10528	</desc>
10529	<param name="progress" type="IProgress" dir="return">
10530	<desc>Progress object to track the operation completion.</desc>
10531	</param>
10532	</method>
10533
10534	<method name="resize">
10535	<desc>
10536	Starts resizing this medium. This means that the nominal size of the
10537	medium is set to the new value. Both increasing and decreasing the
10538	size is possible, and there are no safety checks, since VirtualBox
10539	does not make any assumptions about the medium contents.
10540
10541	Resizing usually needs additional disk space, and possibly also
10542	some temporary disk space. Note that resize does not create a full
10543	temporary copy of the medium, so the additional disk space requirement
10544	is usually much lower than using the clone operation.
10545
10546	This medium will be placed to <link to="MediumState_LockedWrite"/>
10547	state for the duration of this operation.
10548
10549	Please note that the results can be either returned straight away,
10550	or later as the result of the background operation via the object
10551	returned via the @a progress parameter.
10552
10553	<result name="VBOX_E_NOT_SUPPORTED">
10554	Medium format does not support resizing.
10555	</result>
10556	</desc>
10557	<param name="logicalSize" type="unsigned long long" dir="in">
10558	<desc>New nominal capacity of the medium in megabytes.</desc>
10559	</param>
10560	<param name="progress" type="IProgress" dir="return">
10561	<desc>Progress object to track the operation completion.</desc>
10562	</param>
10563	</method>
10564
10565	<method name="reset">
10566	<desc>
10567	Starts erasing the contents of this differencing medium.
10568
10569	This operation will reset the differencing medium to its initial
10570	state when it does not contain any sector data and any read operation is
10571	redirected to its parent medium. This automatically gets called
10572	during VM power-up for every medium whose <link to="#autoReset" />
10573	attribute is @c true.
10574
10575	The medium will be write-locked for the duration of this operation (see
10576	<link to="#lockWrite" />).
10577
10578	<result name="VBOX_E_NOT_SUPPORTED">
10579	This is not a differencing medium.
10580	</result>
10581	<result name="VBOX_E_INVALID_OBJECT_STATE">
10582	Medium is not in <link to="MediumState_Created"/> or
10583	<link to="MediumState_Inaccessible"/> state.
10584	</result>
10585	</desc>
10586	<param name="progress" type="IProgress" dir="return">
10587	<desc>Progress object to track the operation completion.</desc>
10588	</param>
10589	</method>
10590
10591	</interface>
10592
10593
10594	<!--
10595	// IMediumFormat
10596	/////////////////////////////////////////////////////////////////////////
10597	-->
10598
10599	<enum
10600	name="DataType"
10601	uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
10602	>
10603	<const name="Int32" value="0"/>
10604	<const name="Int8" value="1"/>
10605	<const name="String" value="2"/>
10606	</enum>
10607
10608	<enum
10609	name="DataFlags"
10610	uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
10611	>
10612	<const name="None" value="0x00"/>
10613	<const name="Mandatory" value="0x01"/>
10614	<const name="Expert" value="0x02"/>
10615	<const name="Array" value="0x04"/>
10616	<const name="FlagMask" value="0x07"/>
10617	</enum>
10618
10619	<enum
10620	name="MediumFormatCapabilities"
10621	uuid="70fcf810-99e8-4edc-aee4-7f51d489e657"
10622	>
10623	<desc>
10624	Medium format capability flags.
10625	</desc>
10626
10627	<const name="Uuid" value="0x01">
10628	<desc>
10629	Supports UUIDs as expected by VirtualBox code.
10630	</desc>
10631	</const>
10632
10633	<const name="CreateFixed" value="0x02">
10634	<desc>
10635	Supports creating fixed size images, allocating all space instantly.
10636	</desc>
10637	</const>
10638
10639	<const name="CreateDynamic" value="0x04">
10640	<desc>
10641	Supports creating dynamically growing images, allocating space on
10642	demand.
10643	</desc>
10644	</const>
10645
10646	<const name="CreateSplit2G" value="0x08">
10647	<desc>
10648	Supports creating images split in chunks of a bit less than 2 GBytes.
10649	</desc>
10650	</const>
10651
10652	<const name="Differencing" value="0x10">
10653	<desc>
10654	Supports being used as a format for differencing media (see <link
10655	to="IMedium::createDiffStorage"/>).
10656	</desc>
10657	</const>
10658
10659	<const name="Asynchronous" value="0x20">
10660	<desc>
10661	Supports asynchronous I/O operations for at least some configurations.
10662	</desc>
10663	</const>
10664
10665	<const name="File" value="0x40">
10666	<desc>
10667	The format backend operates on files (the <link to="IMedium::location"/>
10668	attribute of the medium specifies a file used to store medium
10669	data; for a list of supported file extensions see
10670	<link to="IMediumFormat::fileExtensions"/>).
10671	</desc>
10672	</const>
10673
10674	<const name="Properties" value="0x80">
10675	<desc>
10676	The format backend uses the property interface to configure the storage
10677	location and properties (the <link to="IMediumFormat::describeProperties"/>
10678	method is used to get access to properties supported by the given medium format).
10679	</desc>
10680	</const>
10681
10682	<const name="CapabilityMask" value="0xFF"/>
10683	</enum>
10684
10685	<interface
10686	name="IMediumFormat" extends="$unknown"
10687	uuid="89f52554-d469-4799-9fad-1705e86a08b1"
10688	wsmap="managed"
10689	>
10690	<desc>
10691	The IMediumFormat interface represents a medium format.
10692
10693	Each medium format has an associated backend which is used to handle
10694	media stored in this format. This interface provides information
10695	about the properties of the associated backend.
10696
10697	Each medium format is identified by a string represented by the
10698	<link to="#id"/> attribute. This string is used in calls like
10699	<link to="IVirtualBox::createHardDisk"/> to specify the desired
10700	format.
10701
10702	The list of all supported medium formats can be obtained using
10703	<link to="ISystemProperties::mediaFormats"/>.
10704
10705	<see>IMedium</see>
10706	</desc>
10707
10708	<attribute name="id" type="wstring" readonly="yes">
10709	<desc>
10710	Identifier of this format.
10711
10712	The format identifier is a non-@c null non-empty ASCII string. Note that
10713	this string is case-insensitive. This means that, for example, all of
10714	the following strings:
10715	<pre>
10716	"VDI"
10717	"vdi"
10718	"VdI"</pre>
10719	refer to the same medium format.
10720
10721	This string is used in methods of other interfaces where it is necessary
10722	to specify a medium format, such as
10723	<link to="IVirtualBox::createHardDisk"/>.
10724	</desc>
10725	</attribute>
10726
10727	<attribute name="name" type="wstring" readonly="yes">
10728	<desc>
10729	Human readable description of this format.
10730
10731	Mainly for use in file open dialogs.
10732	</desc>
10733	</attribute>
10734
10735	<attribute name="fileExtensions" type="wstring" safearray="yes" readonly="yes">
10736	<desc>
10737	Array of strings containing the supported file extensions.
10738
10739	The first extension in the array is the extension preferred by the
10740	backend. It is recommended to use this extension when specifying a
10741	location of the storage unit for a new medium.
10742
10743	Note that some backends do not work on files, so this array may be
10744	empty.
10745
10746	<see>IMediumFormat::capabilities</see>
10747	</desc>
10748	</attribute>
10749
10750	<attribute name="capabilities" type="unsigned long" readonly="yes">
10751	<desc>
10752	Capabilities of the format as a set of bit flags.
10753
10754	For the meaning of individual capability flags see
10755	<link to="MediumFormatCapabilities"/>.
10756	</desc>
10757	</attribute>
10758
10759	<method name="describeProperties">
10760	<desc>
10761	Returns several arrays describing the properties supported by this
10762	format.
10763
10764	An element with the given index in each array describes one
10765	property. Thus, the number of elements in each returned array is the
10766	same and corresponds to the number of supported properties.
10767
10768	The returned arrays are filled in only if the
10769	<link to="MediumFormatCapabilities_Properties"/> flag is set.
10770	All arguments must be non-@c null.
10771
10772	<see>DataType</see>
10773	<see>DataFlags</see>
10774	</desc>
10775
10776	<param name="names" type="wstring" safearray="yes" dir="out">
10777	<desc>Array of property names.</desc>
10778	</param>
10779	<param name="description" type="wstring" safearray="yes" dir="out">
10780	<desc>Array of property descriptions.</desc>
10781	</param>
10782	<param name="types" type="DataType" safearray="yes" dir="out">
10783	<desc>Array of property types.</desc>
10784	</param>
10785	<param name="flags" type="unsigned long" safearray="yes" dir="out">
10786	<desc>Array of property flags.</desc>
10787	</param>
10788	<param name="defaults" type="wstring" safearray="yes" dir="out">
10789	<desc>Array of default property values.</desc>
10790	</param>
10791	</method>
10792
10793	</interface>
10794
10795
10796	<!--
10797	// IKeyboard
10798	/////////////////////////////////////////////////////////////////////////
10799	-->
10800
10801	<interface
10802	name="IKeyboard" extends="$unknown"
10803	uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
10804	wsmap="managed"
10805	>
10806	<desc>
10807	The IKeyboard interface represents the virtual machine's keyboard. Used
10808	in <link to="IConsole::keyboard"/>.
10809
10810	Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
10811	to the virtual machine.
10812
10813	</desc>
10814	<method name="putScancode">
10815	<desc>Sends a scancode to the keyboard.
10816
10817	<result name="VBOX_E_IPRT_ERROR">
10818	Could not send scan code to virtual keyboard.
10819	</result>
10820
10821	</desc>
10822	<param name="scancode" type="long" dir="in"/>
10823	</method>
10824
10825	<method name="putScancodes">
10826	<desc>Sends an array of scancodes to the keyboard.
10827
10828	<result name="VBOX_E_IPRT_ERROR">
10829	Could not send all scan codes to virtual keyboard.
10830	</result>
10831
10832	</desc>
10833	<param name="scancodes" type="long" dir="in" safearray="yes"/>
10834	<param name="codesStored" type="unsigned long" dir="return"/>
10835	</method>
10836
10837	<method name="putCAD">
10838	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
10839	function is nothing special, it is just a convenience function
10840	calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
10841
10842	<result name="VBOX_E_IPRT_ERROR">
10843	Could not send all scan codes to virtual keyboard.
10844	</result>
10845
10846	</desc>
10847	</method>
10848
10849	</interface>
10850
10851
10852	<!--
10853	// IMouse
10854	/////////////////////////////////////////////////////////////////////////
10855	-->
10856
10857	<enum
10858	name="MouseButtonState"
10859	uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
10860	>
10861	<desc>
10862	Mouse button state.
10863	</desc>
10864
10865	<const name="LeftButton" value="0x01"/>
10866	<const name="RightButton" value="0x02"/>
10867	<const name="MiddleButton" value="0x04"/>
10868	<const name="WheelUp" value="0x08"/>
10869	<const name="WheelDown" value="0x10"/>
10870	<const name="XButton1" value="0x20"/>
10871	<const name="XButton2" value="0x40"/>
10872	<const name="MouseStateMask" value="0x7F"/>
10873	</enum>
10874
10875	<interface
10876	name="IMouse" extends="$unknown"
10877	uuid="7c0f2eae-f92d-498c-b802-e1a3763774dc"
10878	wsmap="managed"
10879	>
10880	<desc>
10881	The IMouse interface represents the virtual machine's mouse. Used in
10882	<link to="IConsole::mouse"/>.
10883
10884	Through this interface, the virtual machine's virtual mouse can be
10885	controlled.
10886	</desc>
10887
10888	<attribute name="absoluteSupported" type="boolean" readonly="yes">
10889	<desc>
10890	Whether the guest OS supports absolute mouse pointer positioning
10891	or not.
10892	<note>
10893	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
10894	callback to be instantly informed about changes of this attribute
10895	during virtual machine execution.
10896	</note>
10897	<see><link to="#putMouseEventAbsolute"/></see>
10898	</desc>
10899	</attribute>
10900
10901	<attribute name="relativeSupported" type="boolean" readonly="yes">
10902	<desc>
10903	Whether the guest OS supports relative mouse pointer positioning
10904	or not.
10905	<note>
10906	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
10907	callback to be instantly informed about changes of this attribute
10908	during virtual machine execution.
10909	</note>
10910	<see><link to="#putMouseEvent"/></see>
10911	</desc>
10912	</attribute>
10913
10914	<attribute name="needsHostCursor" type="boolean" readonly="yes">
10915	<desc>
10916	Whether the guest OS can currently switch to drawing it's own mouse
10917	cursor on demand.
10918	<note>
10919	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
10920	callback to be instantly informed about changes of this attribute
10921	during virtual machine execution.
10922	</note>
10923	<see><link to="#putMouseEvent"/></see>
10924	</desc>
10925	</attribute>
10926
10927	<method name="putMouseEvent">
10928	<desc>
10929	Initiates a mouse event using relative pointer movements
10930	along x and y axis.
10931
10932	<result name="E_ACCESSDENIED">
10933	Console not powered up.
10934	</result>
10935	<result name="VBOX_E_IPRT_ERROR">
10936	Could not send mouse event to virtual mouse.
10937	</result>
10938
10939	</desc>
10940
10941	<param name="dx" type="long" dir="in">
10942	<desc>
10943	Amount of pixels the mouse should move to the right.
10944	Negative values move the mouse to the left.
10945	</desc>
10946	</param>
10947	<param name="dy" type="long" dir="in">
10948	<desc>
10949	Amount of pixels the mouse should move downwards.
10950	Negative values move the mouse upwards.
10951	</desc>
10952	</param>
10953	<param name="dz" type="long" dir="in">
10954	<desc>
10955	Amount of mouse wheel moves.
10956	Positive values describe clockwise wheel rotations,
10957	negative values describe counterclockwise rotations.
10958	</desc>
10959	</param>
10960	<param name="dw" type="long" dir="in">
10961	<desc>
10962	Amount of horizontal mouse wheel moves.
10963	Positive values describe a movement to the left,
10964	negative values describe a movement to the right.
10965	</desc>
10966	</param>
10967	<param name="buttonState" type="long" dir="in">
10968	<desc>
10969	The current state of mouse buttons. Every bit represents
10970	a mouse button as follows:
10971	<table>
10972	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
10973	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
10974	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
10975	</table>
10976	A value of <tt>1</tt> means the corresponding button is pressed.
10977	otherwise it is released.
10978	</desc>
10979	</param>
10980	</method>
10981
10982	<method name="putMouseEventAbsolute">
10983	<desc>
10984	Positions the mouse pointer using absolute x and y coordinates.
10985	These coordinates are expressed in pixels and
10986	start from <tt>[1,1]</tt> which corresponds to the top left
10987	corner of the virtual display.
10988
10989	<result name="E_ACCESSDENIED">
10990	Console not powered up.
10991	</result>
10992	<result name="VBOX_E_IPRT_ERROR">
10993	Could not send mouse event to virtual mouse.
10994	</result>
10995
10996	<note>
10997	This method will have effect only if absolute mouse
10998	positioning is supported by the guest OS.
10999	</note>
11000
11001	<see><link to="#absoluteSupported"/></see>
11002	</desc>
11003
11004	<param name="x" type="long" dir="in">
11005	<desc>
11006	X coordinate of the pointer in pixels, starting from @c 1.
11007	</desc>
11008	</param>
11009	<param name="y" type="long" dir="in">
11010	<desc>
11011	Y coordinate of the pointer in pixels, starting from @c 1.
11012	</desc>
11013	</param>
11014	<param name="dz" type="long" dir="in">
11015	<desc>
11016	Amount of mouse wheel moves.
11017	Positive values describe clockwise wheel rotations,
11018	negative values describe counterclockwise rotations.
11019	</desc>
11020	</param>
11021	<param name="dw" type="long" dir="in">
11022	<desc>
11023	Amount of horizontal mouse wheel moves.
11024	Positive values describe a movement to the left,
11025	negative values describe a movement to the right.
11026	</desc>
11027	</param>
11028	<param name="buttonState" type="long" dir="in">
11029	<desc>
11030	The current state of mouse buttons. Every bit represents
11031	a mouse button as follows:
11032	<table>
11033	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
11034	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
11035	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
11036	</table>
11037	A value of @c 1 means the corresponding button is pressed.
11038	otherwise it is released.
11039	</desc>
11040	</param>
11041	</method>
11042
11043	</interface>
11044
11045	<!--
11046	// IDisplay
11047	/////////////////////////////////////////////////////////////////////////
11048	-->
11049
11050	<enum
11051	name="FramebufferPixelFormat"
11052	uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
11053	>
11054	<desc>
11055	Format of the video memory buffer. Constants represented by this enum can
11056	be used to test for particular values of <link
11057	to="IFramebuffer::pixelFormat"/>. See also <link
11058	to="IFramebuffer::requestResize"/>.
11059
11060	See also www.fourcc.org for more information about FOURCC pixel formats.
11061	</desc>
11062
11063	<const name="Opaque" value="0">
11064	<desc>
11065	Unknown buffer format (the user may not assume any particular format of
11066	the buffer).
11067	</desc>
11068	</const>
11069	<const name="FOURCC_RGB" value="0x32424752">
11070	<desc>
11071	Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
11072	bit layout).
11073	</desc>
11074	</const>
11075	</enum>
11076
11077	<interface
11078	name="IFramebuffer" extends="$unknown"
11079	uuid="b7ed347a-5765-40a0-ae1c-f543eb4ddeaf"
11080	wsmap="suppress"
11081	>
11082	<attribute name="address" type="octet" mod="ptr" readonly="yes">
11083	<desc>Address of the start byte of the frame buffer.</desc>
11084	</attribute>
11085
11086	<attribute name="width" type="unsigned long" readonly="yes">
11087	<desc>Frame buffer width, in pixels.</desc>
11088	</attribute>
11089
11090	<attribute name="height" type="unsigned long" readonly="yes">
11091	<desc>Frame buffer height, in pixels.</desc>
11092	</attribute>
11093
11094	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
11095	<desc>
11096	Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
11097	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
11098	are: 8, 15, 16, 24 and 32.
11099	</desc>
11100	</attribute>
11101
11102	<attribute name="bytesPerLine" type="unsigned long" readonly="yes">
11103	<desc>
11104	Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
11105	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
11106	size of the scan line must be aligned to 32 bits.
11107	</desc>
11108	</attribute>
11109
11110	<attribute name="pixelFormat" type="unsigned long" readonly="yes">
11111	<desc>
11112	Frame buffer pixel format. It's either one of the values defined by <link
11113	to="FramebufferPixelFormat"/> or a raw FOURCC code.
11114	<note>
11115	This attribute must never return <link
11116	to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
11117	<link to="#address"/> points to must be always known.
11118	</note>
11119	</desc>
11120	</attribute>
11121
11122	<attribute name="usesGuestVRAM" type="boolean" readonly="yes">
11123	<desc>
11124	Defines whether this frame buffer uses the virtual video card's memory
11125	buffer (guest VRAM) directly or not. See <link
11126	to="IFramebuffer::requestResize"/> for more information.
11127	</desc>
11128	</attribute>
11129
11130	<attribute name="heightReduction" type="unsigned long" readonly="yes">
11131	<desc>
11132	Hint from the frame buffer about how much of the standard
11133	screen height it wants to use for itself. This information is
11134	exposed to the guest through the VESA BIOS and VMMDev interface
11135	so that it can use it for determining its video mode table. It
11136	is not guaranteed that the guest respects the value.
11137	</desc>
11138	</attribute>
11139
11140	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
11141	<desc>
11142	An alpha-blended overlay which is superposed over the frame buffer.
11143	The initial purpose is to allow the display of icons providing
11144	information about the VM state, including disk activity, in front
11145	ends which do not have other means of doing that. The overlay is
11146	designed to controlled exclusively by IDisplay. It has no locking
11147	of its own, and any changes made to it are not guaranteed to be
11148	visible until the affected portion of IFramebuffer is updated. The
11149	overlay can be created lazily the first time it is requested. This
11150	attribute can also return @c null to signal that the overlay is not
11151	implemented.
11152	</desc>
11153	</attribute>
11154
11155	<attribute name="winId" type="unsigned long long" readonly="yes">
11156	<desc>
11157	Platform-dependent identifier of the window where context of this
11158	frame buffer is drawn, or zero if there's no such window.
11159	</desc>
11160	</attribute>
11161
11162	<method name="lock">
11163	<desc>
11164	Locks the frame buffer.
11165	Gets called by the IDisplay object where this frame buffer is
11166	bound to.
11167	</desc>
11168	</method>
11169
11170	<method name="unlock">
11171	<desc>
11172	Unlocks the frame buffer.
11173	Gets called by the IDisplay object where this frame buffer is
11174	bound to.
11175	</desc>
11176	</method>
11177
11178	<method name="notifyUpdate">
11179	<desc>
11180	Informs about an update.
11181	Gets called by the display object where this buffer is
11182	registered.
11183	</desc>
11184	<param name="x" type="unsigned long" dir="in"/>
11185	<param name="y" type="unsigned long" dir="in"/>
11186	<param name="width" type="unsigned long" dir="in"/>
11187	<param name="height" type="unsigned long" dir="in"/>
11188	</method>
11189
11190	<method name="requestResize">
11191	<desc>
11192	Requests a size and pixel format change.
11193
11194	There are two modes of working with the video buffer of the virtual
11195	machine. The <i>indirect</i> mode implies that the IFramebuffer
11196	implementation allocates a memory buffer for the requested display mode
11197	and provides it to the virtual machine. In <i>direct</i> mode, the
11198	IFramebuffer implementation uses the memory buffer allocated and owned
11199	by the virtual machine. This buffer represents the video memory of the
11200	emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
11201	usually faster because the implementation gets a raw pointer to the
11202	guest VRAM buffer which it can directly use for visualizing the contents
11203	of the virtual display, as opposed to the indirect mode where the
11204	contents of guest VRAM are copied to the memory buffer provided by
11205	the implementation every time a display update occurs.
11206
11207	It is important to note that the direct mode is really fast only when
11208	the implementation uses the given guest VRAM buffer directly, for
11209	example, by blitting it to the window representing the virtual machine's
11210	display, which saves at least one copy operation comparing to the
11211	indirect mode. However, using the guest VRAM buffer directly is not
11212	always possible: the format and the color depth of this buffer may be
11213	not supported by the target window, or it may be unknown (opaque) as in
11214	case of text or non-linear multi-plane VGA video modes. In this case,
11215	the indirect mode (that is always available) should be used as a
11216	fallback: when the guest VRAM contents are copied to the
11217	implementation-provided memory buffer, color and format conversion is
11218	done automatically by the underlying code.
11219
11220	The @a pixelFormat parameter defines whether the direct mode is
11221	available or not. If @a pixelFormat is <link
11222	to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
11223	VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
11224	@a bytesPerLine parameters must be ignored and the implementation must use
11225	the indirect mode (where it provides its own buffer in one of the
11226	supported formats). In all other cases, @a pixelFormat together with
11227	@a bitsPerPixel and @a bytesPerLine define the format of the video memory
11228	buffer pointed to by the @a VRAM parameter and the implementation is
11229	free to choose which mode to use. To indicate that this frame buffer uses
11230	the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
11231	attribute must return @c true and <link to="#address"/> must
11232	return exactly the same address that is passed in the @a VRAM parameter
11233	of this method; otherwise it is assumed that the indirect strategy is
11234	chosen.
11235
11236	The @a width and @a height parameters represent the size of the
11237	requested display mode in both modes. In case of indirect mode, the
11238	provided memory buffer should be big enough to store data of the given
11239	display mode. In case of direct mode, it is guaranteed that the given
11240	@a VRAM buffer contains enough space to represent the display mode of the
11241	given size. Note that this frame buffer's <link to="#width"/> and <link
11242	to="#height"/> attributes must return exactly the same values as
11243	passed to this method after the resize is completed (see below).
11244
11245	The @a finished output parameter determines if the implementation has
11246	finished resizing the frame buffer or not. If, for some reason, the
11247	resize cannot be finished immediately during this call, @a finished
11248	must be set to @c false, and the implementation must call
11249	<link to="IDisplay::resizeCompleted"/> after it has returned from
11250	this method as soon as possible. If @a finished is @c false, the
11251	machine will not call any frame buffer methods until
11252	<link to="IDisplay::resizeCompleted"/> is called.
11253
11254	Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
11255	<link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
11256	this frame buffer must return exactly the same values as specified in the
11257	parameters of this method, after the resize is completed. If the
11258	indirect mode is chosen, these attributes must return values describing
11259	the format of the implementation's own memory buffer <link
11260	to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
11261	value must always correlate with <link to="#pixelFormat"/>. Note that
11262	the <link to="#pixelFormat"/> attribute must never return <link
11263	to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
11264
11265	<note>
11266	This method is called by the IDisplay object under the
11267	<link to="#lock"/> provided by this IFramebuffer
11268	implementation. If this method returns @c false in @a finished, then
11269	this lock is not released until
11270	<link to="IDisplay::resizeCompleted"/> is called.
11271	</note>
11272	</desc>
11273	<param name="screenId" type="unsigned long" dir="in">
11274	<desc>
11275	Logical screen number. Must be used in the corresponding call to
11276	<link to="IDisplay::resizeCompleted"/> if this call is made.
11277	</desc>
11278	</param>
11279	<param name="pixelFormat" type="unsigned long" dir="in">
11280	<desc>
11281	Pixel format of the memory buffer pointed to by @a VRAM.
11282	See also <link to="FramebufferPixelFormat"/>.
11283	</desc>
11284	</param>
11285	<param name="VRAM" type="octet" mod="ptr" dir="in">
11286	<desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
11287	</param>
11288	<param name="bitsPerPixel" type="unsigned long" dir="in">
11289	<desc>Color depth, bits per pixel.</desc>
11290	</param>
11291	<param name="bytesPerLine" type="unsigned long" dir="in">
11292	<desc>Size of one scan line, in bytes.</desc>
11293	</param>
11294	<param name="width" type="unsigned long" dir="in">
11295	<desc>Width of the guest display, in pixels.</desc>
11296	</param>
11297	<param name="height" type="unsigned long" dir="in">
11298	<desc>Height of the guest display, in pixels.</desc>
11299	</param>
11300	<param name="finished" type="boolean" dir="return">
11301	<desc>
11302	Can the VM start using the new frame buffer immediately
11303	after this method returns or it should wait for
11304	<link to="IDisplay::resizeCompleted"/>.
11305	</desc>
11306	</param>
11307	</method>
11308
11309	<method name="videoModeSupported">
11310	<desc>
11311	Returns whether the frame buffer implementation is willing to
11312	support a given video mode. In case it is not able to render
11313	the video mode (or for some reason not willing), it should
11314	return @c false. Usually this method is called when the guest
11315	asks the VMM device whether a given video mode is supported
11316	so the information returned is directly exposed to the guest.
11317	It is important that this method returns very quickly.
11318	</desc>
11319	<param name="width" type="unsigned long" dir="in"/>
11320	<param name="height" type="unsigned long" dir="in"/>
11321	<param name="bpp" type="unsigned long" dir="in"/>
11322	<param name="supported" type="boolean" dir="return"/>
11323	</method>
11324
11325	<method name="getVisibleRegion">
11326	<desc>
11327	Returns the visible region of this frame buffer.
11328
11329	If the @a rectangles parameter is @c null then the value of the
11330	@a count parameter is ignored and the number of elements necessary to
11331	describe the current visible region is returned in @a countCopied.
11332
11333	If @a rectangles is not @c null but @a count is less
11334	than the required number of elements to store region data, the method
11335	will report a failure. If @a count is equal or greater than the
11336	required number of elements, then the actual number of elements copied
11337	to the provided array will be returned in @a countCopied.
11338
11339	<note>
11340	The address of the provided array must be in the process space of
11341	this IFramebuffer object.
11342	</note>
11343	<note>
11344	Method not yet implemented.
11345	</note>
11346	</desc>
11347	<param name="rectangles" type="octet" mod="ptr" dir="in">
11348	<desc>Pointer to the @c RTRECT array to receive region data.</desc>
11349	</param>
11350	<param name="count" type="unsigned long" dir="in">
11351	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
11352	</param>
11353	<param name="countCopied" type="unsigned long" dir="return">
11354	<desc>Number of elements copied to the @a rectangles array.</desc>
11355	</param>
11356	</method>
11357
11358	<method name="setVisibleRegion">
11359	<desc>
11360	Suggests a new visible region to this frame buffer. This region
11361	represents the area of the VM display which is a union of regions of
11362	all top-level windows of the guest operating system running inside the
11363	VM (if the Guest Additions for this system support this
11364	functionality). This information may be used by the frontends to
11365	implement the seamless desktop integration feature.
11366
11367	<note>
11368	The address of the provided array must be in the process space of
11369	this IFramebuffer object.
11370	</note>
11371	<note>
11372	The IFramebuffer implementation must make a copy of the provided
11373	array of rectangles.
11374	</note>
11375	<note>
11376	Method not yet implemented.
11377	</note>
11378	</desc>
11379	<param name="rectangles" type="octet" mod="ptr" dir="in">
11380	<desc>Pointer to the @c RTRECT array.</desc>
11381	</param>
11382	<param name="count" type="unsigned long" dir="in">
11383	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
11384	</param>
11385	</method>
11386
11387	<method name="processVHWACommand">
11388	<desc>
11389	Posts a Video HW Acceleration Command to the frame buffer for processing.
11390	The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color covnersion, overlaying, etc.)
11391	are posted from quest to the host to be processed by the host hardware.
11392
11393	<note>
11394	The address of the provided command must be in the process space of
11395	this IFramebuffer object.
11396	</note>
11397	</desc>
11398
11399	<param name="command" type="octet" mod="ptr" dir="in">
11400	<desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
11401	</param>
11402	</method>
11403
11404	</interface>
11405
11406	<interface
11407	name="IFramebufferOverlay" extends="IFramebuffer"
11408	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
11409	wsmap="suppress"
11410	>
11411	<desc>
11412	The IFramebufferOverlay interface represents an alpha blended overlay
11413	for displaying status icons above an IFramebuffer. It is always created
11414	not visible, so that it must be explicitly shown. It only covers a
11415	portion of the IFramebuffer, determined by its width, height and
11416	co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
11417	that order) format, and may be written to directly. Do re-read the
11418	width though, after setting it, as it may be adjusted (increased) to
11419	make it more suitable for the front end.
11420	</desc>
11421	<attribute name="x" type="unsigned long" readonly="yes">
11422	<desc>X position of the overlay, relative to the frame buffer.</desc>
11423	</attribute>
11424
11425	<attribute name="y" type="unsigned long" readonly="yes">
11426	<desc>Y position of the overlay, relative to the frame buffer.</desc>
11427	</attribute>
11428
11429	<attribute name="visible" type="boolean" readonly="no">
11430	<desc>
11431	Whether the overlay is currently visible.
11432	</desc>
11433	</attribute>
11434
11435	<attribute name="alpha" type="unsigned long" readonly="no">
11436	<desc>
11437	The global alpha value for the overlay. This may or may not be
11438	supported by a given front end.
11439	</desc>
11440	</attribute>
11441
11442	<method name="move">
11443	<desc>
11444	Changes the overlay's position relative to the IFramebuffer.
11445	</desc>
11446	<param name="x" type="unsigned long" dir="in"/>
11447	<param name="y" type="unsigned long" dir="in"/>
11448	</method>
11449
11450	</interface>
11451
11452	<interface
11453	name="IDisplay" extends="$unknown"
11454	uuid="1fa79e39-0cc9-4ab3-9df3-ed3e96b42496"
11455	wsmap="managed"
11456	>
11457	<desc>
11458	The IDisplay interface represents the virtual machine's display.
11459
11460	The object implementing this interface is contained in each
11461	<link to="IConsole::display"/> attribute and represents the visual
11462	output of the virtual machine.
11463
11464	The virtual display supports pluggable output targets represented by the
11465	IFramebuffer interface. Examples of the output target are a window on
11466	the host computer or an RDP session's display on a remote computer.
11467	</desc>
11468	<method name="getScreenResolution">
11469	<desc>Queries display width, height and color depth for given screen.</desc>
11470	<param name="screenId" type="unsigned long" dir="in"/>
11471	<param name="width" type="unsigned long" dir="out"/>
11472	<param name="height" type="unsigned long" dir="out"/>
11473	<param name="bitsPerPixel" type="unsigned long" dir="out"/>
11474	</method>
11475
11476	<method name="setFramebuffer">
11477	<desc>
11478	Sets the framebuffer for given screen.
11479	</desc>
11480	<param name="screenId" type="unsigned long" dir="in"/>
11481	<param name="framebuffer" type="IFramebuffer" dir="in"/>
11482	</method>
11483
11484	<method name="getFramebuffer">
11485	<desc>
11486	Queries the framebuffer for given screen.
11487	</desc>
11488	<param name="screenId" type="unsigned long" dir="in"/>
11489	<param name="framebuffer" type="IFramebuffer" dir="out"/>
11490	<param name="xOrigin" type="long" dir="out"/>
11491	<param name="yOrigin" type="long" dir="out"/>
11492	</method>
11493
11494	<method name="setVideoModeHint">
11495	<desc>
11496	Asks VirtualBox to request the given video mode from
11497	the guest. This is just a hint and it cannot be guaranteed
11498	that the requested resolution will be used. Guest Additions
11499	are required for the request to be seen by guests. The caller
11500	should issue the request and wait for a resolution change and
11501	after a timeout retry.
11502
11503	Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
11504	parameters means that the corresponding values should be taken from the
11505	current video mode (i.e. left unchanged).
11506
11507	If the guest OS supports multi-monitor configuration then the @a display
11508	parameter specifies the number of the guest display to send the hint to:
11509	@c 0 is the primary display, @c 1 is the first secondary and
11510	so on. If the multi-monitor configuration is not supported, @a display
11511	must be @c 0.
11512
11513	<result name="E_INVALIDARG">
11514	The @a display is not associated with any monitor.
11515	</result>
11516
11517	</desc>
11518	<param name="width" type="unsigned long" dir="in"/>
11519	<param name="height" type="unsigned long" dir="in"/>
11520	<param name="bitsPerPixel" type="unsigned long" dir="in"/>
11521	<param name="display" type="unsigned long" dir="in"/>
11522	</method>
11523
11524	<method name="setSeamlessMode">
11525	<desc>
11526	Enables or disables seamless guest display rendering (seamless desktop
11527	integration) mode.
11528	<note>
11529	Calling this method has no effect if <link
11530	to="IGuest::supportsSeamless"/> returns @c false.
11531	</note>
11532	</desc>
11533	<param name="enabled" type="boolean" dir="in"/>
11534	</method>
11535
11536	<method name="takeScreenShot">
11537	<desc>
11538	Takes a screen shot of the requested size and copies it to the
11539	32-bpp buffer allocated by the caller and pointed to by @a address.
11540	A pixel consists of 4 bytes in order: B, G, R, 0.
11541
11542	<note>This API can be used only by the COM/XPCOM C++ API as it
11543	requires pointer support. Use <link to="#takeScreenShotToArray" />
11544	with other language bindings.
11545	</note>
11546
11547	<result name="E_NOTIMPL">
11548	Feature not implemented.
11549	</result>
11550	<result name="VBOX_E_IPRT_ERROR">
11551	Could not take a screenshot.
11552	</result>
11553
11554	</desc>
11555	<param name="screenId" type="unsigned long" dir="in"/>
11556	<param name="address" type="octet" mod="ptr" dir="in"/>
11557	<param name="width" type="unsigned long" dir="in"/>
11558	<param name="height" type="unsigned long" dir="in"/>
11559	</method>
11560
11561	<method name="takeScreenShotToArray">
11562	<desc>
11563	Takes a guest screen shot of the requested size and returns it as
11564	an array of bytes in uncompressed 32-bit RGBA format.
11565	A pixel consists of 4 bytes in order: R, G, B, 0xFF.
11566
11567	This API is slow, but could be the only option to get guest screenshot
11568	for scriptable languages not allowed to manipulate with addresses
11569	directly.
11570
11571	<result name="E_NOTIMPL">
11572	Feature not implemented.
11573	</result>
11574	<result name="VBOX_E_IPRT_ERROR">
11575	Could not take a screenshot.
11576	</result>
11577	</desc>
11578	<param name="screenId" type="unsigned long" dir="in">
11579	<desc>
11580	Monitor to take screenshot from.
11581	</desc>
11582	</param>
11583	<param name="width" type="unsigned long" dir="in">
11584	<desc>
11585	Desired image width.
11586	</desc>
11587	</param>
11588	<param name="height" type="unsigned long" dir="in">
11589	<desc>
11590	Desired image height.
11591	</desc>
11592	</param>
11593	<param name="screenData" type="octet" dir="return" safearray="yes">
11594	<desc>
11595	Array with resulting screen data.
11596	</desc>
11597	</param>
11598	</method>
11599
11600	<method name="drawToScreen">
11601	<desc>
11602	Draws a 32-bpp image of the specified size from the given buffer
11603	to the given point on the VM display.
11604
11605	<result name="E_NOTIMPL">
11606	Feature not implemented.
11607	</result>
11608	<result name="VBOX_E_IPRT_ERROR">
11609	Could not draw to screen.
11610	</result>
11611
11612	</desc>
11613	<param name="screenId" type="unsigned long" dir="in"/>
11614	<param name="address" type="octet" mod="ptr" dir="in"/>
11615	<param name="x" type="unsigned long" dir="in">
11616	<desc>Relative to the screen top left corner.</desc>
11617	</param>
11618	<param name="y" type="unsigned long" dir="in">
11619	<desc>Relative to the screen top left corner.</desc>
11620	</param>
11621	<param name="width" type="unsigned long" dir="in"/>
11622	<param name="height" type="unsigned long" dir="in"/>
11623	</method>
11624
11625	<method name="invalidateAndUpdate">
11626	<desc>
11627	Does a full invalidation of the VM display and instructs the VM
11628	to update it.
11629
11630	<result name="VBOX_E_IPRT_ERROR">
11631	Could not invalidate and update screen.
11632	</result>
11633
11634	</desc>
11635	</method>
11636
11637	<method name="resizeCompleted">
11638	<desc>
11639	Signals that a framebuffer has completed the resize operation.
11640
11641	<result name="VBOX_E_NOT_SUPPORTED">
11642	Operation only valid for external frame buffers.
11643	</result>
11644
11645	</desc>
11646	<param name="screenId" type="unsigned long" dir="in"/>
11647	</method>
11648
11649	<method name="completeVHWACommand">
11650	<desc>
11651	Signals that the Video HW Acceleration command has completed.
11652	</desc>
11653
11654	<param name="command" type="octet" mod="ptr" dir="in">
11655	<desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
11656	</param>
11657	</method>
11658
11659	</interface>
11660
11661	<!--
11662	// INetworkAdapter
11663	/////////////////////////////////////////////////////////////////////////
11664	-->
11665
11666	<enum
11667	name="NetworkAttachmentType"
11668	uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
11669	>
11670	<desc>
11671	Network attachment type.
11672	</desc>
11673
11674	<const name="Null" value="0">
11675	<desc>Null value, also means "not attached".</desc>
11676	</const>
11677	<const name="NAT" value="1"/>
11678	<const name="Bridged" value="2"/>
11679	<const name="Internal" value="3"/>
11680	<const name="HostOnly" value="4"/>
11681	<const name="VDE" value="5"/>
11682	</enum>
11683
11684	<enum
11685	name="NetworkAdapterType"
11686	uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
11687	>
11688	<desc>
11689	Network adapter type.
11690	</desc>
11691
11692	<const name="Null" value="0">
11693	<desc>Null value (never used by the API).</desc>
11694	</const>
11695	<const name="Am79C970A" value="1">
11696	<desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
11697	</const>
11698	<const name="Am79C973" value="2">
11699	<desc>AMD PCNet-FAST III network card (Am79C973).</desc>
11700	</const>
11701	<const name="I82540EM" value="3">
11702	<desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
11703	</const>
11704	<const name="I82543GC" value="4">
11705	<desc>Intel PRO/1000 T Server network card (82543GC).</desc>
11706	</const>
11707	<const name="I82545EM" value="5">
11708	<desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
11709	</const>
11710	<const name="Virtio" value="6">
11711	<desc>Virtio network device.</desc>
11712	</const>
11713	</enum>
11714
11715	<interface
11716	name="INetworkAdapter" extends="$unknown"
11717	uuid="5bdb9df8-a5e1-4322-a139-b7a4a734c790"
11718	wsmap="managed"
11719	>
11720	<desc>
11721	Represents a virtual network adapter that is attached to a virtual machine.
11722	Each virtual machine has a fixed number of network adapter slots with one
11723	instance of this attached to each of them. Call
11724	<link to="IMachine::getNetworkAdapter" /> to get the network adapter that
11725	is attached to a given slot in a given machine.
11726
11727	Each network adapter can be in one of five attachment modes, which are
11728	represented by the <link to="NetworkAttachmentType" /> enumeration;
11729	see the <link to="#attachmentType" /> attribute.
11730	</desc>
11731
11732	<attribute name="adapterType" type="NetworkAdapterType">
11733	<desc>
11734	Type of the virtual network adapter. Depending on this value,
11735	VirtualBox will provide a different virtual network hardware
11736	to the guest.
11737	</desc>
11738	</attribute>
11739
11740	<attribute name="slot" type="unsigned long" readonly="yes">
11741	<desc>
11742	Slot number this adapter is plugged into. Corresponds to
11743	the value you pass to <link to="IMachine::getNetworkAdapter"/>
11744	to obtain this instance.
11745	</desc>
11746	</attribute>
11747
11748	<attribute name="enabled" type="boolean">
11749	<desc>
11750	Flag whether the network adapter is present in the
11751	guest system. If disabled, the virtual guest hardware will
11752	not contain this network adapter. Can only be changed when
11753	the VM is not running.
11754	</desc>
11755	</attribute>
11756
11757	<attribute name="MACAddress" type="wstring">
11758	<desc>
11759	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
11760	it to @c null or an empty string, VirtualBox will generate a unique MAC address.
11761	</desc>
11762	</attribute>
11763
11764	<attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
11765
11766	<attribute name="hostInterface" type="wstring">
11767	<desc>
11768	Name of the host network interface the VM is attached to.
11769	</desc>
11770	</attribute>
11771
11772	<attribute name="internalNetwork" type="wstring">
11773	<desc>
11774	Name of the internal network the VM is attached to.
11775	</desc>
11776	</attribute>
11777
11778	<attribute name="NATNetwork" type="wstring">
11779	<desc>
11780	Name of the NAT network the VM is attached to.
11781	</desc>
11782	</attribute>
11783
11784	<attribute name="VDENetwork" type="wstring">
11785	<desc>
11786	Name of the VDE switch the VM is attached to.
11787	</desc>
11788	</attribute>
11789
11790	<attribute name="cableConnected" type="boolean">
11791	<desc>
11792	Flag whether the adapter reports the cable as connected or not.
11793	It can be used to report offline situations to a VM.
11794	</desc>
11795	</attribute>
11796
11797	<attribute name="lineSpeed" type="unsigned long">
11798	<desc>
11799	Line speed reported by custom drivers, in units of 1 kbps.
11800	</desc>
11801	</attribute>
11802
11803	<attribute name="traceEnabled" type="boolean">
11804	<desc>
11805	Flag whether network traffic from/to the network card should be traced.
11806	Can only be toggled when the VM is turned off.
11807	</desc>
11808	</attribute>
11809
11810	<attribute name="traceFile" type="wstring">
11811	<desc>
11812	Filename where a network trace will be stored. If not set, VBox-pid.pcap
11813	will be used.
11814	</desc>
11815	</attribute>
11816
11817	<attribute name="natDriver" type="INATEngine" readonly="yes">
11818	<desc>
11819	Points to the NAT engine which handles the network address translation
11820	for this interface. This is active only when the interface actually uses
11821	NAT (see <link to="#attachToNAT" />).
11822	</desc>
11823	</attribute>
11824
11825	<attribute name="bootPriority" type="unsigned long">
11826	<desc>
11827	Network boot priority of the adapter. Priority 1 is highest. If not set,
11828	the priority is considered to be at the lowest possible setting.
11829	</desc>
11830	</attribute>
11831
11832	<method name="attachToNAT">
11833	<desc>
11834	Attach the network adapter to the Network Address Translation (NAT) interface.
11835	</desc>
11836	</method>
11837
11838	<method name="attachToBridgedInterface">
11839	<desc>
11840	Attach the network adapter to a bridged host interface.
11841	</desc>
11842	</method>
11843
11844	<method name="attachToInternalNetwork">
11845	<desc>
11846	Attach the network adapter to an internal network.
11847	</desc>
11848	</method>
11849
11850	<method name="attachToHostOnlyInterface">
11851	<desc>
11852	Attach the network adapter to the host-only network.
11853	</desc>
11854	</method>
11855
11856	<method name="attachToVDE">
11857	<desc>
11858	Attach the network adapter to a VDE network.
11859	</desc>
11860	</method>
11861
11862	<method name="detach">
11863	<desc>
11864	Detach the network adapter
11865	</desc>
11866	</method>
11867	</interface>
11868
11869
11870	<!--
11871	// ISerialPort
11872	/////////////////////////////////////////////////////////////////////////
11873	-->
11874
11875	<enum
11876	name="PortMode"
11877	uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
11878	>
11879	<desc>
11880	The PortMode enumeration represents possible communication modes for
11881	the virtual serial port device.
11882	</desc>
11883
11884	<const name="Disconnected" value="0">
11885	<desc>Virtual device is not attached to any real host device.</desc>
11886	</const>
11887	<const name="HostPipe" value="1">
11888	<desc>Virtual device is attached to a host pipe.</desc>
11889	</const>
11890	<const name="HostDevice" value="2">
11891	<desc>Virtual device is attached to a host device.</desc>
11892	</const>
11893	<const name="RawFile" value="3">
11894	<desc>Virtual device is attached to a raw file.</desc>
11895	</const>
11896	</enum>
11897
11898	<interface
11899	name="ISerialPort" extends="$unknown"
11900	uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
11901	wsmap="managed"
11902	>
11903
11904	<desc>
11905	The ISerialPort interface represents the virtual serial port device.
11906
11907	The virtual serial port device acts like an ordinary serial port
11908	inside the virtual machine. This device communicates to the real
11909	serial port hardware in one of two modes: host pipe or host device.
11910
11911	In host pipe mode, the #path attribute specifies the path to the pipe on
11912	the host computer that represents a serial port. The #server attribute
11913	determines if this pipe is created by the virtual machine process at
11914	machine startup or it must already exist before starting machine
11915	execution.
11916
11917	In host device mode, the #path attribute specifies the name of the
11918	serial port device on the host computer.
11919
11920	There is also a third communication mode: the disconnected mode. In this
11921	mode, the guest OS running inside the virtual machine will be able to
11922	detect the serial port, but all port write operations will be discarded
11923	and all port read operations will return no data.
11924
11925	<see>IMachine::getSerialPort</see>
11926	</desc>
11927
11928	<attribute name="slot" type="unsigned long" readonly="yes">
11929	<desc>
11930	Slot number this serial port is plugged into. Corresponds to
11931	the value you pass to <link to="IMachine::getSerialPort"/>
11932	to obtain this instance.
11933	</desc>
11934	</attribute>
11935
11936	<attribute name="enabled" type="boolean">
11937	<desc>
11938	Flag whether the serial port is enabled. If disabled,
11939	the serial port will not be reported to the guest OS.
11940	</desc>
11941	</attribute>
11942
11943	<attribute name="IOBase" type="unsigned long">
11944	<desc>Base I/O address of the serial port.</desc>
11945	</attribute>
11946
11947	<attribute name="IRQ" type="unsigned long">
11948	<desc>IRQ number of the serial port.</desc>
11949	</attribute>
11950
11951	<attribute name="hostMode" type="PortMode">
11952	<desc>
11953	How is this port connected to the host.
11954	<note>
11955	Changing this attribute may fail if the conditions for
11956	<link to="#path"/> are not met.
11957	</note>
11958	</desc>
11959	</attribute>
11960
11961	<attribute name="server" type="boolean">
11962	<desc>
11963	Flag whether this serial port acts as a server (creates a new pipe on
11964	the host) or as a client (uses the existing pipe). This attribute is
11965	used only when <link to="#hostMode"/> is PortMode_HostPipe.
11966	</desc>
11967	</attribute>
11968
11969	<attribute name="path" type="wstring">
11970	<desc>
11971	Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
11972	PortMode_HostPipe, or the host serial device name when
11973	<link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
11974	cases, setting a @c null or empty string as the attribute's value
11975	is an error. Otherwise, the value of this property is ignored.
11976	</desc>
11977	</attribute>
11978
11979	</interface>
11980
11981	<!--
11982	// IParallelPort
11983	/////////////////////////////////////////////////////////////////////////
11984	-->
11985
11986	<interface
11987	name="IParallelPort" extends="$unknown"
11988	uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
11989	wsmap="managed"
11990	>
11991
11992	<desc>
11993	The IParallelPort interface represents the virtual parallel port device.
11994
11995	The virtual parallel port device acts like an ordinary parallel port
11996	inside the virtual machine. This device communicates to the real
11997	parallel port hardware using the name of the parallel device on the host
11998	computer specified in the #path attribute.
11999
12000	Each virtual parallel port device is assigned a base I/O address and an
12001	IRQ number that will be reported to the guest operating system and used
12002	to operate the given parallel port from within the virtual machine.
12003
12004	<see>IMachine::getParallelPort</see>
12005	</desc>
12006
12007	<attribute name="slot" type="unsigned long" readonly="yes">
12008	<desc>
12009	Slot number this parallel port is plugged into. Corresponds to
12010	the value you pass to <link to="IMachine::getParallelPort"/>
12011	to obtain this instance.
12012	</desc>
12013	</attribute>
12014
12015	<attribute name="enabled" type="boolean">
12016	<desc>
12017	Flag whether the parallel port is enabled. If disabled,
12018	the parallel port will not be reported to the guest OS.
12019	</desc>
12020	</attribute>
12021
12022	<attribute name="IOBase" type="unsigned long">
12023	<desc>Base I/O address of the parallel port.</desc>
12024	</attribute>
12025
12026	<attribute name="IRQ" type="unsigned long">
12027	<desc>IRQ number of the parallel port.</desc>
12028	</attribute>
12029
12030	<attribute name="path" type="wstring">
12031	<desc>
12032	Host parallel device name. If this parallel port is enabled, setting a
12033	@c null or an empty string as this attribute's value will result into
12034	an error.
12035	</desc>
12036	</attribute>
12037
12038	</interface>
12039
12040
12041	<!--
12042	// IMachineDebugger
12043	/////////////////////////////////////////////////////////////////////////
12044	-->
12045
12046	<interface
12047	name="IMachineDebugger" extends="$unknown"
12048	uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
12049	wsmap="suppress"
12050	>
12051	<method name="resetStats">
12052	<desc>
12053	Reset VM statistics.
12054	</desc>
12055	<param name="pattern" type="wstring" dir="in">
12056	<desc>The selection pattern. A bit similar to filename globbing.</desc>
12057	</param>
12058	</method>
12059
12060	<method name="dumpStats">
12061	<desc>
12062	Dumps VM statistics.
12063	</desc>
12064	<param name="pattern" type="wstring" dir="in">
12065	<desc>The selection pattern. A bit similar to filename globbing.</desc>
12066	</param>
12067	</method>
12068
12069	<method name="getStats">
12070	<desc>
12071	Get the VM statistics in a XMLish format.
12072	</desc>
12073	<param name="pattern" type="wstring" dir="in">
12074	<desc>The selection pattern. A bit similar to filename globbing.</desc>
12075	</param>
12076	<param name="withDescriptions" type="boolean" dir="in">
12077	<desc>Whether to include the descriptions.</desc>
12078	</param>
12079	<param name="stats" type="wstring" dir="out">
12080	<desc>The XML document containing the statistics.</desc>
12081	</param>
12082	</method>
12083
12084	<method name="injectNMI">
12085	<desc>
12086	Inject an NMI into a running VT-x/AMD-V VM.
12087	</desc>
12088	</method>
12089
12090	<attribute name="singlestep" type="boolean">
12091	<desc>Switch for enabling singlestepping.</desc>
12092	</attribute>
12093
12094	<attribute name="recompileUser" type="boolean">
12095	<desc>Switch for forcing code recompilation for user mode code.</desc>
12096	</attribute>
12097
12098	<attribute name="recompileSupervisor" type="boolean">
12099	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
12100	</attribute>
12101
12102	<attribute name="PATMEnabled" type="boolean">
12103	<desc>Switch for enabling and disabling the PATM component.</desc>
12104	</attribute>
12105
12106	<attribute name="CSAMEnabled" type="boolean">
12107	<desc>Switch for enabling and disabling the CSAM component.</desc>
12108	</attribute>
12109
12110	<attribute name="logEnabled" type="boolean">
12111	<desc>Switch for enabling and disabling logging.</desc>
12112	</attribute>
12113
12114	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
12115	<desc>
12116	Flag indicating whether the VM is currently making use of CPU hardware
12117	virtualization extensions.
12118	</desc>
12119	</attribute>
12120
12121	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
12122	<desc>
12123	Flag indicating whether the VM is currently making use of the nested paging
12124	CPU hardware virtualization extension.
12125	</desc>
12126	</attribute>
12127
12128	<attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
12129	<desc>
12130	Flag indicating whether the VM is currently making use of the VPID
12131	VT-x extension.
12132	</desc>
12133	</attribute>
12134
12135	<attribute name="PAEEnabled" type="boolean" readonly="yes">
12136	<desc>
12137	Flag indicating whether the VM is currently making use of the Physical
12138	Address Extension CPU feature.
12139	</desc>
12140	</attribute>
12141
12142	<attribute name="virtualTimeRate" type="unsigned long">
12143	<desc>
12144	The rate at which the virtual time runs expressed as a percentage.
12145	The accepted range is 2% to 20000%.
12146	</desc>
12147	</attribute>
12148
12149	<!-- @todo method for setting log flags, groups and destination! -->
12150
12151	<attribute name="VM" type="unsigned long long" readonly="yes">
12152	<desc>
12153	Gets the VM handle. This is only for internal use while
12154	we carve the details of this interface.
12155	</desc>
12156	</attribute>
12157
12158	</interface>
12159
12160	<!--
12161	// IUSBController
12162	/////////////////////////////////////////////////////////////////////////
12163	-->
12164
12165	<interface
12166	name="IUSBController" extends="$unknown"
12167	uuid="6fdcccc5-abd3-4fec-9387-2ad3914fc4a8"
12168	wsmap="managed"
12169	>
12170	<attribute name="enabled" type="boolean">
12171	<desc>
12172	Flag whether the USB controller is present in the
12173	guest system. If disabled, the virtual guest hardware will
12174	not contain any USB controller. Can only be changed when
12175	the VM is powered off.
12176	</desc>
12177	</attribute>
12178
12179	<attribute name="enabledEhci" type="boolean">
12180	<desc>
12181	Flag whether the USB EHCI controller is present in the
12182	guest system. If disabled, the virtual guest hardware will
12183	not contain a USB EHCI controller. Can only be changed when
12184	the VM is powered off.
12185	</desc>
12186	</attribute>
12187
12188	<attribute name="proxyAvailable" type="boolean" readonly="yes">
12189	<desc>
12190	Flag whether there is an USB proxy available.
12191	</desc>
12192	</attribute>
12193
12194	<attribute name="USBStandard" type="unsigned short" readonly="yes">
12195	<desc>
12196	USB standard version which the controller implements.
12197	This is a BCD which means that the major version is in the
12198	high byte and minor version is in the low byte.
12199	</desc>
12200	</attribute>
12201
12202	<attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
12203	<desc>
12204	List of USB device filters associated with the machine.
12205
12206	If the machine is currently running, these filters are activated
12207	every time a new (supported) USB device is attached to the host
12208	computer that was not ignored by global filters
12209	(<link to="IHost::USBDeviceFilters"/>).
12210
12211	These filters are also activated when the machine is powered up.
12212	They are run against a list of all currently available USB
12213	devices (in states
12214	<link to="USBDeviceState_Available"/>,
12215	<link to="USBDeviceState_Busy"/>,
12216	<link to="USBDeviceState_Held"/>) that were not previously
12217	ignored by global filters.
12218
12219	If at least one filter matches the USB device in question, this
12220	device is automatically captured (attached to) the virtual USB
12221	controller of this machine.
12222
12223	<see>IUSBDeviceFilter, ::IUSBController</see>
12224	</desc>
12225	</attribute>
12226
12227	<method name="createDeviceFilter">
12228	<desc>
12229	Creates a new USB device filter. All attributes except
12230	the filter name are set to empty (any match),
12231	<i>active</i> is @c false (the filter is not active).
12232
12233	The created filter can then be added to the list of filters using
12234	<link to="#insertDeviceFilter"/>.
12235
12236	<result name="VBOX_E_INVALID_VM_STATE">
12237	The virtual machine is not mutable.
12238	</result>
12239
12240	<see>#deviceFilters</see>
12241	</desc>
12242	<param name="name" type="wstring" dir="in">
12243	<desc>
12244	Filter name. See <link to="IUSBDeviceFilter::name"/>
12245	for more info.
12246	</desc>
12247	</param>
12248	<param name="filter" type="IUSBDeviceFilter" dir="return">
12249	<desc>Created filter object.</desc>
12250	</param>
12251	</method>
12252
12253	<method name="insertDeviceFilter">
12254	<desc>
12255	Inserts the given USB device to the specified position
12256	in the list of filters.
12257
12258	Positions are numbered starting from <tt>0</tt>. If the specified
12259	position is equal to or greater than the number of elements in
12260	the list, the filter is added to the end of the collection.
12261
12262	<note>
12263	Duplicates are not allowed, so an attempt to insert a
12264	filter that is already in the collection, will return an
12265	error.
12266	</note>
12267
12268	<result name="VBOX_E_INVALID_VM_STATE">
12269	Virtual machine is not mutable.
12270	</result>
12271	<result name="E_INVALIDARG">
12272	USB device filter not created within this VirtualBox instance.
12273	</result>
12274	<result name="VBOX_E_INVALID_OBJECT_STATE">
12275	USB device filter already in list.
12276	</result>
12277
12278	<see>#deviceFilters</see>
12279	</desc>
12280	<param name="position" type="unsigned long" dir="in">
12281	<desc>Position to insert the filter to.</desc>
12282	</param>
12283	<param name="filter" type="IUSBDeviceFilter" dir="in">
12284	<desc>USB device filter to insert.</desc>
12285	</param>
12286	</method>
12287
12288	<method name="removeDeviceFilter">
12289	<desc>
12290	Removes a USB device filter from the specified position in the
12291	list of filters.
12292
12293	Positions are numbered starting from <tt>0</tt>. Specifying a
12294	position equal to or greater than the number of elements in
12295	the list will produce an error.
12296
12297	<see>#deviceFilters</see>
12298
12299	<result name="VBOX_E_INVALID_VM_STATE">
12300	Virtual machine is not mutable.
12301	</result>
12302	<result name="E_INVALIDARG">
12303	USB device filter list empty or invalid @a position.
12304	</result>
12305
12306	</desc>
12307	<param name="position" type="unsigned long" dir="in">
12308	<desc>Position to remove the filter from.</desc>
12309	</param>
12310	<param name="filter" type="IUSBDeviceFilter" dir="return">
12311	<desc>Removed USB device filter.</desc>
12312	</param>
12313	</method>
12314
12315	</interface>
12316
12317
12318	<!--
12319	// IUSBDevice
12320	/////////////////////////////////////////////////////////////////////////
12321	-->
12322
12323	<interface
12324	name="IUSBDevice" extends="$unknown"
12325	uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
12326	wsmap="managed"
12327	>
12328	<desc>
12329	The IUSBDevice interface represents a virtual USB device attached to the
12330	virtual machine.
12331
12332	A collection of objects implementing this interface is stored in the
12333	<link to="IConsole::USBDevices"/> attribute which lists all USB devices
12334	attached to a running virtual machine's USB controller.
12335	</desc>
12336
12337	<attribute name="id" type="uuid" mod="string" readonly="yes">
12338	<desc>
12339	Unique USB device ID. This ID is built from #vendorId,
12340	#productId, #revision and #serialNumber.
12341	</desc>
12342	</attribute>
12343
12344	<attribute name="vendorId" type="unsigned short" readonly="yes">
12345	<desc>Vendor ID.</desc>
12346	</attribute>
12347
12348	<attribute name="productId" type="unsigned short" readonly="yes">
12349	<desc>Product ID.</desc>
12350	</attribute>
12351
12352	<attribute name="revision" type="unsigned short" readonly="yes">
12353	<desc>
12354	Product revision number. This is a packed BCD represented as
12355	unsigned short. The high byte is the integer part and the low
12356	byte is the decimal.
12357	</desc>
12358	</attribute>
12359
12360	<attribute name="manufacturer" type="wstring" readonly="yes">
12361	<desc>Manufacturer string.</desc>
12362	</attribute>
12363
12364	<attribute name="product" type="wstring" readonly="yes">
12365	<desc>Product string.</desc>
12366	</attribute>
12367
12368	<attribute name="serialNumber" type="wstring" readonly="yes">
12369	<desc>Serial number string.</desc>
12370	</attribute>
12371
12372	<attribute name="address" type="wstring" readonly="yes">
12373	<desc>Host specific address of the device.</desc>
12374	</attribute>
12375
12376	<attribute name="port" type="unsigned short" readonly="yes">
12377	<desc>
12378	Host USB port number the device is physically
12379	connected to.
12380	</desc>
12381	</attribute>
12382
12383	<attribute name="version" type="unsigned short" readonly="yes">
12384	<desc>
12385	The major USB version of the device - 1 or 2.
12386	</desc>
12387	</attribute>
12388
12389	<attribute name="portVersion" type="unsigned short" readonly="yes">
12390	<desc>
12391	The major USB version of the host USB port the device is
12392	physically connected to - 1 or 2. For devices not connected to
12393	anything this will have the same value as the version attribute.
12394	</desc>
12395	</attribute>
12396
12397	<attribute name="remote" type="boolean" readonly="yes">
12398	<desc>
12399	Whether the device is physically connected to a remote VRDP
12400	client or to a local host machine.
12401	</desc>
12402	</attribute>
12403
12404	</interface>
12405
12406
12407	<!--
12408	// IUSBDeviceFilter
12409	/////////////////////////////////////////////////////////////////////////
12410	-->
12411
12412	<interface
12413	name="IUSBDeviceFilter" extends="$unknown"
12414	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
12415	wsmap="managed"
12416	>
12417	<desc>
12418	The IUSBDeviceFilter interface represents an USB device filter used
12419	to perform actions on a group of USB devices.
12420
12421	This type of filters is used by running virtual machines to
12422	automatically capture selected USB devices once they are physically
12423	attached to the host computer.
12424
12425	A USB device is matched to the given device filter if and only if all
12426	attributes of the device match the corresponding attributes of the
12427	filter (that is, attributes are joined together using the logical AND
12428	operation). On the other hand, all together, filters in the list of
12429	filters carry the semantics of the logical OR operation. So if it is
12430	desirable to create a match like "this vendor id OR this product id",
12431	one needs to create two filters and specify "any match" (see below)
12432	for unused attributes.
12433
12434	All filter attributes used for matching are strings. Each string
12435	is an expression representing a set of values of the corresponding
12436	device attribute, that will match the given filter. Currently, the
12437	following filtering expressions are supported:
12438
12439	<ul>
12440	<li><i>Interval filters</i>. Used to specify valid intervals for
12441	integer device attributes (Vendor ID, Product ID and Revision).
12442	The format of the string is:
12443
12444	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
12445
12446	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
12447	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
12448	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
12449	is omitted before a dash (<tt>-</tt>), the minimum possible integer
12450	is assumed; if <tt>n</tt> is omitted after a dash, the maximum
12451	possible integer is assumed.
12452	</li>
12453	<li><i>Boolean filters</i>. Used to specify acceptable values for
12454	boolean device attributes. The format of the string is:
12455
12456	<tt>true\|false\|yes\|no\|0\|1</tt>
12457
12458	</li>
12459	<li><i>Exact match</i>. Used to specify a single value for the given
12460	device attribute. Any string that doesn't start with <tt>int:</tt>
12461	represents the exact match. String device attributes are compared to
12462	this string including case of symbols. Integer attributes are first
12463	converted to a string (see individual filter attributes) and then
12464	compared ignoring case.
12465
12466	</li>
12467	<li><i>Any match</i>. Any value of the corresponding device attribute
12468	will match the given filter. An empty or @c null string is
12469	used to construct this type of filtering expressions.
12470
12471	</li>
12472	</ul>
12473
12474	<note>
12475	On the Windows host platform, interval filters are not currently
12476	available. Also all string filter attributes
12477	(<link to="#manufacturer"/>, <link to="#product"/>,
12478	<link to="#serialNumber"/>) are ignored, so they behave as
12479	<i>any match</i> no matter what string expression is specified.
12480	</note>
12481
12482	<see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
12483	</desc>
12484
12485	<attribute name="name" type="wstring">
12486	<desc>
12487	Visible name for this filter.
12488	This name is used to visually distinguish one filter from another,
12489	so it can neither be @c null nor an empty string.
12490	</desc>
12491	</attribute>
12492
12493	<attribute name="active" type="boolean">
12494	<desc>Whether this filter active or has been temporarily disabled.</desc>
12495	</attribute>
12496
12497	<attribute name="vendorId" type="wstring">
12498	<desc>
12499	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
12500	The string representation for the <i>exact matching</i>
12501	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
12502	(including leading zeroes).
12503	</desc>
12504	</attribute>
12505
12506	<attribute name="productId" type="wstring">
12507	<desc>
12508	<link to="IUSBDevice::productId">Product ID</link> filter.
12509	The string representation for the <i>exact matching</i>
12510	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
12511	(including leading zeroes).
12512	</desc>
12513	</attribute>
12514
12515	<attribute name="revision" type="wstring">
12516	<desc>
12517	<link to="IUSBDevice::productId">Product revision number</link>
12518	filter. The string representation for the <i>exact matching</i>
12519	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
12520	of the integer part of the revision, and <tt>F</tt> is the
12521	decimal digit of its fractional part (including leading and
12522	trailing zeros).
12523	Note that for interval filters, it's best to use the hexadecimal
12524	form, because the revision is stored as a 16 bit packed BCD value;
12525	so the expression <tt>int:0x0100-0x0199</tt> will match any
12526	revision from <tt>1.0</tt> to <tt>1.99</tt>.
12527	</desc>
12528	</attribute>
12529
12530	<attribute name="manufacturer" type="wstring">
12531	<desc>
12532	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
12533	</desc>
12534	</attribute>
12535
12536	<attribute name="product" type="wstring">
12537	<desc>
12538	<link to="IUSBDevice::product">Product</link> filter.
12539	</desc>
12540	</attribute>
12541
12542	<attribute name="serialNumber" type="wstring">
12543	<desc>
12544	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
12545	</desc>
12546	</attribute>
12547
12548	<attribute name="port" type="wstring">
12549	<desc>
12550	<link to="IUSBDevice::port">Host USB port</link> filter.
12551	</desc>
12552	</attribute>
12553
12554	<attribute name="remote" type="wstring">
12555	<desc>
12556	<link to="IUSBDevice::remote">Remote state</link> filter.
12557	<note>
12558	This filter makes sense only for machine USB filters,
12559	i.e. it is ignored by IHostUSBDeviceFilter objects.
12560	</note>
12561	</desc>
12562	</attribute>
12563
12564	<attribute name="maskedInterfaces" type="unsigned long">
12565	<desc>
12566	This is an advanced option for hiding one or more USB interfaces
12567	from the guest. The value is a bit mask where the bits that are set
12568	means the corresponding USB interface should be hidden, masked off
12569	if you like.
12570	This feature only works on Linux hosts.
12571	</desc>
12572	</attribute>
12573
12574	</interface>
12575
12576
12577	<!--
12578	// IHostUSBDevice
12579	/////////////////////////////////////////////////////////////////////////
12580	-->
12581
12582	<enum
12583	name="USBDeviceState"
12584	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
12585	>
12586	<desc>
12587	USB device state. This enumeration represents all possible states
12588	of the USB device physically attached to the host computer regarding
12589	its state on the host computer and availability to guest computers
12590	(all currently running virtual machines).
12591
12592	Once a supported USB device is attached to the host, global USB
12593	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
12594	either ignore the device, or put it to USBDeviceState_Held state, or do
12595	nothing. Unless the device is ignored by global filters, filters of all
12596	currently running guests (<link to="IUSBController::deviceFilters"/>) are
12597	activated that can put it to USBDeviceState_Captured state.
12598
12599	If the device was ignored by global filters, or didn't match
12600	any filters at all (including guest ones), it is handled by the host
12601	in a normal way. In this case, the device state is determined by
12602	the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
12603	or USBDeviceState_Available, depending on the current device usage.
12604
12605	Besides auto-capturing based on filters, the device can be manually
12606	captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
12607	state is USBDeviceState_Busy, USBDeviceState_Available or
12608	USBDeviceState_Held.
12609
12610	<note>
12611	Due to differences in USB stack implementations in Linux and Win32,
12612	states USBDeviceState_Busy and USBDeviceState_vailable are applicable
12613	only to the Linux version of the product. This also means that (<link
12614	to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
12615	device state is USBDeviceState_Held.
12616	</note>
12617
12618	<see>IHostUSBDevice, IHostUSBDeviceFilter</see>
12619	</desc>
12620
12621	<const name="NotSupported" value="0">
12622	<desc>
12623	Not supported by the VirtualBox server, not available to guests.
12624	</desc>
12625	</const>
12626	<const name="Unavailable" value="1">
12627	<desc>
12628	Being used by the host computer exclusively,
12629	not available to guests.
12630	</desc>
12631	</const>
12632	<const name="Busy" value="2">
12633	<desc>
12634	Being used by the host computer, potentially available to guests.
12635	</desc>
12636	</const>
12637	<const name="Available" value="3">
12638	<desc>
12639	Not used by the host computer, available to guests (the host computer
12640	can also start using the device at any time).
12641	</desc>
12642	</const>
12643	<const name="Held" value="4">
12644	<desc>
12645	Held by the VirtualBox server (ignored by the host computer),
12646	available to guests.
12647	</desc>
12648	</const>
12649	<const name="Captured" value="5">
12650	<desc>
12651	Captured by one of the guest computers, not available
12652	to anybody else.
12653	</desc>
12654	</const>
12655	</enum>
12656
12657	<interface
12658	name="IHostUSBDevice" extends="IUSBDevice"
12659	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
12660	wsmap="managed"
12661	>
12662	<desc>
12663	The IHostUSBDevice interface represents a physical USB device attached
12664	to the host computer.
12665
12666	Besides properties inherited from IUSBDevice, this interface adds the
12667	<link to="#state"/> property that holds the current state of the USB
12668	device.
12669
12670	<see>IHost::USBDevices, IHost::USBDeviceFilters</see>
12671	</desc>
12672
12673	<attribute name="state" type="USBDeviceState" readonly="yes">
12674	<desc>
12675	Current state of the device.
12676	</desc>
12677	</attribute>
12678
12679	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
12680
12681	</interface>
12682
12683
12684	<!--
12685	// IHostUSBDeviceFilter
12686	/////////////////////////////////////////////////////////////////////////
12687	-->
12688
12689	<enum
12690	name="USBDeviceFilterAction"
12691	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
12692	>
12693	<desc>
12694	Actions for host USB device filters.
12695	<see>IHostUSBDeviceFilter, USBDeviceState</see>
12696	</desc>
12697
12698	<const name="Null" value="0">
12699	<desc>Null value (never used by the API).</desc>
12700	</const>
12701	<const name="Ignore" value="1">
12702	<desc>Ignore the matched USB device.</desc>
12703	</const>
12704	<const name="Hold" value="2">
12705	<desc>Hold the matched USB device.</desc>
12706	</const>
12707	</enum>
12708
12709	<interface
12710	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
12711	uuid="4cc70246-d74a-400f-8222-3900489c0374"
12712	wsmap="managed"
12713	>
12714	<desc>
12715	The IHostUSBDeviceFilter interface represents a global filter for a
12716	physical USB device used by the host computer. Used indirectly in
12717	<link to="IHost::USBDeviceFilters"/>.
12718
12719	Using filters of this type, the host computer determines the initial
12720	state of the USB device after it is physically attached to the
12721	host's USB controller.
12722
12723	<note>
12724	The <link to="#remote"/> attribute is ignored by this type of
12725	filters, because it makes sense only for
12726	<link to="IUSBController::deviceFilters">machine USB filters</link>.
12727	</note>
12728
12729	<see>IHost::USBDeviceFilters</see>
12730	</desc>
12731
12732	<attribute name="action" type="USBDeviceFilterAction">
12733	<desc>
12734	Action performed by the host when an attached USB device
12735	matches this filter.
12736	</desc>
12737	</attribute>
12738
12739	</interface>
12740
12741	<!--
12742	// IAudioAdapter
12743	/////////////////////////////////////////////////////////////////////////
12744	-->
12745
12746	<enum
12747	name="AudioDriverType"
12748	uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
12749	>
12750	<desc>
12751	Host audio driver type.
12752	</desc>
12753
12754	<const name="Null" value="0">
12755	<desc>Null value, also means "dummy audio driver".</desc>
12756	</const>
12757	<const name="WinMM" value="1">
12758	<desc>Windows multimedia (Windows hosts only).</desc>
12759	</const>
12760	<const name="OSS" value="2">
12761	<desc>Open Sound System (Linux hosts only).</desc>
12762	</const>
12763	<const name="ALSA" value="3">
12764	<desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
12765	</const>
12766	<const name="DirectSound" value="4">
12767	<desc>DirectSound (Windows hosts only).</desc>
12768	</const>
12769	<const name="CoreAudio" value="5">
12770	<desc>CoreAudio (Mac hosts only).</desc>
12771	</const>
12772	<const name="MMPM" value="6">
12773	<desc>Reserved for historical reasons.</desc>
12774	</const>
12775	<const name="Pulse" value="7">
12776	<desc>PulseAudio (Linux hosts only).</desc>
12777	</const>
12778	<const name="SolAudio" value="8">
12779	<desc>Solaris audio (Solaris hosts only).</desc>
12780	</const>
12781	</enum>
12782
12783	<enum
12784	name="AudioControllerType"
12785	uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
12786	>
12787	<desc>
12788	Virtual audio controller type.
12789	</desc>
12790
12791	<const name="AC97" value="0"/>
12792	<const name="SB16" value="1"/>
12793	</enum>
12794
12795	<interface
12796	name="IAudioAdapter" extends="$unknown"
12797	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
12798	wsmap="managed"
12799	>
12800	<desc>
12801	The IAudioAdapter interface represents the virtual audio adapter of
12802	the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
12803	</desc>
12804	<attribute name="enabled" type="boolean">
12805	<desc>
12806	Flag whether the audio adapter is present in the
12807	guest system. If disabled, the virtual guest hardware will
12808	not contain any audio adapter. Can only be changed when
12809	the VM is not running.
12810	</desc>
12811	</attribute>
12812	<attribute name="audioController" type="AudioControllerType">
12813	<desc>
12814	The audio hardware we emulate.
12815	</desc>
12816	</attribute>
12817	<attribute name="audioDriver" type="AudioDriverType">
12818	<desc>
12819	Audio driver the adapter is connected to. This setting
12820	can only be changed when the VM is not running.
12821	</desc>
12822	</attribute>
12823	</interface>
12824
12825	<!--
12826	// IVRDPServer
12827	/////////////////////////////////////////////////////////////////////////
12828	-->
12829
12830	<enum
12831	name="VRDPAuthType"
12832	uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
12833	>
12834	<desc>
12835	VRDP authentication type.
12836	</desc>
12837
12838	<const name="Null" value="0">
12839	<desc>Null value, also means "no authentication".</desc>
12840	</const>
12841	<const name="External" value="1"/>
12842	<const name="Guest" value="2"/>
12843	</enum>
12844
12845	<interface
12846	name="IVRDPServer" extends="$unknown"
12847	uuid="7aeeb530-0b08-41fe-835d-9be9ec1dbe5c"
12848	wsmap="managed"
12849	>
12850	<attribute name="enabled" type="boolean">
12851	<desc>VRDP server status.</desc>
12852	</attribute>
12853
12854	<attribute name="ports" type="wstring">
12855	<desc>
12856	VRDP server port numbers. The server will try to bind to one of free ports from the list.
12857	<note>
12858	This is a string of comma separated TCP port numbers or port number ranges.
12859	Example <tt>5000,5010-5012,5015</tt>
12860	</note>
12861	</desc>
12862	</attribute>
12863
12864	<attribute name="netAddress" type="wstring">
12865	<desc>VRDP server address.</desc>
12866	</attribute>
12867
12868	<attribute name="authType" type="VRDPAuthType">
12869	<desc>VRDP authentication method.</desc>
12870	</attribute>
12871
12872	<attribute name="authTimeout" type="unsigned long">
12873	<desc>Timeout for guest authentication. Milliseconds.</desc>
12874	</attribute>
12875
12876	<attribute name="allowMultiConnection" type="boolean">
12877	<desc>
12878	Flag whether multiple simultaneous connections to the VM are permitted.
12879	Note that this will be replaced by a more powerful mechanism in the future.
12880	</desc>
12881	</attribute>
12882
12883	<attribute name="reuseSingleConnection" type="boolean">
12884	<desc>
12885	Flag whether the existing connection must be dropped and a new connection
12886	must be established by the VRDP server, when a new client connects in single
12887	connection mode.
12888	</desc>
12889	</attribute>
12890
12891	<attribute name="videoChannel" type="boolean">
12892	<desc>
12893	Flag whether RDP video channel is supported.
12894	</desc>
12895	</attribute>
12896
12897	<attribute name="videoChannelQuality" type="unsigned long">
12898	<desc>
12899	Image quality in percents.
12900	</desc>
12901	</attribute>
12902
12903	</interface>
12904
12905
12906	<!--
12907	// ISharedFolder
12908	/////////////////////////////////////////////////////////////////////////
12909	-->
12910
12911	<interface
12912	name="ISharedFolder" extends="$unknown"
12913	uuid="64637bb2-9e17-471c-b8f3-f8968dd9884e"
12914	wsmap="struct"
12915	>
12916	<desc>
12917	The ISharedFolder interface represents a folder in the host computer's
12918	file system accessible from the guest OS running inside a virtual
12919	machine using an associated logical name.
12920
12921	There are three types of shared folders:
12922	<ul>
12923	<li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
12924	folders available to all virtual machines.</li>
12925	<li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
12926	VM-specific shared folders available to the given virtual machine at
12927	startup.</li>
12928	<li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
12929	VM-specific shared folders created in the session context (for
12930	example, when the virtual machine is running) and automatically
12931	discarded when the session is closed (the VM is powered off).</li>
12932	</ul>
12933
12934	Logical names of shared folders must be unique within the given scope
12935	(global, permanent or transient). However, they do not need to be unique
12936	across scopes. In this case, the definition of the shared folder in a
12937	more specific scope takes precedence over definitions in all other
12938	scopes. The order of precedence is (more specific to more general):
12939	<ol>
12940	<li>Transient definitions</li>
12941	<li>Permanent definitions</li>
12942	<li>Global definitions</li>
12943	</ol>
12944
12945	For example, if MyMachine has a shared folder named
12946	<tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
12947	transient shared folder named <tt>C_DRIVE</tt> (that points
12948	to <tt>C:\\\\WINDOWS</tt>) will change the definition
12949	of <tt>C_DRIVE</tt> in the guest OS so
12950	that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
12951	to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
12952	PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
12953	the previous (permanent) definition of <tt>C_DRIVE</tt> that points
12954	to <tt>C:\\</tt> if it still exists.
12955
12956	Note that permanent and transient shared folders of different machines
12957	are in different name spaces, so they don't overlap and don't need to
12958	have unique logical names.
12959
12960	<note>
12961	Global shared folders are not implemented in the current version of the
12962	product.
12963	</note>
12964	</desc>
12965
12966	<attribute name="name" type="wstring" readonly="yes">
12967	<desc>Logical name of the shared folder.</desc>
12968	</attribute>
12969
12970	<attribute name="hostPath" type="wstring" readonly="yes">
12971	<desc>Full path to the shared folder in the host file system.</desc>
12972	</attribute>
12973
12974	<attribute name="accessible" type="boolean" readonly="yes">
12975	<desc>
12976	Whether the folder defined by the host path is currently
12977	accessible or not.
12978	For example, the folder can be unaccessible if it is placed
12979	on the network share that is not available by the time
12980	this property is read.
12981	</desc>
12982	</attribute>
12983
12984	<attribute name="writable" type="boolean" readonly="yes">
12985	<desc>
12986	Whether the folder defined by the host path is writable or
12987	not.
12988	</desc>
12989	</attribute>
12990
12991	<attribute name="lastAccessError" type="wstring" readonly="yes">
12992	<desc>
12993	Text message that represents the result of the last accessibility
12994	check.
12995
12996	Accessibility checks are performed each time the <link to="#accessible"/>
12997	attribute is read. An empty string is returned if the last
12998	accessibility check was successful. A non-empty string indicates a
12999	failure and should normally describe a reason of the failure (for
13000	example, a file read error).
13001	</desc>
13002	</attribute>
13003
13004	</interface>
13005
13006	<!--
13007	// ISession
13008	/////////////////////////////////////////////////////////////////////////
13009	-->
13010
13011	<interface
13012	name="IInternalSessionControl" extends="$unknown"
13013	uuid="cc8d63a0-568e-45dd-9bf6-6354049ece1e"
13014	internal="yes"
13015	wsmap="suppress"
13016	>
13017	<method name="getPID">
13018	<desc>PID of the process that has created this Session object.
13019	</desc>
13020	<param name="pid" type="unsigned long" dir="return"/>
13021	</method>
13022
13023	<method name="getRemoteConsole">
13024	<desc>
13025	Returns the console object suitable for remote control.
13026
13027	<result name="VBOX_E_INVALID_VM_STATE">
13028	Session state prevents operation.
13029	</result>
13030	<result name="VBOX_E_INVALID_OBJECT_STATE">
13031	Session type prevents operation.
13032	</result>
13033
13034	</desc>
13035	<param name="console" type="IConsole" dir="return"/>
13036	</method>
13037
13038	<method name="assignMachine">
13039	<desc>
13040	Assigns the machine object associated with this direct-type
13041	session or informs the session that it will be a remote one
13042	(if @a machine == @c null).
13043
13044	<result name="VBOX_E_INVALID_VM_STATE">
13045	Session state prevents operation.
13046	</result>
13047	<result name="VBOX_E_INVALID_OBJECT_STATE">
13048	Session type prevents operation.
13049	</result>
13050
13051	</desc>
13052	<param name="machine" type="IMachine" dir="in"/>
13053	</method>
13054
13055	<method name="assignRemoteMachine">
13056	<desc>
13057	Assigns the machine and the (remote) console object associated with
13058	this remote-type session.
13059
13060	<result name="VBOX_E_INVALID_VM_STATE">
13061	Session state prevents operation.
13062	</result>
13063
13064	</desc>
13065	<param name="machine" type="IMachine" dir="in"/>
13066	<param name="console" type="IConsole" dir="in"/>
13067	</method>
13068
13069	<method name="updateMachineState">
13070	<desc>
13071	Updates the machine state in the VM process.
13072	Must be called only in certain cases
13073	(see the method implementation).
13074
13075	<result name="VBOX_E_INVALID_VM_STATE">
13076	Session state prevents operation.
13077	</result>
13078	<result name="VBOX_E_INVALID_OBJECT_STATE">
13079	Session type prevents operation.
13080	</result>
13081
13082	</desc>
13083	<param name="aMachineState" type="MachineState" dir="in"/>
13084	</method>
13085
13086	<method name="uninitialize">
13087	<desc>
13088	Uninitializes (closes) this session. Used by VirtualBox to close
13089	the corresponding remote session when the direct session dies
13090	or gets closed.
13091
13092	<result name="VBOX_E_INVALID_VM_STATE">
13093	Session state prevents operation.
13094	</result>
13095
13096	</desc>
13097	</method>
13098
13099	<method name="onNetworkAdapterChange">
13100	<desc>
13101	Triggered when settings of a network adapter of the
13102	associated virtual machine have changed.
13103
13104	<result name="VBOX_E_INVALID_VM_STATE">
13105	Session state prevents operation.
13106	</result>
13107	<result name="VBOX_E_INVALID_OBJECT_STATE">
13108	Session type prevents operation.
13109	</result>
13110
13111	</desc>
13112	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
13113	<param name="changeAdapter" type="boolean" dir="in"/>
13114	</method>
13115
13116	<method name="onSerialPortChange">
13117	<desc>
13118	Triggered when settings of a serial port of the
13119	associated virtual machine have changed.
13120
13121	<result name="VBOX_E_INVALID_VM_STATE">
13122	Session state prevents operation.
13123	</result>
13124	<result name="VBOX_E_INVALID_OBJECT_STATE">
13125	Session type prevents operation.
13126	</result>
13127
13128	</desc>
13129	<param name="serialPort" type="ISerialPort" dir="in"/>
13130	</method>
13131
13132	<method name="onParallelPortChange">
13133	<desc>
13134	Triggered when settings of a parallel port of the
13135	associated virtual machine have changed.
13136
13137	<result name="VBOX_E_INVALID_VM_STATE">
13138	Session state prevents operation.
13139	</result>
13140	<result name="VBOX_E_INVALID_OBJECT_STATE">
13141	Session type prevents operation.
13142	</result>
13143
13144	</desc>
13145	<param name="parallelPort" type="IParallelPort" dir="in"/>
13146	</method>
13147
13148	<method name="onStorageControllerChange">
13149	<desc>
13150	Triggered when settings of a storage controller of the
13151	associated virtual machine have changed.
13152
13153	<result name="VBOX_E_INVALID_VM_STATE">
13154	Session state prevents operation.
13155	</result>
13156	<result name="VBOX_E_INVALID_OBJECT_STATE">
13157	Session type prevents operation.
13158	</result>
13159
13160	</desc>
13161	</method>
13162
13163	<method name="onMediumChange">
13164	<desc>
13165	Triggered when attached media of the
13166	associated virtual machine have changed.
13167
13168	<result name="VBOX_E_INVALID_VM_STATE">
13169	Session state prevents operation.
13170	</result>
13171	<result name="VBOX_E_INVALID_OBJECT_STATE">
13172	Session type prevents operation.
13173	</result>
13174
13175	</desc>
13176
13177	<param name="mediumAttachment" type="IMediumAttachment" dir="in"/>
13178	<param name="force" type="boolean" dir="in"/>
13179	</method>
13180
13181	<method name="onCPUChange">
13182	<desc>
13183	Notification when a CPU changes.
13184	</desc>
13185	<param name="cpu" type="unsigned long" dir="in">
13186	<desc>The CPU which changed</desc>
13187	</param>
13188	<param name="add" type="boolean" dir="in">
13189	<desc>Flag whether the CPU was added or removed</desc>
13190	</param>
13191	</method>
13192
13193	<method name="onVRDPServerChange">
13194	<desc>
13195	Triggered when settings of the VRDP server object of the
13196	associated virtual machine have changed.
13197
13198	<result name="VBOX_E_INVALID_VM_STATE">
13199	Session state prevents operation.
13200	</result>
13201	<result name="VBOX_E_INVALID_OBJECT_STATE">
13202	Session type prevents operation.
13203	</result>
13204
13205	</desc>
13206	</method>
13207
13208	<method name="onUSBControllerChange">
13209	<desc>
13210	Triggered when settings of the USB controller object of the
13211	associated virtual machine have changed.
13212
13213	<result name="VBOX_E_INVALID_VM_STATE">
13214	Session state prevents operation.
13215	</result>
13216	<result name="VBOX_E_INVALID_OBJECT_STATE">
13217	Session type prevents operation.
13218	</result>
13219
13220	</desc>
13221	</method>
13222
13223	<method name="onSharedFolderChange">
13224	<desc>
13225	Triggered when a permanent (global or machine) shared folder has been
13226	created or removed.
13227	<note>
13228	We don't pass shared folder parameters in this notification because
13229	the order in which parallel notifications are delivered is not defined,
13230	therefore it could happen that these parameters were outdated by the
13231	time of processing this notification.
13232	</note>
13233
13234	<result name="VBOX_E_INVALID_VM_STATE">
13235	Session state prevents operation.
13236	</result>
13237	<result name="VBOX_E_INVALID_OBJECT_STATE">
13238	Session type prevents operation.
13239	</result>
13240
13241	</desc>
13242	<param name="global" type="boolean" dir="in"/>
13243	</method>
13244
13245	<method name="onUSBDeviceAttach">
13246	<desc>
13247	Triggered when a request to capture a USB device (as a result
13248	of matched USB filters or direct call to
13249	<link to="IConsole::attachUSBDevice"/>) has completed.
13250	A @c null @a error object means success, otherwise it
13251	describes a failure.
13252
13253	<result name="VBOX_E_INVALID_VM_STATE">
13254	Session state prevents operation.
13255	</result>
13256	<result name="VBOX_E_INVALID_OBJECT_STATE">
13257	Session type prevents operation.
13258	</result>
13259
13260	</desc>
13261	<param name="device" type="IUSBDevice" dir="in"/>
13262	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
13263	<param name="maskedInterfaces" type="unsigned long" dir="in"/>
13264	</method>
13265
13266	<method name="onUSBDeviceDetach">
13267	<desc>
13268	Triggered when a request to release the USB device (as a result
13269	of machine termination or direct call to
13270	<link to="IConsole::detachUSBDevice"/>) has completed.
13271	A @c null @a error object means success, otherwise it
13272	describes a failure.
13273
13274	<result name="VBOX_E_INVALID_VM_STATE">
13275	Session state prevents operation.
13276	</result>
13277	<result name="VBOX_E_INVALID_OBJECT_STATE">
13278	Session type prevents operation.
13279	</result>
13280
13281	</desc>
13282	<param name="id" type="uuid" mod="string" dir="in"/>
13283	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
13284	</method>
13285
13286	<method name="onShowWindow">
13287	<desc>
13288	Called by <link to="IMachine::canShowConsoleWindow"/> and by
13289	<link to="IMachine::showConsoleWindow"/> in order to notify
13290	console callbacks
13291	<link to="IConsoleCallback::onCanShowWindow"/>
13292	and <link to="IConsoleCallback::onShowWindow"/>.
13293
13294	<result name="VBOX_E_INVALID_OBJECT_STATE">
13295	Session type prevents operation.
13296	</result>
13297
13298	</desc>
13299	<param name="check" type="boolean" dir="in"/>
13300	<param name="canShow" type="boolean" dir="out"/>
13301	<param name="winId" type="unsigned long long" dir="out"/>
13302	</method>
13303
13304	<method name="accessGuestProperty">
13305	<desc>
13306	Called by <link to="IMachine::getGuestProperty"/> and by
13307	<link to="IMachine::setGuestProperty"/> in order to read and
13308	modify guest properties.
13309
13310	<result name="VBOX_E_INVALID_VM_STATE">
13311	Machine session is not open.
13312	</result>
13313	<result name="VBOX_E_INVALID_OBJECT_STATE">
13314	Session type is not direct.
13315	</result>
13316
13317	</desc>
13318	<param name="name" type="wstring" dir="in"/>
13319	<param name="value" type="wstring" dir="in"/>
13320	<param name="flags" type="wstring" dir="in"/>
13321	<param name="isSetter" type="boolean" dir="in"/>
13322	<param name="retValue" type="wstring" dir="out"/>
13323	<param name="retTimestamp" type="unsigned long long" dir="out"/>
13324	<param name="retFlags" type="wstring" dir="out"/>
13325	</method>
13326
13327	<method name="enumerateGuestProperties">
13328	<desc>
13329	Return a list of the guest properties matching a set of patterns along
13330	with their values, time stamps and flags.
13331
13332	<result name="VBOX_E_INVALID_VM_STATE">
13333	Machine session is not open.
13334	</result>
13335	<result name="VBOX_E_INVALID_OBJECT_STATE">
13336	Session type is not direct.
13337	</result>
13338
13339	</desc>
13340	<param name="patterns" type="wstring" dir="in">
13341	<desc>
13342	The patterns to match the properties against as a comma-separated
13343	string. If this is empty, all properties currently set will be
13344	returned.
13345	</desc>
13346	</param>
13347	<param name="key" type="wstring" dir="out" safearray="yes">
13348	<desc>
13349	The key names of the properties returned.
13350	</desc>
13351	</param>
13352	<param name="value" type="wstring" dir="out" safearray="yes">
13353	<desc>
13354	The values of the properties returned. The array entries match the
13355	corresponding entries in the @a key array.
13356	</desc>
13357	</param>
13358	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
13359	<desc>
13360	The time stamps of the properties returned. The array entries match
13361	the corresponding entries in the @a key array.
13362	</desc>
13363	</param>
13364	<param name="flags" type="wstring" dir="out" safearray="yes">
13365	<desc>
13366	The flags of the properties returned. The array entries match the
13367	corresponding entries in the @a key array.
13368	</desc>
13369	</param>
13370	</method>
13371
13372	<method name="onlineMergeMedium">
13373	<desc>
13374	Triggers online merging of a hard disk. Used internally when deleting
13375	a snapshot while a VM referring to the same hard disk chain is running.
13376
13377	<result name="VBOX_E_INVALID_VM_STATE">
13378	Machine session is not open.
13379	</result>
13380	<result name="VBOX_E_INVALID_OBJECT_STATE">
13381	Session type is not direct.
13382	</result>
13383
13384	</desc>
13385	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
13386	<desc>The medium attachment to identify the medium chain.</desc>
13387	</param>
13388	<param name="sourceIdx" type="unsigned long" dir="in">
13389	<desc>The index of the source image in the chain.
13390	Redundant, but drastically reduces IPC.</desc>
13391	</param>
13392	<param name="targetIdx" type="unsigned long" dir="in">
13393	<desc>The index of the target image in the chain.
13394	Redundant, but drastically reduces IPC.</desc>
13395	</param>
13396	<param name="source" type="IMedium" dir="in">
13397	<desc>Merge source medium.</desc>
13398	</param>
13399	<param name="target" type="IMedium" dir="in">
13400	<desc>Merge target medium.</desc>
13401	</param>
13402	<param name="mergeForward" type="boolean" dir="in">
13403	<desc>Merge direction.</desc>
13404	</param>
13405	<param name="parentForTarget" type="IMedium" dir="in">
13406	<desc>For forward merges: new parent for target medium.</desc>
13407	</param>
13408	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
13409	<desc>For backward merges: list of media which need their parent UUID
13410	updated.</desc>
13411	</param>
13412	<param name="progress" type="IProgress" dir="in">
13413	<desc>
13414	Progress object for this operation.
13415	</desc>
13416	</param>
13417	</method>
13418
13419	</interface>
13420
13421	<interface
13422	name="ISession" extends="$unknown"
13423	uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
13424	wsmap="managed"
13425	>
13426	<desc>
13427	The ISession interface represents a serialization primitive for virtual
13428	machines.
13429
13430	With VirtualBox, every time one wishes to manipulate a virtual machine
13431	(e.g. change its settings or start execution), a session object is
13432	required. Such an object must be passed to one of the session methods
13433	that open the given session, which then initiates the machine manipulation.
13434
13435	A session serves several purposes: it identifies to the inter-process VirtualBox
13436	code which process is currently working with the virtual machine, and it ensures
13437	that there are no incompatible requests from several processes for the
13438	same virtual machine. Session objects can therefore be thought of as mutex
13439	semaphores that lock virtual machines to prevent conflicting accesses from
13440	several processes.
13441
13442	How sessions objects are used depends on whether you use the Main API
13443	via COM or via the webservice:
13444
13445	<ul>
13446	<li>When using the COM API directly, an object of the Session class from the
13447	VirtualBox type library needs to be created. In regular COM C++ client code,
13448	this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
13449	This object will then act as a local session object in further calls to open
13450	a session.
13451	</li>
13452
13453	<li>In the webservice, the session manager (IWebsessionManager) instead creates
13454	one session object automatically when <link to="IWebsessionManager::logon" />
13455	is called. A managed object reference to that session object can be retrieved by
13456	calling <link to="IWebsessionManager::getSessionObject" />. This session object
13457	reference can then be used to open sessions.
13458	</li>
13459	</ul>
13460
13461	Sessions are mainly used in two variations:
13462
13463	<ul>
13464	<li>
13465	To start a virtual machine in a separate process, one would call
13466	<link to="IVirtualBox::openRemoteSession"/>, which requires a session
13467	object as its first parameter. This session then identifies the caller
13468	and lets him control the started machine (for example, pause machine
13469	execution or power it down) as well as be notified about machine
13470	execution state changes.
13471	</li>
13472
13473	<li>To alter machine settings, or to start machine execution within the
13474	current process, one needs to open a direct session for the machine first by
13475	calling <link to="IVirtualBox::openSession"/>. While a direct session
13476	is open within one process, no any other process may open another direct
13477	session for the same machine. This prevents the machine from being changed
13478	by other processes while it is running or while the machine is being configured.
13479	</li>
13480	</ul>
13481
13482	One also can attach to an existing direct session already opened by
13483	another process (for example, in order to send a control request to the
13484	virtual machine such as the pause or the reset request). This is done by
13485	calling <link to="IVirtualBox::openExistingSession"/>.
13486
13487	<note>
13488	Unless you are trying to write a new VirtualBox front-end that
13489	performs direct machine execution (like the VirtualBox or VBoxSDL
13490	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
13491	session opened by <link to="IVirtualBox::openSession"/> and use this
13492	session only to change virtual machine settings. If you simply want to
13493	start virtual machine execution using one of the existing front-ends
13494	(for example the VirtualBox GUI or headless server), simply use
13495	<link to="IVirtualBox::openRemoteSession"/>; these front-ends
13496	will power up the machine automatically for you.
13497	</note>
13498	</desc>
13499
13500	<attribute name="state" type="SessionState" readonly="yes">
13501	<desc>Current state of this session.</desc>
13502	</attribute>
13503
13504	<attribute name="type" type="SessionType" readonly="yes">
13505	<desc>
13506	Type of this session. The value of this attribute is valid only
13507	if the session is currently open (i.e. its #state is
13508	SessionType_SessionOpen), otherwise an error will be returned.
13509	</desc>
13510	</attribute>
13511
13512	<attribute name="machine" type="IMachine" readonly="yes">
13513	<desc>Machine object associated with this session.</desc>
13514	</attribute>
13515
13516	<attribute name="console" type="IConsole" readonly="yes">
13517	<desc>Console object associated with this session.</desc>
13518	</attribute>
13519
13520	<method name="close">
13521	<desc>
13522	Closes a session that was previously opened.
13523
13524	It is recommended that every time an "open session" method (such as
13525	<link to="IVirtualBox::openRemoteSession" /> or
13526	<link to="IVirtualBox::openSession" />) has been called to
13527	manipulate a virtual machine, the caller invoke
13528	ISession::close() when it's done doing so. Since sessions are
13529	serialization primitives much like ordinary mutexes, they are
13530	best used the same way: for each "open" call, there should be
13531	a matching "close" call, even when errors occur.
13532
13533	Otherwise, if a direct session for a machine opened with
13534	<link to="IVirtualBox::openSession"/> is not explicitly closed
13535	when the application terminates, the state of the machine will
13536	be set to <link to="MachineState_Aborted" /> on the server.
13537
13538	Generally, it is recommended to close all open sessions explicitly
13539	before terminating the application (regardless of the reason for
13540	the termination).
13541
13542	<note>
13543	Do not expect the session state (<link to="ISession::state" />
13544	to return to "Closed" immediately after you invoke
13545	ISession::close(), particularly if you have started a remote
13546	session to execute the VM in a new process. The session state will
13547	automatically return to "Closed" once the VM is no longer executing,
13548	which can of course take a very long time.
13549	</note>
13550
13551	<result name="E_UNEXPECTED">
13552	Session is not open.
13553	</result>
13554
13555	</desc>
13556	</method>
13557
13558	</interface>
13559
13560	<!--
13561	// IStorageController
13562	/////////////////////////////////////////////////////////////////////////
13563	-->
13564
13565	<enum
13566	name="StorageBus"
13567	uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
13568	>
13569	<desc>
13570	The bus type of the storage controller (IDE, SATA, SCSI or Floppy);
13571	see <link to="IStorageController::bus" />.
13572	</desc>
13573	<const name="Null" value="0">
13574	<desc>@c null value. Never used by the API.</desc>
13575	</const>
13576	<const name="IDE" value="1"/>
13577	<const name="SATA" value="2"/>
13578	<const name="SCSI" value="3"/>
13579	<const name="Floppy" value="4"/>
13580	<const name="SAS" value="5"/>
13581	</enum>
13582
13583	<enum
13584	name="StorageControllerType"
13585	uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
13586	>
13587	<desc>
13588	The exact variant of storage controller hardware presented
13589	to the guest; see <link to="IStorageController::controllerType" />.
13590	</desc>
13591
13592	<const name="Null" value="0">
13593	<desc>@c null value. Never used by the API.</desc>
13594	</const>
13595	<const name="LsiLogic" value="1">
13596	<desc>A SCSI controller of the LsiLogic variant.</desc>
13597	</const>
13598	<const name="BusLogic" value="2">
13599	<desc>A SCSI controller of the BusLogic variant.</desc>
13600	</const>
13601	<const name="IntelAhci" value="3">
13602	<desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
13603	</const>
13604	<const name="PIIX3" value="4">
13605	<desc>An IDE controller of the PIIX3 variant.</desc>
13606	</const>
13607	<const name="PIIX4" value="5">
13608	<desc>An IDE controller of the PIIX4 variant.</desc>
13609	</const>
13610	<const name="ICH6" value="6">
13611	<desc>An IDE controller of the ICH6 variant.</desc>
13612	</const>
13613	<const name="I82078" value="7">
13614	<desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
13615	</const>
13616	<const name="LsiLogicSas" value="8">
13617	<desc>A variant of the LsiLogic controller using SAS.</desc>
13618	</const>
13619	</enum>
13620
13621	<interface
13622	name="IStorageController" extends="$unknown"
13623	uuid="7635f4ec-8a28-44b5-9223-315a87b710fb"
13624	wsmap="managed"
13625	>
13626	<desc>
13627	Represents a storage controller that is attached to a virtual machine
13628	(<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
13629	attached to storage controllers in a real computer, virtual drives
13630	(represented by <link to="IMediumAttachment" />) are attached to virtual
13631	storage controllers, represented by this interface.
13632
13633	As opposed to physical hardware, VirtualBox has a very generic concept
13634	of a storage controller, and for purposes of the Main API, all virtual
13635	storage is attached to virtual machines via instances of this interface.
13636	There are four types of such virtual storage controllers: IDE, SCSI, SATA
13637	and Floppy (see <link to="#bus" />). Depending on which of these four is
13638	used, certain sub-types may be available and can be selected in
13639	<link to="#controllerType" />.
13640
13641	Depending on these settings, the guest operating system might see
13642	significantly different virtual hardware.
13643	</desc>
13644
13645	<attribute name="name" type="wstring" readonly="yes">
13646	<desc>
13647	Name of the storage controller, as originally specified with
13648	<link to="IMachine::addStorageController" />. This then uniquely
13649	identifies this controller with other method calls such as
13650	<link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
13651	</desc>
13652	</attribute>
13653
13654	<attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
13655	<desc>
13656	Maximum number of devices which can be attached to one port.
13657	</desc>
13658	</attribute>
13659
13660	<attribute name="minPortCount" type="unsigned long" readonly="yes">
13661	<desc>
13662	Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
13663	</desc>
13664	</attribute>
13665
13666	<attribute name="maxPortCount" type="unsigned long" readonly="yes">
13667	<desc>
13668	Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
13669	</desc>
13670	</attribute>
13671
13672	<attribute name="instance" type="unsigned long">
13673	<desc>
13674	The instance number of the device in the running VM.
13675	</desc>
13676	</attribute>
13677
13678	<attribute name="portCount" type="unsigned long">
13679	<desc>
13680	The number of currently usable ports on the controller.
13681	The minimum and maximum number of ports for one controller are
13682	stored in <link to="IStorageController::minPortCount"/>
13683	and <link to="IStorageController::maxPortCount"/>.
13684	</desc>
13685	</attribute>
13686
13687	<attribute name="bus" type="StorageBus" readonly="yes">
13688	<desc>
13689	The bus type of the storage controller (IDE, SATA, SCSI or Floppy).
13690	</desc>
13691	</attribute>
13692
13693	<attribute name="controllerType" type="StorageControllerType">
13694	<desc>
13695	The exact variant of storage controller hardware presented
13696	to the guest.
13697	Depending on this value, VirtualBox will provide a different
13698	virtual storage controller hardware to the guest.
13699	For SATA and floppy controllers, only one variant is available,
13700	but for IDE and SCSI, there are several.
13701
13702	For SCSI controllers, the default type is LsiLogic.
13703	</desc>
13704	</attribute>
13705
13706	<attribute name="ioBackend" type="IoBackendType">
13707	<desc>
13708	The I/O backend to use for the given storage controller.
13709	</desc>
13710	</attribute>
13711
13712	<method name="getIDEEmulationPort">
13713	<desc>
13714	Gets the corresponding port number which is emulated as an IDE device.
13715	Works only with SATA controllers.
13716
13717	<result name="E_INVALIDARG">
13718	The @a devicePosition is not in the range 0 to 3.
13719	</result>
13720	<result name="E_NOTIMPL">
13721	The storage controller type is not SATAIntelAhci.
13722	</result>
13723
13724	</desc>
13725	<param name="devicePosition" type="long" dir="in"/>
13726	<param name="portNumber" type="long" dir="return"/>
13727	</method>
13728
13729	<method name="setIDEEmulationPort">
13730	<desc>
13731	Sets the port number which is emulated as an IDE device.
13732	Works only with SATA controllers.
13733
13734	<result name="E_INVALIDARG">
13735	The @a devicePosition is not in the range 0 to 3 or the
13736	@a portNumber is not in the range 0 to 29.
13737	</result>
13738	<result name="E_NOTIMPL">
13739	The storage controller type is not SATAIntelAhci.
13740	</result>
13741
13742	</desc>
13743	<param name="devicePosition" type="long" dir="in"/>
13744	<param name="portNumber" type="long" dir="in"/>
13745	</method>
13746
13747	</interface>
13748
13749	<if target="wsdl">
13750
13751	<!--
13752	// IManagedObjectRef
13753	/////////////////////////////////////////////////////////////////////////
13754	-->
13755
13756	<interface
13757	name="IManagedObjectRef" extends="$unknown"
13758	uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
13759	internal="yes"
13760	wsmap="managed"
13761	wscpp="hardcoded"
13762	>
13763	<desc>
13764	Managed object reference.
13765
13766	Only within the webservice, a managed object reference (which is really
13767	an opaque number) allows a webservice client to address an object
13768	that lives in the address space of the webservice server.
13769
13770	Behind each managed object reference, there is a COM object that lives
13771	in the webservice server's address space. The COM object is not freed
13772	until the managed object reference is released, either by an explicit
13773	call to <link to="IManagedObjectRef::release" /> or by logging off from
13774	the webservice (<link to="IWebsessionManager::logoff" />), which releases
13775	all objects created during the webservice session.
13776
13777	Whenever a method call of the VirtualBox API returns a COM object, the
13778	webservice representation of that method will instead return a
13779	managed object reference, which can then be used to invoke methods
13780	on that object.
13781	</desc>
13782
13783	<method name="getInterfaceName">
13784	<desc>
13785	Returns the name of the interface that this managed object represents,
13786	for example, "IMachine", as a string.
13787	</desc>
13788	<param name="return" type="wstring" dir="return"/>
13789	</method>
13790
13791	<method name="release">
13792	<desc>
13793	Releases this managed object reference and frees the resources that
13794	were allocated for it in the webservice server process. After calling
13795	this method, the identifier of the reference can no longer be used.
13796	</desc>
13797	</method>
13798
13799	</interface>
13800
13801	<!--
13802	// IWebsessionManager
13803	/////////////////////////////////////////////////////////////////////////
13804	-->
13805
13806	<interface
13807	name="IWebsessionManager" extends="$unknown"
13808	uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
13809	internal="yes"
13810	wsmap="global"
13811	wscpp="hardcoded"
13812	>
13813	<desc>
13814	Websession manager. This provides essential services
13815	to webservice clients.
13816	</desc>
13817	<method name="logon">
13818	<desc>
13819	Logs a new client onto the webservice and returns a managed object reference to
13820	the IVirtualBox instance, which the client can then use as a basis to further
13821	queries, since all calls to the VirtualBox API are based on the IVirtualBox
13822	interface, in one way or the other.
13823	</desc>
13824	<param name="username" type="wstring" dir="in"/>
13825	<param name="password" type="wstring" dir="in"/>
13826	<param name="return" type="IVirtualBox" dir="return"/>
13827	</method>
13828
13829	<method name="getSessionObject">
13830	<desc>
13831	Returns a managed object reference to the internal ISession object that was created
13832	for this web service session when the client logged on.
13833
13834	<see>ISession</see>
13835	</desc>
13836	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
13837	<param name="return" type="ISession" dir="return"/>
13838	</method>
13839
13840	<method name="logoff">
13841	<desc>
13842	Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
13843	and destroys all resources associated with the session (most importantly, all
13844	managed objects created in the server while the session was active).
13845	</desc>
13846	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
13847	</method>
13848
13849	</interface>
13850
13851	</if>
13852
13853	<!--
13854	// IPerformanceCollector & friends
13855	/////////////////////////////////////////////////////////////////////////
13856	-->
13857
13858	<interface
13859	name="IPerformanceMetric" extends="$unknown"
13860	uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
13861	>
13862	<desc>
13863	The IPerformanceMetric interface represents parameters of the given
13864	performance metric.
13865	</desc>
13866
13867	<attribute name="metricName" type="wstring" readonly="yes">
13868	<desc>
13869	Name of the metric.
13870	</desc>
13871	</attribute>
13872
13873	<attribute name="object" type="$unknown" readonly="yes">
13874	<desc>
13875	Object this metric belongs to.
13876	</desc>
13877	</attribute>
13878
13879	<attribute name="description" type="wstring" readonly="yes">
13880	<desc>
13881	Textual description of the metric.
13882	</desc>
13883	</attribute>
13884
13885	<attribute name="period" type="unsigned long" readonly="yes">
13886	<desc>
13887	Time interval between samples, measured in seconds.
13888	</desc>
13889	</attribute>
13890
13891	<attribute name="count" type="unsigned long" readonly="yes">
13892	<desc>
13893	Number of recent samples retained by the performance collector for this
13894	metric.
13895
13896	When the collected sample count exceeds this number, older samples
13897	are discarded.
13898	</desc>
13899	</attribute>
13900
13901	<attribute name="unit" type="wstring" readonly="yes">
13902	<desc>
13903	Unit of measurement.
13904	</desc>
13905	</attribute>
13906
13907	<attribute name="minimumValue" type="long" readonly="yes">
13908	<desc>
13909	Minimum possible value of this metric.
13910	</desc>
13911	</attribute>
13912
13913	<attribute name="maximumValue" type="long" readonly="yes">
13914	<desc>
13915	Maximum possible value of this metric.
13916	</desc>
13917	</attribute>
13918	</interface>
13919
13920	<interface
13921	name="IPerformanceCollector" extends="$unknown"
13922	uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
13923	wsmap="managed"
13924	>
13925	<desc>
13926	The IPerformanceCollector interface represents a service that collects
13927	and stores performance metrics data.
13928
13929	Performance metrics are associated with objects of interfaces like IHost
13930	and IMachine. Each object has a distinct set of performance metrics. The
13931	set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
13932
13933	Metric data is collected at the specified intervals and is retained
13934	internally. The interval and the number of retained samples can be set
13935	with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
13936	and collection settings are not persistent, they are discarded as soon as
13937	VBoxSVC process terminates. Moreover, metric settings and data associated
13938	with a particular VM only exist while VM is running. They disappear as
13939	soon as VM shuts down. It is not possible to set up metrics for machines
13940	that are powered off. One needs to start VM first, then set up metric
13941	collection parameters.
13942
13943	Metrics are organized hierarchically, with each level separated by a
13944	slash (/) character. Generally, the scheme for metric names is like this:
13945
13946	<tt>Category/Metric[/SubMetric][:aggregation]</tt>
13947
13948	"Category/Metric" together form the base metric name. A base metric is
13949	the smallest unit for which a sampling interval and the number of
13950	retained samples can be set. Only base metrics can be enabled and
13951	disabled. All sub-metrics are collected when their base metric is
13952	collected. Collected values for any set of sub-metrics can be queried
13953	with <link to="IPerformanceCollector::queryMetricsData" />.
13954
13955	For example "CPU/Load/User:avg" metric name stands for the "CPU"
13956	category, "Load" metric, "User" submetric, "average" aggregate. An
13957	aggregate function is computed over all retained data. Valid aggregate
13958	functions are:
13959
13960	<ul>
13961	<li>avg -- average</li>
13962	<li>min -- minimum</li>
13963	<li>max -- maximum</li>
13964	</ul>
13965
13966	When setting up metric parameters, querying metric data, enabling or
13967	disabling metrics wildcards can be used in metric names to specify a
13968	subset of metrics. For example, to select all CPU-related metrics
13969	use <tt>CPU/</tt>, all averages can be queried using <tt>:avg</tt> and
13970	so on. To query metric values without aggregates <tt>*:</tt> can be used.
13971
13972	The valid names for base metrics are:
13973
13974	<ul>
13975	<li>CPU/Load</li>
13976	<li>CPU/MHz</li>
13977	<li>RAM/Usage</li>
13978	</ul>
13979
13980	The general sequence for collecting and retrieving the metrics is:
13981	<ul>
13982	<li>
13983	Obtain an instance of IPerformanceCollector with
13984	<link to="IVirtualBox::performanceCollector" />
13985	</li>
13986	<li>
13987	Allocate and populate an array with references to objects the metrics
13988	will be collected for. Use references to IHost and IMachine objects.
13989	</li>
13990	<li>
13991	Allocate and populate an array with base metric names the data will
13992	be collected for.
13993	</li>
13994	<li>
13995	Call <link to="IPerformanceCollector::setupMetrics" />. From now on
13996	the metric data will be collected and stored.
13997	</li>
13998	<li>
13999	Wait for the data to get collected.
14000	</li>
14001	<li>
14002	Allocate and populate an array with references to objects the metric
14003	values will be queried for. You can re-use the object array used for
14004	setting base metrics.
14005	</li>
14006	<li>
14007	Allocate and populate an array with metric names the data will be
14008	collected for. Note that metric names differ from base metric names.
14009	</li>
14010	<li>
14011	Call <link to="IPerformanceCollector::queryMetricsData" />. The data
14012	that have been collected so far are returned. Note that the values
14013	are still retained internally and data collection continues.
14014	</li>
14015	</ul>
14016
14017	For an example of usage refer to the following files in VirtualBox SDK:
14018	<ul>
14019	<li>
14020	Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
14021	</li>
14022	<li>
14023	Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
14024	</li>
14025	</ul>
14026	</desc>
14027
14028	<attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
14029	<desc>
14030	Array of unique names of metrics.
14031
14032	This array represents all metrics supported by the performance
14033	collector. Individual objects do not necessarily support all of them.
14034	<link to="IPerformanceCollector::getMetrics"/> can be used to get the
14035	list of supported metrics for a particular object.
14036	</desc>
14037	</attribute>
14038
14039	<method name="getMetrics">
14040	<desc>
14041	Returns parameters of specified metrics for a set of objects.
14042	<note>
14043	@c Null metrics array means all metrics. @c Null object array means
14044	all existing objects.
14045	</note>
14046	</desc>
14047	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14048	<desc>
14049	Metric name filter. Currently, only a comma-separated list of metrics
14050	is supported.
14051	</desc>
14052	</param>
14053	<param name="objects" type="$unknown" dir="in" safearray="yes">
14054	<desc>
14055	Set of objects to return metric parameters for.
14056	</desc>
14057	</param>
14058	<param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
14059	<desc>
14060	Array of returned metric parameters.
14061	</desc>
14062	</param>
14063	</method>
14064
14065	<method name="setupMetrics">
14066	<desc>
14067	Sets parameters of specified base metrics for a set of objects. Returns
14068	an array of <link to="IPerformanceMetric" /> describing the metrics
14069	have been affected.
14070	<note>
14071	@c Null or empty metric name array means all metrics. @c Null or
14072	empty object array means all existing objects. If metric name array
14073	contains a single element and object array contains many, the single
14074	metric name array element is applied to each object array element to
14075	form metric/object pairs.
14076	</note>
14077	</desc>
14078	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14079	<desc>
14080	Metric name filter. Comma-separated list of metrics with wildcard
14081	support.
14082	</desc>
14083	</param>
14084	<param name="objects" type="$unknown" dir="in" safearray="yes">
14085	<desc>
14086	Set of objects to setup metric parameters for.
14087	</desc>
14088	</param>
14089	<param name="period" type="unsigned long" dir="in">
14090	<desc>
14091	Time interval in seconds between two consecutive samples of
14092	performance data.
14093	</desc>
14094	</param>
14095	<param name="count" type="unsigned long" dir="in">
14096	<desc>
14097	Number of samples to retain in performance data history. Older
14098	samples get discarded.
14099	</desc>
14100	</param>
14101	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
14102	<desc>
14103	Array of metrics that have been modified by the call to this method.
14104	</desc>
14105	</param>
14106	</method>
14107
14108	<method name="enableMetrics">
14109	<desc>
14110	Turns on collecting specified base metrics. Returns an array of
14111	<link to="IPerformanceMetric" /> describing the metrics have been
14112	affected.
14113	<note>
14114	@c Null or empty metric name array means all metrics. @c Null or
14115	empty object array means all existing objects. If metric name array
14116	contains a single element and object array contains many, the single
14117	metric name array element is applied to each object array element to
14118	form metric/object pairs.
14119	</note>
14120	</desc>
14121	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14122	<desc>
14123	Metric name filter. Comma-separated list of metrics with wildcard
14124	support.
14125	</desc>
14126	</param>
14127	<param name="objects" type="$unknown" dir="in" safearray="yes">
14128	<desc>
14129	Set of objects to enable metrics for.
14130	</desc>
14131	</param>
14132	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
14133	<desc>
14134	Array of metrics that have been modified by the call to this method.
14135	</desc>
14136	</param>
14137	</method>
14138
14139	<method name="disableMetrics">
14140	<desc>
14141	Turns off collecting specified base metrics. Returns an array of
14142	<link to="IPerformanceMetric" /> describing the metrics have been
14143	affected.
14144	<note>
14145	@c Null or empty metric name array means all metrics. @c Null or
14146	empty object array means all existing objects. If metric name array
14147	contains a single element and object array contains many, the single
14148	metric name array element is applied to each object array element to
14149	form metric/object pairs.
14150	</note>
14151	</desc>
14152	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14153	<desc>
14154	Metric name filter. Comma-separated list of metrics with wildcard
14155	support.
14156	</desc>
14157	</param>
14158	<param name="objects" type="$unknown" dir="in" safearray="yes">
14159	<desc>
14160	Set of objects to disable metrics for.
14161	</desc>
14162	</param>
14163	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
14164	<desc>
14165	Array of metrics that have been modified by the call to this method.
14166	</desc>
14167	</param>
14168	</method>
14169
14170	<method name="queryMetricsData">
14171	<desc>
14172	Queries collected metrics data for a set of objects.
14173
14174	The data itself and related metric information are returned in seven
14175	parallel and one flattened array of arrays. Elements of
14176	<tt>returnMetricNames, returnObjects, returnUnits, returnScales,
14177	returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
14178	the same index describe one set of values corresponding to a single
14179	metric.
14180
14181	The <tt>returnData</tt> parameter is a flattened array of arrays. Each
14182	start and length of a sub-array is indicated by
14183	<tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
14184	value for metric <tt>metricNames[i]</tt> is at
14185	<tt>returnData[returnIndices[i]]</tt>.
14186
14187	<note>
14188	@c Null or empty metric name array means all metrics. @c Null or
14189	empty object array means all existing objects. If metric name array
14190	contains a single element and object array contains many, the single
14191	metric name array element is applied to each object array element to
14192	form metric/object pairs.
14193	</note>
14194	<note>
14195	Data collection continues behind the scenes after call to @c
14196	queryMetricsData. The return data can be seen as the snapshot of the
14197	current state at the time of @c queryMetricsData call. The internally
14198	kept metric values are not cleared by the call. This makes possible
14199	querying different subsets of metrics or aggregates with subsequent
14200	calls. If periodic querying is needed it is highly suggested to query
14201	the values with @c interval*count period to avoid confusion. This way
14202	a completely new set of data values will be provided by each query.
14203	</note>
14204	</desc>
14205	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14206	<desc>
14207	Metric name filter. Comma-separated list of metrics with wildcard
14208	support.
14209	</desc>
14210	</param>
14211	<param name="objects" type="$unknown" dir="in" safearray="yes">
14212	<desc>
14213	Set of objects to query metrics for.
14214	</desc>
14215	</param>
14216	<param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
14217	<desc>
14218	Names of metrics returned in @c returnData.
14219	</desc>
14220	</param>
14221	<param name="returnObjects" type="$unknown" dir="out" safearray="yes">
14222	<desc>
14223	Objects associated with metrics returned in @c returnData.
14224	</desc>
14225	</param>
14226	<param name="returnUnits" type="wstring" dir="out" safearray="yes">
14227	<desc>
14228	Units of measurement for each returned metric.
14229	</desc>
14230	</param>
14231	<param name="returnScales" type="unsigned long" dir="out" safearray="yes">
14232	<desc>
14233	Divisor that should be applied to return values in order to get
14234	floating point values. For example:
14235	<tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
14236	will retrieve the floating point value of i-th sample of the first
14237	metric.
14238	</desc>
14239	</param>
14240	<param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
14241	<desc>
14242	Sequence numbers of the first elements of value sequences of
14243	particular metrics returned in @c returnData. For aggregate metrics
14244	it is the sequence number of the sample the aggregate started
14245	calculation from.
14246	</desc>
14247	</param>
14248	<param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
14249	<desc>
14250	Indices of the first elements of value sequences of particular
14251	metrics returned in @c returnData.
14252	</desc>
14253	</param>
14254	<param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
14255	<desc>
14256	Lengths of value sequences of particular metrics.
14257	</desc>
14258	</param>
14259	<param name="returnData" type="long" dir="return" safearray="yes">
14260	<desc>
14261	Flattened array of all metric data containing sequences of values for
14262	each metric.
14263	</desc>
14264	</param>
14265	</method>
14266
14267	</interface>
14268	<enum
14269	name="NATAliasMode"
14270	uuid="67772168-50d9-11df-9669-7fb714ee4fa1">
14271	<desc></desc>
14272	<const name="AliasLog" value="0x1">
14273	<desc></desc>
14274	</const>
14275	<const name="AliasProxyOnly" value="0x02">
14276	<desc></desc>
14277	</const>
14278	<const name="AliasUseSamePorts" value="0x04">
14279	<desc></desc>
14280	</const>
14281	</enum>
14282	<enum
14283	name="NATProtocol"
14284	uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
14285	>
14286	<desc>Protocol definitions used with NAT port-forwarding rules.</desc>
14287	<const name="UDP" value="0">
14288	<desc>Port-forwarding uses UDP protocol.</desc>
14289	</const>
14290	<const name="TCP" value="1">
14291	<desc>Port-forwarding uses TCP protocol.</desc>
14292	</const>
14293	</enum>
14294
14295	<interface
14296	name="INATEngine" extends="$unknown"
14297	uuid="4b286616-eb03-11de-b0fb-1701eca42246"
14298	wsmap="managed"
14299	>
14300	<desc>Interface for managing a NAT engine which is used with a virtual machine. This
14301	allows for changing NAT behavior such as port-forwarding rules. This interface is
14302	used in the <link to="INetworkAdapter::natDriver" /> attribute.</desc>
14303	<attribute name="network" type="wstring">
14304	<desc>The network attribute of the NAT engine (the same value is used with built-in
14305	DHCP server to fill corresponding fields of DHCP leases).</desc>
14306	</attribute>
14307	<attribute name="hostIP" type="wstring">
14308	<desc>IP of host interface to bind all opened sockets to.
14309	<note>Changing this does not change binding of port forwarding.</note>
14310	</desc>
14311	</attribute>
14312	<attribute name="tftpPrefix" type="wstring">
14313	<desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
14314	the corresponding fields of DHCP leases.</desc>
14315	</attribute>
14316	<attribute name="tftpBootFile" type="wstring">
14317	<desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
14318	the corresponding fields of DHCP leases.</desc>
14319	</attribute>
14320	<attribute name="tftpNextServer" type="wstring">
14321	<desc>TFTP server attribute which is used with the built-in DHCP server to fill
14322	the corresponding fields of DHCP leases.
14323	<note>The preferred form is IPv4 addresses.</note>
14324	</desc>
14325	</attribute>
14326	<attribute name="aliasMode" type="unsigned long">
14327	<desc></desc>
14328	</attribute>
14329	<attribute name="dnsPassDomain" type="boolean">
14330	<desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
14331	</attribute>
14332	<attribute name="dnsProxy" type="boolean">
14333	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
14334	of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
14335	</attribute>
14336	<attribute name="dnsUseHostResolver" type="boolean">
14337	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
14338	of the DNS proxy and process traffic using the host resolver mechanism.</desc>
14339	</attribute>
14340	<attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
14341	<desc>Array of NAT port-forwarding rules in string representation, in the following
14342	format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
14343	</attribute>
14344	<method name="setNetworkSettings">
14345	<desc>Sets network configuration of the NAT engine.</desc>
14346	<param name="mtu" type="unsigned long" dir="in">
14347	<desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
14348	</param>
14349	<param name="sockSnd" type="unsigned long" dir="in">
14350	<desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
14351	</param>
14352	<param name="sockRcv" type="unsigned long" dir="in">
14353	<desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
14354	</param>
14355	<param name="TcpWndSnd" type="unsigned long" dir="in">
14356	<desc>Initial size of the NAT engine's sending TCP window in bytes when
14357	establishing a new TCP connection.</desc>
14358	</param>
14359	<param name="TcpWndRcv" type="unsigned long" dir="in">
14360	<desc>Initial size of the NAT engine's receiving TCP window in bytes when
14361	establishing a new TCP connection.</desc>
14362	</param>
14363	</method>
14364	<method name="getNetworkSettings">
14365	<desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
14366	for parameter descriptions.</desc>
14367	<param name="mtu" type="unsigned long" dir="out" />
14368	<param name="sockSnd" type="unsigned long" dir="out" />
14369	<param name="sockRcv" type="unsigned long" dir="out" />
14370	<param name="TcpWndSnd" type="unsigned long" dir="out" />
14371	<param name="TcpWndRcv" type="unsigned long" dir="out" />
14372	</method>
14373	<method name="addRedirect">
14374	<desc>Adds a new NAT port-forwarding rule.</desc>
14375	<param name="name" type="wstring" dir="in">
14376	<desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
14377	auto-generates one using the other parameters.</desc>
14378	</param>
14379	<param name="proto" type="NATProtocol" dir="in">
14380	<desc>Protocol handled with the rule.</desc>
14381	</param>
14382	<param name="hostIp" type="wstring" dir="in">
14383	<desc>IP of the host interface to which the rule should apply. An empty ip address is
14384	acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
14385	</param>
14386	<param name="hostPort" type="unsigned short" dir="in">
14387	<desc>The port number to listen on.</desc>
14388	</param>
14389	<param name="guestIp" type="wstring" dir="in">
14390	<desc>The IP address of the guest which the NAT engine will forward matching packets
14391	to. An empty IP address is acceptable, in which case the NAT engine will forward
14392	packets to the first DHCP lease (x.x.x.15).</desc>
14393	</param>
14394	<param name="guestPort" type="unsigned short" dir="in">
14395	<desc>The port number to forward.</desc>
14396	</param>
14397	</method>
14398	<method name="removeRedirect">
14399	<desc>Removes a port-forwarding rule that was previously registered.</desc>
14400	<param name="name" type="wstring" dir="in">
14401	<desc>The name of the rule to delete.</desc>
14402	</param>
14403	</method>
14404	</interface>
14405
14406	<module name="VBoxSVC" context="LocalServer">
14407	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
14408	namespace="virtualbox.org">
14409	<interface name="IVirtualBox" default="yes"/>
14410	</class>
14411	</module>
14412
14413	<module name="VBoxC" context="InprocServer" threadingModel="Free">
14414	<class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
14415	namespace="virtualbox.org">
14416	<interface name="ISession" default="yes"/>
14417	</class>
14418	<class name="CallbackWrapper" uuid="49EE8561-5563-4715-B18C-A4B1A490DAFE"
14419	namespace="virtualbox.org">
14420	<interface name="ILocalOwner" default="yes"/>
14421	<interface name="IVirtualBoxCallback"/>
14422	<interface name="IConsoleCallback"/>
14423	</class>
14424	</module>
14425
14426	</library>
14427
14428	</idl>
14429
14430	<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->

Note: See TracBrowser for help on using the repository browser.

Download in other formats:

Original Format