VirtualBox.xidl@ 23702

Last change on this file since 23702 was 23702, checked in by vboxsync, 15 years ago
Query VT capabilities from the support driver.
Property svn:eol-style set to `native`
File size: 486.7 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-2009 Sun Microsystems, Inc.
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	Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
59	Clara, CA 95054 USA or visit http://www.sun.com if you need
60	additional information or have any questions.
61	-->
62
63	<idl>
64
65	<desc>
66	Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
67	describes the so-called <i>VirtualBox Main API</i> which comprises all public
68	COM interfaces and components provided by the VirtualBox server and by the
69	VirtualBox client library.
70
71	VirtualBox employs a client-server design, meaning that whenever any part of
72	VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
73	interface or any virtual machine --, a dedicated server process named
74	VBoxSVC runs in the background. This allows multiple processes working with
75	VirtualBox to cooperate without conflicts. These processes communicate to each
76	other using inter-process communication facilities provided by the COM
77	implementation of the host computer.
78
79	On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
80	implementation. On all other platforms, Mozilla XPCOM, an open-source COM
81	implementation, is used.
82
83	All the parts that a typical VirtualBox user interacts with (the Qt GUI,
84	the VBoxManage command-line interface and the VBoxVRDP server) are technically
85	front-ends to the Main API and only use the interfaces that are documented
86	in this Main API documentation. This ensures that, with any given release
87	version of VirtualBox, all capabilities of the product that could be useful
88	to an external client program are always exposed by way of this API.
89
90	The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
91	contains two public component classes:
92	<tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
93	implement IVirtualBox and ISession interfaces respectively. These two classes
94	are of supreme importance and will be needed in order for any front-end
95	program to do anything useful. It is recommended to read the documentation of
96	the mentioned interfaces first.
97
98	The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
99	there can be only one object of this class on the local machine at any given
100	time. This object is a parent of many other objects in the VirtualBox COM
101	library and lives in the VBoxSVC process. In fact, when you create an instance
102	of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
103	process is already running, starts it if not, and returns you a reference to
104	the <tt>VirtualBox</tt> object created in this process. When the last reference
105	to this object is released, the VBoxSVC process ends (with a 5 second delay to
106	protect from too frequent restarts).
107
108	The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
109	as many <tt>Session</tt> objects as you need but all of them will live in a
110	process which issues the object instantiation call. <tt>Session</tt> objects
111	represent virtual machine sessions which are used to configure virtual
112	machines and control their execution.
113	</desc>
114
115	<if target="midl">
116	<cpp line="enum {"/>
117	<cpp line=" kTypeLibraryMajorVersion = 1,"/>
118	<cpp line=" kTypeLibraryMinorVersion = 0"/>
119	<cpp line="};"/>
120	</if>
121
122	<if target="xpidl">
123	<!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
124	<cpp>
125	/* currently, nsISupportsImpl.h lacks the below-like macros */
126
127	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
128	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
129	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI
130
131	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
132	# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
133	NS_IMPL_THREADSAFE_ADDREF(_class) \
134	NS_IMPL_THREADSAFE_RELEASE(_class) \
135	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
136	NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
137	#endif
138
139	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
140	# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
141	NS_IMPL_THREADSAFE_ADDREF(_class) \
142	NS_IMPL_THREADSAFE_RELEASE(_class) \
143	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
144	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
145	#endif
146
147	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI
148	# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \
149	NS_IMPL_THREADSAFE_ADDREF(_class) \
150	NS_IMPL_THREADSAFE_RELEASE(_class) \
151	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \
152	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
153	#endif
154
155	#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
156	# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
157	NS_INTERFACE_MAP_BEGIN(_class) \
158	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
159	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
160	NS_IMPL_QUERY_CLASSINFO(_class) \
161	NS_INTERFACE_MAP_END
162	#endif
163
164	#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
165	# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
166	_i2, _ic2) \
167	NS_INTERFACE_MAP_BEGIN(_class) \
168	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
169	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
170	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
171	NS_IMPL_QUERY_CLASSINFO(_class) \
172	NS_INTERFACE_MAP_END
173	#endif
174
175	#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
176	# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
177	_i2, _ic2, _i3, _ic3) \
178	NS_INTERFACE_MAP_BEGIN(_class) \
179	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
180	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
181	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \
182	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
183	NS_IMPL_QUERY_CLASSINFO(_class) \
184	NS_INTERFACE_MAP_END
185	#endif
186
187	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
188	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
189	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
190
191	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
192	# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
193	NS_IMPL_THREADSAFE_ADDREF(_class) \
194	NS_IMPL_THREADSAFE_RELEASE(_class) \
195	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
196	NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
197	#endif
198
199	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
200	# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
201	_i2, _ic2) \
202	NS_IMPL_THREADSAFE_ADDREF(_class) \
203	NS_IMPL_THREADSAFE_RELEASE(_class) \
204	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
205	_i2, _ic2) \
206	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
207	#endif
208
209	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI
210	# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \
211	_i2, _ic2, _i3, _ic3) \
212	NS_IMPL_THREADSAFE_ADDREF(_class) \
213	NS_IMPL_THREADSAFE_RELEASE(_class) \
214	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
215	_i2, _ic2, _i3, _ic3) \
216	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
217	#endif
218
219	</cpp>
220	</if>
221
222	<library
223	name="VirtualBox"
224	uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
225	version="1.3"
226	desc="VirtualBox Type Library"
227	appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
228	supportsErrorInfo="yes"
229	>
230
231
232	<!--
233	// COM result codes for VirtualBox
234	/////////////////////////////////////////////////////////////////////////
235	-->
236
237	<descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
238	<desc>
239	This section describes all VirtualBox-specific COM result codes that may
240	be returned by methods of VirtualBox COM interfaces in addition to
241	standard COM result codes.
242
243	Note that along with the result code, every VirtualBox method returns
244	extended error information through the IVirtualBoxErrorInfo interface on
245	failure. This interface is a preferred way to present the error to the end
246	user because it contains a human readable description of the error. Raw
247	result codes, both standard and described in this section, are intended to
248	be used by programs to analyze the reason of a failure and select an
249	appropriate course of action without involving the end user (for example,
250	retry the operation later or make a different call).
251
252	The standard COM result codes that may originate from our methods include:
253
254	<table>
255	<tr><td>E_INVALIDARG</td>
256	<td>
257	Returned when the value of the method's argument is not within the range
258	of valid values. This should not be confused with situations when the
259	value is within the range but simply doesn't suit the current object
260	state and there is a possibility that it will be accepted later (in such
261	cases VirtualBox-specific codes are returned, for example,
262	<link to="VBOX_E_OBJECT_NOT_FOUND"/>).
263	</td>
264	</tr>
265	<tr><td>E_POINTER</td>
266	<td>
267	Returned if a memory pointer for the output argument is invalid (for
268	example, @c null). Note that when pointers representing input
269	arguments (such as strings) are invalid, E_INVALIDARG is returned.
270	</td>
271	</tr>
272	<tr><td>E_ACCESSDENIED</td>
273	<td>
274	Returned when the called object is not ready. Since the lifetime of a
275	public COM object cannot be fully controlled by the implementation,
276	VirtualBox maintains the readiness state for all objects it creates and
277	returns this code in response to any method call on the object that was
278	deactivated by VirtualBox and is not functioning any more.
279	</td>
280	</tr>
281	<tr><td>E_OUTOFMEMORY</td>
282	<td>
283	Returned when a memory allocation operation fails.
284	</td>
285	</tr>
286	</table>
287	</desc>
288	</descGroup>
289
290	<!--
291	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
292	everything in <result>/<desc> after (and including) the first dot, so express
293	the matter of the error code in the first sentence and keep it short.
294	-->
295
296	<result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
297	<desc>
298	Object corresponding to the supplied arguments does not exist.
299	</desc>
300	</result>
301
302	<result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
303	<desc>
304	Current virtual machine state prevents the operation.
305	</desc>
306	</result>
307
308	<result name="VBOX_E_VM_ERROR" value="0x80BB0003">
309	<desc>
310	Virtual machine error occurred attempting the operation.
311	</desc>
312	</result>
313
314	<result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
315	<desc>
316	File not accessible or erroneous file contents.
317	</desc>
318	</result>
319
320	<result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
321	<desc>
322	Runtime subsystem error.
323	</desc>
324	</result>
325
326	<result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
327	<desc>
328	Pluggable Device Manager error.
329	</desc>
330	</result>
331
332	<result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
333	<desc>
334	Current object state prohibits operation.
335	</desc>
336	</result>
337
338	<result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
339	<desc>
340	Host operating system related error.
341	</desc>
342	</result>
343
344	<result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
345	<desc>
346	Requested operation is not supported.
347	</desc>
348	</result>
349
350	<result name="VBOX_E_XML_ERROR" value="0x80BB000A">
351	<desc>
352	Invalid XML found.
353	</desc>
354	</result>
355
356	<result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
357	<desc>
358	Current session state prohibits operation.
359	</desc>
360	</result>
361
362	<result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
363	<desc>
364	Object being in use prohibits operation.
365	</desc>
366	</result>
367
368	<!--
369	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
370	everything in <result>/<desc> after (and including) the first dot, so express
371	the matter of the error code in the first sentence and keep it short.
372	-->
373
374	<descGroup/>
375
376	<!--
377	// all common enums
378	/////////////////////////////////////////////////////////////////////////
379	-->
380
381	<enum name="SettingsVersion"
382	uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f"
383	>
384	<desc>Settings version of VirtualBox settings files. This is written to
385	the "version" attribute of the root "VirtualBox" element in the settings
386	file XML and indicates which VirtualBox version wrote the file.
387	</desc>
388
389	<const name="Null" value="0">
390	<desc>Null value, indicates invalid version.</desc>
391	</const>
392	<const name="v1_0" value="1">
393	<desc>Legacy settings version, not currently supported.</desc>
394	</const>
395	<const name="v1_1" value="2">
396	<desc>Legacy settings version, not currently supported.</desc>
397	</const>
398	<const name="v1_2" value="3">
399	<desc>Legacy settings version, not currently supported.</desc>
400	</const>
401	<const name="v1_3pre" value="4">
402	<desc>Legacy settings version, not currently supported.</desc>
403	</const>
404	<const name="v1_3" value="5">
405	<desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>
406	<!--
407	Machine XML: Capitalization of Uart, Lpt elements and many attributes changed.
408	-->
409	</const>
410	<const name="v1_4" value="6">
411	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
412	<!--
413	VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged
414	(was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk)
415	-->
416	</const>
417	<const name="v1_5" value="7">
418	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
419	<!-- 2008-09-04: 2.0.0 released
420	2008-11-20: settings version 1.5 introduced
421	2008-12-17: 2.1.0 released
422	Machine changes:
423	guest OS identifiers changed;
424	Machine/Hardware/Display/MonitorCount renamed to monitorCount;
425	Machine/Hardware/Display/Accelerate3D renamed to accelerate3D;
426	Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count
427	-->
428	</const>
429	<const name="v1_6" value="8">
430	<desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>
431	<!-- 2008-12-17: 2.1.0 released
432	2008-12-19: settings version 1.6 introduced (is in 2.1 branch)
433	2009-04-08: 2.2.0 released
434	Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done)
435	-->
436	</const>
437	<const name="v1_7" value="9">
438	<desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>
439	<!-- 2008-12-17: 2.1.0 released
440	2009-03-11: settings version 1.7 introduced (is in 2.2 branch)
441	2009-04-08: 2.2.0 released
442	VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done)
443	Machine changes: HardDiskAttachments is now StorageControllers (done)
444	-->
445	</const>
446	<const name="v1_8" value="10">
447	<desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>
448	<!-- Machine additions: Display/@accelerate2DVideo (done)
449	-->
450	</const>
451	<const name="v1_9" value="11">
452	<desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>
453	<!-- The big storage controller / DVD / Floppy rework (done)
454	-->
455	</const>
456	<const name="Future" value="12">
457	<desc>Settings version greater than "1.9", written by a future VirtualBox version.</desc>
458	</const>
459	</enum>
460
461	<enum
462	name="AccessMode"
463	uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
464	>
465	<desc>
466	Access mode for opening files.
467	</desc>
468
469	<const name="ReadOnly" value="1"/>
470	<const name="ReadWrite" value="2"/>
471	</enum>
472
473	<enum
474	name="MachineState"
475	uuid="73bf04d0-7c4f-4684-9abf-d65a9ad74343"
476	>
477	<desc>
478	Virtual machine execution state.
479
480	This enumeration represents possible values of the <link
481	to="IMachine::state"/> attribute.
482
483	Below is the basic virtual machine state diagram. It shows how the state
484	changes during virtual machine execution. The text in square braces shows
485	a method of the IConsole interface that performs the given state
486	transition.
487
488	<pre>
489	+---------[powerDown()] <- Stuck <--[failure]-+
490	V \|
491	+-> PoweredOff --+-->[powerUp()]--> Starting --+ \| +-----[resume()]-----+
492	\| \| \| \| V \|
493	\| Aborted -----+ +--> Running --[pause()]--> Paused
494	\| \| ^ \| ^ \|
495	\| Saved -----------[powerUp()]--> Restoring -+ \| \| \| \|
496	\| ^ \| \| \| \|
497	\| \| +-----------------------------------------+-\|-------------------+ +
498	\| \| \| \| \|
499	\| \| +-- Saving <--------[takeSnapshot()]<-------+---------------------+
500	\| \| \| \|
501	\| +-------- Saving <--------[saveState()]<----------+---------------------+
502	\| \| \|
503	+-------------- Stopping -------[powerDown()]<----------+---------------------+
504	</pre>
505
506	Note that states to the right from PoweredOff, Aborted and Saved in the
507	above diagram are called <i>online VM states</i>. These states
508	represent the virtual machine which is being executed in a dedicated
509	process (usually with a GUI window attached to it where you can see the
510	activity of the virtual machine and interact with it). There are two
511	special pseudo-states, FirstOnline and LastOnline, that can be used in
512	relational expressions to detect if the given machine state is online or
513	not:
514
515	<pre>
516	if (machine.GetState() >= MachineState_FirstOnline &&
517	machine.GetState() <= MachineState_LastOnline)
518	{
519	...the machine is being executed...
520	}
521	</pre>
522
523	When the virtual machine is in one of the online VM states (that is, being
524	executed), only a few machine settings can be modified. Methods working
525	with such settings contain an explicit note about that. An attempt to
526	change any oter setting or perform a modifying operation during this time
527	will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
528
529	All online states except Running, Paused and Stuck are transitional: they
530	represent temporary conditions of the virtual machine that will last as
531	long as the operation that initiated such a condition.
532
533	The Stuck state is a special case. It means that execution of the machine
534	has reached the "Guru Meditation" condition. This condition indicates an
535	internal VMM (virtual machine manager) failure which may happen as a
536	result of either an unhandled low-level virtual hardware exception or one
537	of the recompiler exceptions (such as the <i>too-many-traps</i>
538	condition).
539
540	Note also that any online VM state may transit to the Aborted state. This
541	happens if the process that is executing the virtual machine terminates
542	unexpectedly (for example, crashes). Other than that, the Aborted state is
543	equivalent to PoweredOff.
544
545	There are also a few additional state diagrams that do not deal with
546	virtual machine execution and therefore are shown separately. The states
547	shown on these diagrams are called <i>offline VM states</i> (this includes
548	PoweredOff, Aborted and Saved too).
549
550	The first diagram shows what happens when a lengthy setup operation is
551	being executed (such as <link to="IMachine::attachDevice"/>).
552
553	<pre>
554	+----------------------------------(same state as before the call)------+
555	\| \|
556	+-> PoweredOff --+ \|
557	\| \| \|
558	\|-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
559	\| \|
560	+-> Saved -------+
561	</pre>
562
563	The next two diagrams demonstrate the process of taking a snapshot of a
564	powered off virtual machine and performing one of the "discard..."
565	operations, respectively.
566
567	<pre>
568	+----------------------------------(same state as before the call)------+
569	\| \|
570	+-> PoweredOff --+ \|
571	\| +-->[takeSnapshot()] -------------------> Saving ------+
572	+-> Aborted -----+
573
574	+-> PoweredOff --+
575	\| \|
576	\| Aborted -----+-->[discardSnapshot() ]-------------> Discarding --+
577	\| \| [discardCurrentState()] \|
578	+-> Saved -------+ [discardCurrentSnapshotAndState()] \|
579	\| \|
580	+---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
581	</pre>
582
583	Note that the Saving state is present in both the offline state group and
584	online state group. Currently, the only way to determine what group is
585	assumed in a particular case is to remember the previous machine state: if
586	it was Running or Paused, then Saving is an online state, otherwise it is
587	an offline state. This inconsistency may be removed in one of the future
588	versions of VirtualBox by adding a new state.
589
590	<note internal="yes">
591	For whoever decides to touch this enum: In order to keep the
592	comparisons involving FirstOnline and LastOnline pseudo-states valid,
593	the numeric values of these states must be correspondingly updated if
594	needed: for any online VM state, the condition
595	<tt>FirstOnline <= state <= LastOnline</tt> must be
596	@c true. The same relates to transient states for which
597	the condition <tt>FirstOnline <= state <= LastOnline</tt> must be
598	@c true.
599	</note>
600	</desc>
601
602	<const name="Null" value="0">
603	<desc>Null value (never used by the API).</desc>
604	</const>
605	<const name="PoweredOff" value="1">
606	<desc>
607	The machine is not running and has no saved execution state; it has
608	either never been started or been shut down successfully.
609	</desc>
610	</const>
611	<const name="Saved" value="2">
612	<desc>
613	The machine is not currently running, but the execution state of the machine
614	has been saved to an external file when it was running, from where
615	it can be resumed.
616	</desc>
617	</const>
618	<const name="Aborted" value="3">
619	<desc>
620	The process running the machine has terminated abnormally. This may
621	indicate a crash of the VM process in host execution context, or
622	the VM process has been terminated externally.
623	</desc>
624	</const>
625	<const name="Running" value="4">
626	<desc>
627	The machine is currently being executed.
628	<note internal="yes">
629	For whoever decides to touch this enum: In order to keep the
630	comparisons in the old source code valid, this state must immediately
631	precede the Paused state.
632	</note>
633	</desc>
634	</const>
635	<const name="Paused" value="5">
636	<desc>
637	Execution of the machine has been paused.
638	<note internal="yes">
639	For whoever decides to touch this enum: In order to keep the
640	comparisons in the old source code valid, this state must immediately
641	follow the Running state.
642	</note>
643	</desc>
644	</const>
645	<const name="Stuck" value="6">
646	<desc>
647	Execution of the machine has reached the "Guru Meditation"
648	condition. This indicates a severe error in the hypervisor itself.
649	</desc>
650	</const>
651	<const name="Starting" value="7">
652	<desc>
653	Machine is being started after powering it on from a
654	zero execution state.
655	</desc>
656	</const>
657	<const name="Stopping" value="8">
658	<desc>
659	Machine is being normally stopped powering it off, or after the guest OS
660	has initiated a shutdown sequence.
661	</desc>
662	</const>
663	<const name="Saving" value="9">
664	<desc>
665	Machine is saving its execution state to a file, or an online
666	snapshot of the machine is being taken.
667	</desc>
668	</const>
669	<const name="Restoring" value="10">
670	<desc>
671	Execution state of the machine is being restored from a file
672	after powering it on from the saved execution state.
673	</desc>
674	</const>
675	<const name="Discarding" value="11">
676	<desc>
677	Snapshot of the machine is being discarded.
678	</desc>
679	</const>
680	<const name="SettingUp" value="12">
681	<desc>
682	Lengthy setup operation is in progress.
683	</desc>
684	</const>
685
686	<const name="FirstOnline" value="4" wsmap="suppress"> <!-- Running -->
687	<desc>
688	Pseudo-state: first online state (for use in relational expressions).
689	</desc>
690	</const>
691	<const name="LastOnline" value="10" wsmap="suppress"> <!-- Restoring -->
692	<desc>
693	Pseudo-state: last online state (for use in relational expressions).
694	</desc>
695	</const>
696
697	<const name="FirstTransient" value="7" wsmap="suppress"> <!-- Starting -->
698	<desc>
699	Pseudo-state: first transient state (for use in relational expressions).
700	</desc>
701	</const>
702	<const name="LastTransient" value="12" wsmap="suppress"> <!-- SettingUp -->
703	<desc>
704	Pseudo-state: last transient state (for use in relational expressions).
705	</desc>
706	</const>
707
708	</enum>
709
710	<enum
711	name="SessionState"
712	uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
713	>
714	<desc>
715	Session state. This enumeration represents possible values of
716	<link to="IMachine::sessionState"/> and <link to="ISession::state"/>
717	attributes. See individual enumerator descriptions for the meaning for
718	every value.
719	</desc>
720
721	<const name="Null" value="0">
722	<desc>Null value (never used by the API).</desc>
723	</const>
724	<const name="Closed" value="1">
725	<desc>
726	The machine has no open sessions (<link to="IMachine::sessionState"/>);
727	the session is closed (<link to="ISession::state"/>)
728	</desc>
729	</const>
730	<const name="Open" value="2">
731	<desc>
732	The machine has an open direct session (<link to="IMachine::sessionState"/>);
733	the session is open (<link to="ISession::state"/>)
734	</desc>
735	</const>
736	<const name="Spawning" value="3">
737	<desc>
738	A new (direct) session is being opened for the machine
739	as a result of <link to="IVirtualBox::openRemoteSession"/>
740	call (<link to="IMachine::sessionState"/>);
741	the session is currently being opened
742	as a result of <link to="IVirtualBox::openRemoteSession"/>
743	call (<link to="ISession::state"/>)
744	</desc>
745	</const>
746	<const name="Closing" value="4">
747	<desc>
748	The direct session is being closed (<link to="IMachine::sessionState"/>);
749	the session is being closed (<link to="ISession::state"/>)
750	</desc>
751	</const>
752	</enum>
753
754	<enum
755	name="SessionType"
756	uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
757	>
758	<desc>
759	Session type. This enumeration represents possible values of the
760	<link to="ISession::type"/> attribute.
761	</desc>
762
763	<const name="Null" value="0">
764	<desc>Null value (never used by the API).</desc>
765	</const>
766	<const name="Direct" value="1">
767	<desc>
768	Direct session
769	(opened by <link to="IVirtualBox::openSession"/>)
770	</desc>
771	</const>
772	<const name="Remote" value="2">
773	<desc>
774	Remote session
775	(opened by <link to="IVirtualBox::openRemoteSession"/>)
776	</desc>
777	</const>
778	<const name="Existing" value="3">
779	<desc>
780	Existing session
781	(opened by <link to="IVirtualBox::openExistingSession"/>)
782	</desc>
783	</const>
784	</enum>
785
786	<enum
787	name="DeviceType"
788	uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
789	>
790	<desc>
791	Device type.
792	</desc>
793	<const name="Null" value="0">
794	<desc>
795	Null value, may also mean "no device" (not allowed for
796	<link to="IConsole::getDeviceActivity"/>).
797	</desc>
798	</const>
799	<const name="Floppy" value="1">
800	<desc>Floppy device.</desc>
801	</const>
802	<const name="DVD" value="2">
803	<desc>CD/DVD-ROM device.</desc>
804	</const>
805	<const name="HardDisk" value="3">
806	<desc>Hard disk device.</desc>
807	</const>
808	<const name="Network" value="4">
809	<desc>Network device.</desc>
810	</const>
811	<const name="USB" value="5">
812	<desc>USB device.</desc>
813	</const>
814	<const name="SharedFolder" value="6">
815	<desc>Shared folder device.</desc>
816	</const>
817	</enum>
818
819	<enum
820	name="DeviceActivity"
821	uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
822	>
823	<desc>
824	Device activity for <link to="IConsole::getDeviceActivity"/>.
825	</desc>
826
827	<const name="Null" value="0"/>
828	<const name="Idle" value="1"/>
829	<const name="Reading" value="2"/>
830	<const name="Writing" value="3"/>
831	</enum>
832
833	<enum
834	name="ClipboardMode"
835	uuid="33364716-4008-4701-8f14-be0fa3d62950"
836	>
837	<desc>
838	Host-Guest clipboard interchange mode.
839	</desc>
840
841	<const name="Disabled" value="0"/>
842	<const name="HostToGuest" value="1"/>
843	<const name="GuestToHost" value="2"/>
844	<const name="Bidirectional" value="3"/>
845	</enum>
846
847	<enum
848	name="Scope"
849	uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
850	>
851	<desc>
852	Scope of the operation.
853
854	A generic enumeration used in various methods to define the action or
855	argument scope.
856	</desc>
857
858	<const name="Global" value="0"/>
859	<const name="Machine" value="1"/>
860	<const name="Session" value="2"/>
861	</enum>
862
863	<enum
864	name="GuestStatisticType"
865	uuid="aa7c1d71-aafe-47a8-9608-27d2d337cf55"
866	>
867	<desc>
868	Statistics type for <link to="IGuest::getStatistic"/>.
869	</desc>
870
871	<const name="CPULoad_Idle" value="0">
872	<desc>
873	Idle CPU load (0-100%) for last interval.
874	</desc>
875	</const>
876	<const name="CPULoad_Kernel" value="1">
877	<desc>
878	Kernel CPU load (0-100%) for last interval.
879	</desc>
880	</const>
881	<const name="CPULoad_User" value="2">
882	<desc>
883	User CPU load (0-100%) for last interval.
884	</desc>
885	</const>
886	<const name="Threads" value="3">
887	<desc>
888	Total number of threads in the system.
889	</desc>
890	</const>
891	<const name="Processes" value="4">
892	<desc>
893	Total number of processes in the system.
894	</desc>
895	</const>
896	<const name="Handles" value="5">
897	<desc>
898	Total number of handles in the system.
899	</desc>
900	</const>
901	<const name="MemoryLoad" value="6">
902	<desc>
903	Memory load (0-100%).
904	</desc>
905	</const>
906	<const name="PhysMemTotal" value="7">
907	<desc>
908	Total physical memory in megabytes.
909	</desc>
910	</const>
911	<const name="PhysMemAvailable" value="8">
912	<desc>
913	Free physical memory in megabytes.
914	</desc>
915	</const>
916	<const name="PhysMemBalloon" value="9">
917	<desc>
918	Ballooned physical memory in megabytes.
919	</desc>
920	</const>
921	<const name="MemCommitTotal" value="10">
922	<desc>
923	Total amount of memory in the committed state in megabytes.
924	</desc>
925	</const>
926	<const name="MemKernelTotal" value="11">
927	<desc>
928	Total amount of memory used by the guest OS's kernel in megabytes.
929	</desc>
930	</const>
931	<const name="MemKernelPaged" value="12">
932	<desc>
933	Total amount of paged memory used by the guest OS's kernel in megabytes.
934	</desc>
935	</const>
936	<const name="MemKernelNonpaged" value="13">
937	<desc>
938	Total amount of non-paged memory used by the guest OS's kernel in megabytes.
939	</desc>
940	</const>
941	<const name="MemSystemCache" value="14">
942	<desc>
943	Total amount of memory used by the guest OS's system cache in megabytes.
944	</desc>
945	</const>
946	<const name="PageFileSize" value="15">
947	<desc>
948	Pagefile size in megabytes.
949	</desc>
950	</const>
951	<const name="SampleNumber" value="16">
952	<desc>
953	Statistics sample number
954	</desc>
955	</const>
956	<const name="MaxVal" value="17"/>
957	</enum>
958
959	<enum
960	name="BIOSBootMenuMode"
961	uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
962	>
963	<desc>
964	BIOS boot menu mode.
965	</desc>
966
967	<const name="Disabled" value="0"/>
968	<const name="MenuOnly" value="1"/>
969	<const name="MessageAndMenu" value="2"/>
970	</enum>
971
972	<enum
973	name="ProcessorFeature"
974	uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
975	>
976	<desc>
977	CPU features.
978	</desc>
979
980	<const name="HWVirtEx" value="0"/>
981	<const name="PAE" value="1"/>
982	<const name="LongMode" value="2"/>
983	<const name="NestedPaging" value="3"/>
984	</enum>
985
986	<enum
987	name="FirmwareType"
988	uuid="7ceea938-8b49-41e2-bb47-667219c0d586"
989	>
990	<desc>
991	Firmware type.
992	</desc>
993	<const name="BIOS" value="1">
994	<desc>BIOS Firmware.</desc>
995	</const>
996	<const name="EFI" value="2">
997	<desc>Efi firmware.</desc>
998	</const>
999	</enum>
1000
1001	<!--
1002	// IVirtualBoxErrorInfo
1003	/////////////////////////////////////////////////////////////////////////
1004	-->
1005
1006	<interface
1007	name="IVirtualBoxErrorInfo" extends="$errorinfo"
1008	uuid="4b86d186-407e-4f9e-8be8-e50061be8725"
1009	supportsErrorInfo="no"
1010	wsmap="managed"
1011	>
1012	<desc>
1013	The IVirtualBoxErrorInfo interface represents extended error information.
1014
1015	Extended error information can be set by VirtualBox components after
1016	unsuccessful or partially successful method invocation. This information
1017	can be retrieved by the calling party as an IVirtualBoxErrorInfo object
1018	and then shown to the client in addition to the plain 32-bit result code.
1019
1020	In MS COM, this interface extends the IErrorInfo interface,
1021	in XPCOM, it extends the nsIException interface. In both cases,
1022	it provides a set of common attributes to retrieve error
1023	information.
1024
1025	Sometimes invocation of some component's method may involve methods of
1026	other components that may also fail (independently of this method's
1027	failure), or a series of non-fatal errors may precede a fatal error that
1028	causes method failure. In cases like that, it may be desirable to preserve
1029	information about all errors happened during method invocation and deliver
1030	it to the caller. The <link to="#next"/> attribute is intended
1031	specifically for this purpose and allows to represent a chain of errors
1032	through a single IVirtualBoxErrorInfo object set after method invocation.
1033
1034	Note that errors are stored to a chain in the reverse order, i.e. the
1035	initial error object you query right after method invocation is the last
1036	error set by the callee, the object it points to in the @a next attribute
1037	is the previous error and so on, up to the first error (which is the last
1038	in the chain).
1039	</desc>
1040
1041	<attribute name="resultCode" type="long" readonly="yes">
1042	<desc>
1043	Result code of the error.
1044	Usually, it will be the same as the result code returned
1045	by the method that provided this error information, but not
1046	always. For example, on Win32, CoCreateInstance() will most
1047	likely return E_NOINTERFACE upon unsuccessful component
1048	instantiation attempt, but not the value the component factory
1049	returned. Value is typed 'long', not 'result',
1050	to make interface usable from scripting languages.
1051	<note>
1052	In MS COM, there is no equivalent.
1053	In XPCOM, it is the same as nsIException::result.
1054	</note>
1055	</desc>
1056	</attribute>
1057
1058	<attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
1059	<desc>
1060	UUID of the interface that defined the error.
1061	<note>
1062	In MS COM, it is the same as IErrorInfo::GetGUID, except for the
1063	data type.
1064	In XPCOM, there is no equivalent.
1065	</note>
1066	</desc>
1067	</attribute>
1068
1069	<attribute name="component" type="wstring" readonly="yes">
1070	<desc>
1071	Name of the component that generated the error.
1072	<note>
1073	In MS COM, it is the same as IErrorInfo::GetSource.
1074	In XPCOM, there is no equivalent.
1075	</note>
1076	</desc>
1077	</attribute>
1078
1079	<attribute name="text" type="wstring" readonly="yes">
1080	<desc>
1081	Text description of the error.
1082	<note>
1083	In MS COM, it is the same as IErrorInfo::GetDescription.
1084	In XPCOM, it is the same as nsIException::message.
1085	</note>
1086	</desc>
1087	</attribute>
1088
1089	<attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
1090	<desc>
1091	Next error object if there is any, or @c null otherwise.
1092	<note>
1093	In MS COM, there is no equivalent.
1094	In XPCOM, it is the same as nsIException::inner.
1095	</note>
1096	</desc>
1097	</attribute>
1098
1099	</interface>
1100
1101	<interface
1102	name="ILocalOwner" extends="$dispatched"
1103	uuid="308FF42A-DC45-49D4-A950-B1EEE5E00BB5" wsmap="suppress"
1104	>
1105	<desc>
1106	The ILocalOwner interface allows to register local objects
1107	(created without COM calls, but with new()).
1108	Once registered, calls to methods of such objects can be made
1109	from remote COM processes.
1110	The main usecase is the event callback implementation where
1111	API clients provide callback objects.
1112	</desc>
1113	<method name="setLocalObject">
1114	<desc>
1115	Set local object.
1116	</desc>
1117	<param name="object" type="$unknown" dir="in">
1118	<desc>Local object to forward requests to.
1119	If null, clears currently set local object.</desc>
1120	</param>
1121	</method>
1122	</interface>
1123
1124	<!--
1125	// IVirtualBox
1126	/////////////////////////////////////////////////////////////////////////
1127	-->
1128
1129	<interface
1130	name="IVirtualBoxCallback" extends="$unknown"
1131	uuid="9a65adf2-3ee6-406b-bca2-2b1fa05f0d0b"
1132	wsmap="suppress"
1133	>
1134
1135	<method name="onMachineStateChange">
1136	<desc>
1137	The execution state of the given machine has changed.
1138	<see>IMachine::state</see>
1139	</desc>
1140	<param name="machineId" type="uuid" mod="string" dir="in">
1141	<desc>ID of the machine this event relates to.</desc>
1142	</param>
1143	<param name="state" type="MachineState" dir="in">
1144	<desc>New execution state.</desc>
1145	</param>
1146	</method>
1147
1148	<method name="onMachineDataChange">
1149	<desc>
1150	Any of the settings of the given machine has changed.
1151	</desc>
1152	<param name="machineId" type="uuid" mod="string" dir="in">
1153	<desc>ID of the machine this event relates to.</desc>
1154	</param>
1155	</method>
1156
1157	<method name="onExtraDataCanChange">
1158	<desc>
1159	Notification when someone tries to change extra data for
1160	either the given machine or (if @c null) global extra data.
1161	This gives the chance to veto against changes.
1162	</desc>
1163	<param name="machineId" type="uuid" mod="string" dir="in">
1164	<desc>
1165	ID of the machine this event relates to
1166	(@c null ID for global extra data change requests).
1167	</desc>
1168	</param>
1169	<param name="key" type="wstring" dir="in">
1170	<desc>
1171	Extra data key for the attempted write.
1172	</desc>
1173	</param>
1174	<param name="value" type="wstring" dir="in">
1175	<desc>
1176	Extra data value for the given key.
1177	</desc>
1178	</param>
1179	<param name="error" type="wstring" dir="out">
1180	<desc>
1181	Optional error message describing the reason of the
1182	veto (ignored if this notification returns @c true).
1183	</desc>
1184	</param>
1185	<param name="allowChange" type="boolean" dir="return">
1186	<desc>
1187	Flag to indicate whether the callee agrees (@c true)
1188	or vetoes against the change (@c false).
1189	</desc>
1190	</param>
1191	</method>
1192
1193	<method name="onExtraDataChange">
1194	<desc>
1195	Notification when machine specific or global extra data
1196	has changed.
1197	</desc>
1198	<param name="machineId" type="uuid" mod="string" dir="in">
1199	<desc>
1200	ID of the machine this event relates to.
1201	Null for global extra data changes.
1202	</desc>
1203	</param>
1204	<param name="key" type="wstring" dir="in">
1205	<desc>
1206	Extra data key that has changed.
1207	</desc>
1208	</param>
1209	<param name="value" type="wstring" dir="in">
1210	<desc>
1211	Extra data value for the given key.
1212	</desc>
1213	</param>
1214	</method>
1215
1216	<method name="onMediumRegistered">
1217	<desc>
1218	The given medium was registered or unregistered
1219	within this VirtualBox installation.
1220
1221	The @a mediumType parameter describes what type of
1222	medium the specified @a mediumId refers to. Possible
1223	values are:
1224
1225	<ul>
1226	<li><link to="DeviceType_HardDisk"/>: the medium is a hard disk
1227	that, if registered, can be obtained using the
1228	<link to="IVirtualBox::getHardDisk"/> call.</li>
1229	<li><link to="DeviceType_DVD"/>: the medium is a CD/DVD image
1230	that, if registered, can be obtained using the
1231	<link to="IVirtualBox::getDVDImage"/> call.</li>
1232	<li><link to="DeviceType_Floppy"/>: the medium is a Floppy image
1233	that, if registered, can be obtained using the
1234	<link to="IVirtualBox::getFloppyImage"/> call.</li>
1235	</ul>
1236
1237	Note that if this is a deregistration notification,
1238	there is no way to access the object representing the
1239	unregistered medium. It is supposed that the
1240	application will do required cleanup based on the
1241	@a mediumId value.
1242	</desc>
1243	<param name="mediumId" type="uuid" mod="string" dir="in">
1244	<desc>ID of the medium this event relates to.</desc>
1245	</param>
1246	<param name="mediumType" type="DeviceType" dir="in">
1247	<desc>Type of the medium this event relates to.</desc>
1248	</param>
1249	<param name="registered" type="boolean" dir="in">
1250	<desc>
1251	If @c true, the medium was registered, otherwise it was
1252	unregistered.
1253	</desc>
1254	</param>
1255	</method>
1256
1257	<method name="onMachineRegistered">
1258	<desc>
1259	The given machine was registered or unregistered
1260	within this VirtualBox installation.
1261	</desc>
1262	<param name="machineId" type="uuid" mod="string" dir="in">
1263	<desc>ID of the machine this event relates to.</desc>
1264	</param>
1265	<param name="registered" type="boolean" dir="in">
1266	<desc>
1267	If @c true, the machine was registered, otherwise it was
1268	unregistered.
1269	</desc>
1270	</param>
1271	</method>
1272
1273	<method name="onSessionStateChange">
1274	<desc>
1275	The state of the session for the given machine was changed.
1276	<see>IMachine::sessionState</see>
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	<param name="state" type="SessionState" dir="in">
1282	<desc>New session state.</desc>
1283	</param>
1284	</method>
1285
1286	<method name="onSnapshotTaken">
1287	<desc>
1288	A new snapshot of the machine has been taken.
1289	<see>ISnapshot</see>
1290	</desc>
1291	<param name="machineId" type="uuid" mod="string" dir="in">
1292	<desc>ID of the machine this event relates to.</desc>
1293	</param>
1294	<param name="snapshotId" type="uuid" mod="string" dir="in">
1295	<desc>ID of the new snapshot.</desc>
1296	</param>
1297	</method>
1298
1299	<method name="onSnapshotDiscarded">
1300	<desc>
1301	Snapshot of the given machine has been discarded.
1302
1303	<note>
1304	This notification is delivered <b>after</b> the snapshot
1305	object has been uninitialized on the server (so that any
1306	attempt to call its methods will return an error).
1307	</note>
1308
1309	<see>ISnapshot</see>
1310	</desc>
1311	<param name="machineId" type="uuid" mod="string" dir="in">
1312	<desc>ID of the machine this event relates to.</desc>
1313	</param>
1314	<param name="snapshotId" type="uuid" mod="string" dir="in">
1315	<desc>
1316	ID of the discarded snapshot. @c null means the current machine
1317	state has been discarded (restored from the current snapshot).
1318	</desc>
1319	</param>
1320	</method>
1321
1322	<method name="onSnapshotChange">
1323	<desc>
1324	Snapshot properties (name and/or description) have been changed.
1325	<see>ISnapshot</see>
1326	</desc>
1327	<param name="machineId" type="uuid" mod="string" dir="in">
1328	<desc>ID of the machine this event relates to.</desc>
1329	</param>
1330	<param name="snapshotId" type="uuid" mod="string" dir="in">
1331	<desc>ID of the changed snapshot.</desc>
1332	</param>
1333	</method>
1334
1335	<method name="onGuestPropertyChange">
1336	<desc>
1337	Notification when a guest property has changed.
1338	</desc>
1339	<param name="machineId" type="uuid" mod="string" dir="in">
1340	<desc>
1341	ID of the machine this event relates to.
1342	</desc>
1343	</param>
1344	<param name="name" type="wstring" dir="in">
1345	<desc>
1346	The name of the property that has changed.
1347	</desc>
1348	</param>
1349	<param name="value" type="wstring" dir="in">
1350	<desc>
1351	The new property value.
1352	</desc>
1353	</param>
1354	<param name="flags" type="wstring" dir="in">
1355	<desc>
1356	The new property flags.
1357	</desc>
1358	</param>
1359	</method>
1360
1361	</interface>
1362
1363	<interface
1364	name="IDHCPServer" extends="$unknown"
1365	uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
1366	wsmap="managed"
1367	>
1368	<desc>
1369	The IDHCPServer interface represents the vbox dhcp server configuration.
1370
1371	To enumerate all the dhcp servers on the host, use the
1372	<link to="IVirtualBox::DHCPServers"/> attribute.
1373	</desc>
1374
1375	<attribute name="enabled" type="boolean">
1376	<desc>
1377	specifies if the dhcp server is enabled
1378	</desc>
1379	</attribute>
1380
1381	<attribute name="IPAddress" type="wstring" readonly="yes">
1382	<desc>
1383	specifies server IP
1384	</desc>
1385	</attribute>
1386
1387	<attribute name="networkMask" type="wstring" readonly="yes">
1388	<desc>
1389	specifies server network mask
1390	</desc>
1391	</attribute>
1392
1393	<attribute name="networkName" type="wstring" readonly="yes">
1394	<desc>
1395	specifies internal network name the server is used for
1396	</desc>
1397	</attribute>
1398
1399	<attribute name="lowerIP" type="wstring" readonly="yes">
1400	<desc>
1401	specifies from IP adrres in server address range
1402	</desc>
1403	</attribute>
1404
1405	<attribute name="upperIP" type="wstring" readonly="yes">
1406	<desc>
1407	specifies to IP adrres in server address range
1408	</desc>
1409	</attribute>
1410
1411	<method name="setConfiguration">
1412	<desc>
1413	configures the server
1414	<result name="E_INVALIDARG">
1415	invalid configuration supplied
1416	</result>
1417	</desc>
1418	<param name="IPAddress" type="wstring" dir="in">
1419	<desc>
1420	server IP address
1421	</desc>
1422	</param>
1423	<param name="networkMask" type="wstring" dir="in">
1424	<desc>
1425	server network mask
1426	</desc>
1427	</param>
1428	<param name="FromIPAddress" type="wstring" dir="in">
1429	<desc>
1430	server From IP address for address range
1431	</desc>
1432	</param>
1433	<param name="ToIPAddress" type="wstring" dir="in">
1434	<desc>
1435	server To IP address for address range
1436	</desc>
1437	</param>
1438	</method>
1439
1440	<method name="start">
1441	<desc>
1442	Starts DHCP server process.
1443	<result name="E_FAIL">
1444	Failed to start the process.
1445	</result>
1446	</desc>
1447	<param name="networkName" type="wstring" dir="in">
1448	<desc>
1449	Name of internal network DHCP server should attach to.
1450	</desc>
1451	</param>
1452	<param name="trunkName" type="wstring" dir="in">
1453	<desc>
1454	Name of internal network trunk.
1455	</desc>
1456	</param>
1457	<param name="trunkType" type="wstring" dir="in">
1458	<desc>
1459	Type of internal network trunk.
1460	</desc>
1461	</param>
1462	</method>
1463
1464	<method name="stop">
1465	<desc>
1466	Stops DHCP server process.
1467	<result name="E_FAIL">
1468	Failed to stop the process.
1469	</result>
1470	</desc>
1471	</method>
1472	</interface>
1473
1474	<interface
1475	name="IVirtualBox" extends="$dispatched"
1476	uuid="c1b8d85d-8f44-4314-94fc-072332bdf852"
1477	wsmap="managed"
1478	>
1479	<desc>
1480	The IVirtualBox interface represents the main interface exposed by the
1481	product that provides virtual machine management.
1482
1483	An instance of IVirtualBox is required for the product to do anything
1484	useful. Even though the interface does not expose this, internally,
1485	IVirtualBox is implemented as a singleton and actually lives in the
1486	process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1487	IVirtualBox can track the state of all virtual machines on a particular
1488	host, regardless of which frontend started them.
1489
1490	To enumerate all the virtual machines on the host, use the
1491	<link to="IVirtualBox::machines"/> attribute.
1492	</desc>
1493
1494	<attribute name="version" type="wstring" readonly="yes">
1495	<desc>
1496	A string representing the version number of the product. The
1497	format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1498	last number represents the build number and will frequently change.
1499	</desc>
1500	</attribute>
1501
1502	<attribute name="revision" type="unsigned long" readonly="yes">
1503	<desc>
1504	The internal build revision number of the product.
1505	</desc>
1506	</attribute>
1507
1508	<attribute name="packageType" type="wstring" readonly="yes">
1509	<desc>
1510	A string representing the package type of this product. The
1511	format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1512	SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1513	is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1514	this.
1515	</desc>
1516	</attribute>
1517
1518	<attribute name="homeFolder" type="wstring" readonly="yes">
1519	<desc>
1520	Full path to the directory where the global settings file,
1521	<tt>VirtualBox.xml</tt>, is stored.
1522
1523	In this version of VirtualBox, the value of this property is
1524	always <tt><user_dir>/.VirtualBox</tt> (where
1525	<tt><user_dir></tt> is the path to the user directory,
1526	as determined by the host OS), and cannot be changed.
1527
1528	This path is also used as the base to resolve relative paths in
1529	places where relative paths are allowed (unless otherwise
1530	expressly indicated).
1531	</desc>
1532	</attribute>
1533
1534	<attribute name="settingsFilePath" type="wstring" readonly="yes">
1535	<desc>
1536	Full name of the global settings file.
1537	The value of this property corresponds to the value of
1538	<link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1539	</desc>
1540	</attribute>
1541
1542	<attribute name="host" type="IHost" readonly="yes">
1543	<desc>Associated host object.</desc>
1544	</attribute>
1545
1546	<attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1547	<desc>Associated system information object.</desc>
1548	</attribute>
1549
1550	<attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1551	<desc>
1552	Array of machine objects registered within this VirtualBox instance.
1553	</desc>
1554	</attribute>
1555
1556	<attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
1557	<desc>
1558	Array of medium objects known to this VirtualBox installation.
1559
1560	This array contains only base media. All differencing
1561	media of the given base medium can be enumerated using
1562	<link to="IMedium::children"/>.
1563	</desc>
1564	</attribute>
1565
1566	<attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
1567	<desc>
1568	Array of CD/DVD image objects registered with this VirtualBox instance.
1569	</desc>
1570	</attribute>
1571
1572	<attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
1573	<desc>
1574	Array of floppy image objects registered with this VirtualBox instance.
1575	</desc>
1576	</attribute>
1577
1578	<attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1579
1580	<attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1581
1582	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1583	<desc>
1584	Collection of global shared folders. Global shared folders are
1585	available to all virtual machines.
1586
1587	New shared folders are added to the collection using
1588	<link to="#createSharedFolder"/>. Existing shared folders can be
1589	removed using <link to="#removeSharedFolder"/>.
1590
1591	<note>
1592	In the current version of the product, global shared folders are not
1593	implemented and therefore this collection is always empty.
1594	</note>
1595	</desc>
1596	</attribute>
1597
1598	<attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1599	<desc>
1600	Associated performance collector object.
1601	</desc>
1602	</attribute>
1603
1604	<attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1605	<desc>
1606	dhcp server settings.
1607	</desc>
1608	</attribute>
1609
1610	<method name="createMachine">
1611	<desc>
1612	Creates a new virtual machine.
1613
1614	The new machine is created unregistered, with the initial configuration
1615	set according to the specified guest OS type. A typical sequence of
1616	actions to create a new virtual machine is as follows:
1617
1618	<ol>
1619	<li>
1620	Call this method to have a new machine created. The returned machine
1621	object will be "mutable" allowing to change any machine property.
1622	</li>
1623
1624	<li>
1625	Configure the machine using the appropriate attributes and methods.
1626	</li>
1627
1628	<li>
1629	Call <link to="IMachine::saveSettings" /> to write the settings
1630	to the machine's XML settings file. The configuration of the newly
1631	created machine will not be saved to disk until this method is
1632	called.
1633	</li>
1634
1635	<li>
1636	Call <link to="#registerMachine" /> to add the machine to the list
1637	of machines known to VirtualBox.
1638	</li>
1639	</ol>
1640
1641	You should specify valid name for the newly created machine when calling
1642	this method. See the <link to="IMachine::name"/> attribute description
1643	for more details about the machine name.
1644
1645	The specified guest OS type identifier must match an ID of one of known
1646	guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1647	array.
1648
1649	Every machine has a <i>settings file</i> that is used to store
1650	the machine configuration. This file is stored in a directory called the
1651	<i>machine settings subfolder</i>. Both the settings subfolder and file
1652	will have a name that corresponds to the name of the virtual machine.
1653	You can specify where to create the machine setting subfolder using the
1654	@a baseFolder argument. The base folder can be absolute (full path) or
1655	relative to the <link to="IVirtualBox::homeFolder">VirtualBox home
1656	directory</link>.
1657
1658	If @a baseFolder is a @c null or empty string (which is recommended), the
1659	<link to="ISystemProperties::defaultMachineFolder">default machine
1660	settings folder</link> will be used as a base folder for the created
1661	machine. Otherwise the given base folder will be used. In either case,
1662	the full path to the resulting settings file has the following
1663	structure:
1664	<pre>
1665	<base_folder>/<machine_name>/<machine_name>.xml
1666	</pre>
1667
1668	Note that if the resulting settings file already exists, this method
1669	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1670
1671	Optionally, you may specify an UUID of to assign to the created machine.
1672	However, this is not recommended and you should normally pass an empty
1673	(@c null) UUID to this method so that a new UUID will be automatically
1674	generated for every created machine. You can use UUID
1675	00000000-0000-0000-0000-000000000000 as @c null value.
1676
1677	<note>
1678	There is no way to change the name of the settings file or
1679	subfolder of the created machine directly.
1680	</note>
1681
1682	<result name="VBOX_E_OBJECT_NOT_FOUND">
1683	@a osTypeId is invalid.
1684	</result>
1685	<result name="VBOX_E_FILE_ERROR">
1686	Resulting settings file name is invalid or the settings file already
1687	exists or could not be created due to an I/O error.
1688	</result>
1689	<result name="E_INVALIDARG">
1690	@a name is empty or @c null.
1691	</result>
1692	</desc>
1693
1694	<param name="name" type="wstring" dir="in">
1695	<desc>Machine name.</desc>
1696	</param>
1697	<param name="osTypeId" type="wstring" dir="in">
1698	<desc>Guest OS Type ID.</desc>
1699	</param>
1700	<param name="baseFolder" type="wstring" dir="in">
1701	<desc>Base machine folder (optional).</desc>
1702	</param>
1703	<param name="id" type="uuid" mod="string" dir="in">
1704	<desc>Machine UUID (optional).</desc>
1705	</param>
1706	<param name="machine" type="IMachine" dir="return">
1707	<desc>Created machine object.</desc>
1708	</param>
1709	</method>
1710
1711	<method name="createLegacyMachine">
1712	<desc>
1713	Creates a new virtual machine in "legacy" mode, using the specified
1714	settings file to store machine settings.
1715
1716	As opposed to machines created by <link to="#createMachine"/>,
1717	the settings file of the machine created in "legacy" mode is not
1718	automatically renamed when the machine name is changed -- it will always
1719	remain the same as specified in this method call.
1720
1721	The specified settings file name can be absolute (full path) or relative
1722	to the <link to="IVirtualBox::homeFolder">VirtualBox home
1723	directory</link>. If the file name doesn't contain an extension, the
1724	default extension (.xml) will be appended.
1725
1726	Note that the configuration of the newly created machine is not
1727	saved to disk (and therefore no settings file is created)
1728	until <link to="IMachine::saveSettings"/> is called. If the
1729	specified settings file already exists, this method
1730	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1731
1732	See <link to="#createMachine"/> for more information.
1733
1734	@deprecated This method may be removed later. Use <link
1735	to="IVirtualBox::createMachine"/> instead.
1736
1737	<note>
1738	There is no way to change the name of the settings file
1739	of the machine created in "legacy" mode.
1740	</note>
1741
1742	<result name="VBOX_E_OBJECT_NOT_FOUND">
1743	@a osTypeId is invalid.
1744	</result>
1745	<result name="VBOX_E_FILE_ERROR">
1746	@a settingsFile is invalid or the settings file already exists or
1747	could not be created due to an I/O error.
1748	</result>
1749	<result name="E_INVALIDARG">
1750	@a name or @a settingsFile is empty or @c null.
1751	</result>
1752	</desc>
1753
1754	<param name="name" type="wstring" dir="in">
1755	<desc>Machine name.</desc>
1756	</param>
1757	<param name="osTypeId" type="wstring" dir="in">
1758	<desc>Machine OS Type ID.</desc>
1759	</param>
1760	<param name="settingsFile" type="wstring" dir="in">
1761	<desc>Name of the machine settings file.</desc>
1762	</param>
1763	<param name="id" type="uuid" mod="string" dir="in">
1764	<desc>Machine UUID (optional).</desc>
1765	</param>
1766	<param name="machine" type="IMachine" dir="return">
1767	<desc>Created machine object.</desc>
1768	</param>
1769	</method>
1770
1771	<method name="openMachine">
1772	<desc>
1773	Opens a virtual machine from the existing settings file.
1774	The opened machine remains unregistered until you call
1775	<link to="#registerMachine"/>.
1776
1777	The specified settings file name can be absolute
1778	(full path) or relative to the <link to="IVirtualBox::homeFolder">
1779	VirtualBox home directory</link>. This file must exist
1780	and must be a valid machine settings file whose contents
1781	will be used to construct the machine object.
1782
1783	@deprecated Will be removed soon.
1784	<result name="VBOX_E_FILE_ERROR">
1785	Settings file name invalid, not found or sharing violation.
1786	</result>
1787	</desc>
1788	<param name="settingsFile" type="wstring" dir="in">
1789	<desc>
1790	Name of the machine settings file.
1791	</desc>
1792	</param>
1793	<param name="machine" type="IMachine" dir="return">
1794	<desc>Opened machine object.</desc>
1795	</param>
1796	<note>
1797	<link to="IMachine::settingsModified"/> will return
1798	@c false for the created machine, until any of machine settings
1799	are changed.
1800	</note>
1801	</method>
1802
1803	<method name="registerMachine">
1804	<desc>
1805
1806	Registers the machine previously created using
1807	<link to="#createMachine"/> or opened using
1808	<link to="#openMachine"/> within this VirtualBox installation. After
1809	successful method invocation, the
1810	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1811	to all registered callbacks.
1812
1813	<note>
1814	This method implicitly calls <link to="IMachine::saveSettings"/>
1815	to save all current machine settings before registering it.
1816	</note>
1817
1818	<result name="VBOX_E_OBJECT_NOT_FOUND">
1819	No matching virtual machine found.
1820	</result>
1821	<result name="VBOX_E_INVALID_OBJECT_STATE">
1822	Virtual machine was not created within this VirtualBox instance.
1823	</result>
1824
1825	</desc>
1826	<param name="machine" type="IMachine" dir="in"/>
1827	</method>
1828
1829	<method name="getMachine">
1830	<desc>
1831	Attempts to find a virtual machine given its UUID.
1832	To look up a machine by name, use <link to="IVirtualBox::findMachine" />
1833	instead.
1834
1835	<result name="VBOX_E_OBJECT_NOT_FOUND">
1836	Could not find registered machine matching @a id.
1837	</result>
1838
1839	</desc>
1840	<param name="id" type="uuid" mod="string" dir="in"/>
1841	<param name="machine" type="IMachine" dir="return"/>
1842	</method>
1843
1844	<method name="findMachine">
1845	<desc>
1846	Attempts to find a virtual machine given its name.
1847	To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
1848	instead.
1849
1850	<result name="VBOX_E_OBJECT_NOT_FOUND">
1851	Could not find registered machine matching @a name.
1852	</result>
1853
1854	</desc>
1855	<param name="name" type="wstring" dir="in"/>
1856	<param name="machine" type="IMachine" dir="return"/>
1857	</method>
1858
1859	<method name="unregisterMachine">
1860	<desc>
1861
1862	Unregisters the machine previously registered using
1863	<link to="#registerMachine"/>. After successful method invocation, the
1864	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1865	to all registered callbacks.
1866
1867	<note>
1868	The specified machine must not be in the Saved state, have an open
1869	(or a spawning) direct session associated with it, have snapshots or
1870	have hard disks attached.
1871	</note>
1872
1873	<note>
1874	This method implicitly calls <link to="IMachine::saveSettings"/> to
1875	save all current machine settings before unregistering it.
1876	</note>
1877
1878	<note>
1879	If the given machine is inaccessible (see
1880	<link to="IMachine::accessible"/>), it will be unregistered and
1881	fully uninitialized right afterwards. As a result, the returned
1882	machine object will be unusable and an attempt to call
1883	<b>any</b> method will return the "Object not ready" error.
1884	</note>
1885
1886	<result name="VBOX_E_OBJECT_NOT_FOUND">
1887	Could not find registered machine matching @a id.
1888	</result>
1889	<result name="VBOX_E_INVALID_VM_STATE">
1890	Machine is in Saved state.
1891	</result>
1892	<result name="VBOX_E_INVALID_OBJECT_STATE">
1893	Machine has snapshot or open session or hard disk attached.
1894	</result>
1895
1896	</desc>
1897	<param name="id" type="uuid" mod="string" dir="in">
1898	<desc>UUID of the machine to unregister.</desc>
1899	</param>
1900	<param name="machine" type="IMachine" dir="return">
1901	<desc>Unregistered machine object.</desc>
1902	</param>
1903	</method>
1904
1905	<method name="createAppliance">
1906	<desc>
1907	Creates a new appliance object, which represents an appliance in the Open Virtual Machine
1908	Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
1909	machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
1910	</desc>
1911	<param name="appliance" type="IAppliance" dir="return">
1912	<desc>New appliance.</desc>
1913	</param>
1914	</method>
1915
1916	<method name="createHardDisk">
1917	<desc>
1918	Creates a new base medium object that will use the given storage
1919	format and location for medium data.
1920
1921	Note that the actual storage unit is not created by this method. In
1922	order to do it, and before you are able to attach the created medium
1923	to virtual machines, you must call one of the following methods to
1924	allocate a format-specific storage unit at the specified location:
1925	<ul>
1926	<li><link to="IMedium::createBaseStorage"/></li>
1927	<li><link to="IMedium::createDiffStorage"/></li>
1928	</ul>
1929
1930	Some medium attributes, such as <link to="IMedium::id"/>, may
1931	remain uninitialized until the medium storage unit is successfully
1932	created by one of the above methods.
1933
1934	After the storage unit is successfully created, the medium gets
1935	remembered by this VirtualBox installation and will be accessible
1936	through <link to="#getHardDisk"/> and <link to="#findHardDisk"/>
1937	methods. Remembered base medium are also returned as part of
1938	the <link to="#hardDisks"/> array. See IMedium for more details.
1939
1940	The list of all storage formats supported by this VirtualBox
1941	installation can be obtained using
1942	<link to="ISystemProperties::mediumFormats"/>. If the @a format
1943	attribute is empty or @c null then the default storage format
1944	specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
1945	be used for creating a storage unit of the medium.
1946
1947	Note that the format of the location string is storage format specific.
1948	See <link to="IMedium::location"/>, IMedium and
1949	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1950
1951	<result name="VBOX_E_OBJECT_NOT_FOUND">
1952	@a format identifier is invalid. See
1953	<link to="ISystemProperties::mediumFormats"/>.
1954	</result>
1955	<result name="VBOX_E_FILE_ERROR">
1956	@a location is a not valid file name (for file-based formats only).
1957	</result>
1958	</desc>
1959	<param name="format" type="wstring" dir="in">
1960	<desc>
1961	Identifier of the storage format to use for the new medium.
1962	</desc>
1963	</param>
1964	<param name="location" type="wstring" dir="in">
1965	<desc>
1966	Location of the storage unit for the new medium.
1967	</desc>
1968	</param>
1969	<param name="medium" type="IMedium" dir="return">
1970	<desc>Created medium object.</desc>
1971	</param>
1972	</method>
1973
1974	<method name="openHardDisk">
1975	<desc>
1976	Opens a medium from an existing location, optionally replacing
1977	the image UUID and/or parent UUID.
1978
1979	After the medium is successfully opened by this method, it gets
1980	remembered by (known to) this VirtualBox installation and will be
1981	accessible through <link to="#getHardDisk"/> and
1982	<link to="#findHardDisk"/> methods. Remembered base media
1983	are also returned as part of the <link to="#hardDisks"/> array and can
1984	be attached to virtual machines. See IMedium for more details.
1985
1986	If a differencing medium is to be opened by this method, the
1987	operation will succeed only if its parent medium and all ancestors,
1988	if any, are already known to this VirtualBox installation (for example,
1989	were opened by this method before).
1990
1991	This method tries to guess the storage format of the specified medium
1992	by reading medium data at the specified location.
1993
1994	If @a write is ReadWrite (which it should be), the image is opened for
1995	read/write access and must have according permissions, as VirtualBox
1996	may actually write status information into the disk's metadata sections.
1997
1998	Note that write access is required for all typical image usage in VirtualBox,
1999	since VirtualBox may need to write metadata such as a UUID into the image.
2000	The only exception is opening a source image temporarily for copying and
2001	cloning when the image will quickly be closed again.
2002
2003	Note that the format of the location string is storage format specific.
2004	See <link to="IMedium::location"/>, IMedium and
2005	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
2006
2007	<result name="VBOX_E_FILE_ERROR">
2008	Invalid medium storage file location or could not find the medium
2009	at the specified location.
2010	</result>
2011	<result name="VBOX_E_IPRT_ERROR">
2012	Could not get medium storage format.
2013	</result>
2014	<result name="E_INVALIDARG">
2015	Invalid medium storage format.
2016	</result>
2017
2018	</desc>
2019	<param name="location" type="wstring" dir="in">
2020	<desc>
2021	Location of the storage unit that contains medium data in one of
2022	the supported storage formats.
2023	</desc>
2024	</param>
2025	<param name="accessMode" type="AccessMode" dir="in">
2026	<desc>
2027	Determines whether to open the image in read/write or read-only mode.
2028	</desc>
2029	</param>
2030	<param name="setImageId" type="boolean" dir="in">
2031	<desc>
2032	Select whether a new image UUID is set or not.
2033	</desc>
2034	</param>
2035	<param name="imageId" type="uuid" mod="string" dir="in">
2036	<desc>
2037	New UUID for the image. If an empty string is passed, then a new
2038	UUID is automatically created. Specifying a zero UUIDs is not valid.
2039	</desc>
2040	</param>
2041	<param name="setParentId" type="boolean" dir="in">
2042	<desc>
2043	Select whether a new parent UUID is set or not.
2044	</desc>
2045	</param>
2046	<param name="parentId" type="uuid" mod="string" dir="in">
2047	<desc>
2048	New parent UUID for the image. If an empty string is passed, then a
2049	new UUID is automatically created, provided @a setParentId is
2050	@c true. A zero UUID is valid.
2051	</desc>
2052	</param>
2053	<param name="medium" type="IMedium" dir="return">
2054	<desc>Opened medium object.</desc>
2055	</param>
2056	</method>
2057
2058	<method name="getHardDisk" const="yes">
2059	<desc>
2060	Returns a medium with the given UUID.
2061
2062	The medium with the given UUID must be known to this VirtualBox
2063	installation, i.e. it must be previously created by
2064	<link to="#createHardDisk"/> or opened by <link
2065	to="#openHardDisk"/>, or attached to some known virtual machine.
2066
2067	<result name="VBOX_E_OBJECT_NOT_FOUND">
2068	No medium object matching @a id found.
2069	</result>
2070
2071	</desc>
2072	<param name="id" type="uuid" mod="string" dir="in">
2073	<desc>UUID of the medium to look for.</desc>
2074	</param>
2075	<param name="medium" type="IMedium" dir="return">
2076	<desc>Found medium object.</desc>
2077	</param>
2078	</method>
2079
2080	<method name="findHardDisk">
2081	<desc>
2082	Returns a medium that uses the given location to store medium data.
2083
2084	The given medium must be known to this VirtualBox installation, i.e.
2085	it must be previously created by
2086	<link to="#createHardDisk"/> or opened by <link
2087	to="#openHardDisk"/>, or attached to some known virtual machine.
2088
2089	The search is done by comparing the value of the @a location argument to
2090	the <link to="IMedium::location"/> attribute of each known medium.
2091
2092	For locations represented by file names in the host's file system, the
2093	requested location can be a path relative to the
2094	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2095	only a file name without any path is given, the
2096	<link to="ISystemProperties::defaultHardDiskFolder"> default medium
2097	folder</link> will be prepended to the file name before searching. Note
2098	that on case sensitive file systems, a case sensitive comparison is
2099	performed, otherwise the case of symbols in the file path is ignored.
2100
2101	<result name="VBOX_E_OBJECT_NOT_FOUND">
2102	No medium object matching @a location found.
2103	</result>
2104
2105	</desc>
2106	<param name="location" type="wstring" dir="in">
2107	<desc>Location string to search for.</desc>
2108	</param>
2109	<param name="medium" type="IMedium" dir="return">
2110	<desc>Found medium object.</desc>
2111	</param>
2112	</method>
2113
2114	<method name="openDVDImage">
2115	<desc>
2116	Opens a CD/DVD image contained in the specified file of the supported
2117	format and assigns it the given UUID.
2118
2119	After the image is successfully opened by this method, it gets
2120	remembered by (known to) this VirtualBox installation and will be
2121	accessible through <link to="#getDVDImage"/> and
2122	<link to="#findDVDImage"/> methods. Remembered images are also
2123	returned as part of the <link to="#DVDImages"/> array and can be mounted
2124	to virtual machines. See IMedium for more details.
2125
2126	See <link to="IMedium::location"/> to get more details about the format
2127	of the location string.
2128
2129	<note>
2130	Currently only ISO 9960 CD/DVD images are supported by VirtualBox.
2131	</note>
2132
2133	<result name="VBOX_E_FILE_ERROR">
2134	Invalid CD/DVD image file location or could not find the CD/DVD
2135	image at the specified location.
2136	</result>
2137	<result name="VBOX_E_INVALID_OBJECT_STATE">
2138	CD/DVD image already exists in the media registry.
2139	</result>
2140
2141	</desc>
2142	<param name="location" type="wstring" dir="in">
2143	<desc>
2144	Full path to the file that contains a valid CD/DVD image.
2145	</desc>
2146	</param>
2147	<param name="id" type="uuid" mod="string" dir="in">
2148	<desc>
2149	UUID to assign to the given image within this VirtualBox installation.
2150	If an empty (@c null) UUID is specified, the system will randomly
2151	generate a new UUID.
2152	</desc>
2153	</param>
2154	<param name="image" type="IMedium" dir="return">
2155	<desc>Opened CD/DVD image object.</desc>
2156	</param>
2157	</method>
2158
2159	<method name="getDVDImage">
2160	<desc>
2161	Returns a CD/DVD image with the given UUID.
2162
2163	The image with the given UUID must be known to this VirtualBox
2164	installation, i.e. it must be previously opened by <link
2165	to="#openDVDImage"/>, or mounted to some known virtual machine.
2166
2167	<result name="VBOX_E_OBJECT_NOT_FOUND">
2168	No matching DVD image found in the media registry.
2169	</result>
2170
2171	</desc>
2172	<param name="id" type="uuid" mod="string" dir="in">
2173	<desc>UUID of the image to look for.</desc>
2174	</param>
2175	<param name="image" type="IMedium" dir="return">
2176	<desc>Found CD/DVD image object.</desc>
2177	</param>
2178	</method>
2179
2180	<method name="findDVDImage">
2181	<desc>
2182	Returns a CD/DVD image with the given image location.
2183
2184	The image with the given UUID must be known to this VirtualBox
2185	installation, i.e. it must be previously opened by <link
2186	to="#openDVDImage"/>, or mounted to some known virtual machine.
2187
2188	The search is done by comparing the value of the @a location argument to
2189	the <link to="IMedium::location"/> attribute of each known CD/DVD image.
2190
2191	The requested location can be a path relative to the
2192	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2193	only a file name without any path is given, the
2194	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2195	folder</link> will be prepended to the file name before searching. Note
2196	that on case sensitive file systems, a case sensitive comparison is
2197	performed, otherwise the case in the file path is ignored.
2198
2199	<result name="VBOX_E_FILE_ERROR">
2200	Invalid image file location.
2201	</result>
2202	<result name="VBOX_E_OBJECT_NOT_FOUND">
2203	No matching DVD image found in the media registry.
2204	</result>
2205
2206	</desc>
2207	<param name="location" type="wstring" dir="in">
2208	<desc>CD/DVD image file path to look for.</desc>
2209	</param>
2210	<param name="image" type="IMedium" dir="return">
2211	<desc>Found CD/DVD image object.</desc>
2212	</param>
2213	</method>
2214
2215	<method name="openFloppyImage">
2216	<desc>
2217	Opens a floppy image contained in the specified file of the supported
2218	format and assigns it the given UUID.
2219
2220	After the image is successfully opened by this method, it gets
2221	remembered by (known to) this VirtualBox installation and will be
2222	accessible through <link to="#getFloppyImage"/> and
2223	<link to="#findFloppyImage"/> methods. Remembered images are also
2224	returned as part of the <link to="#floppyImages"/> array and can be
2225	mounted to virtual machines. See IMedium for more details.
2226
2227	See <link to="IMedium::location"/> to get more details about the format
2228	of the location string.
2229
2230	<result name="VBOX_E_FILE_ERROR">
2231	Invalid floppy image file location or could not find the floppy
2232	image at the specified location.
2233	</result>
2234	<result name="VBOX_E_INVALID_OBJECT_STATE">
2235	Floppy image already exists in the media registry.
2236	</result>
2237
2238	<note>
2239	Currently, only raw floppy images are supported by VirtualBox.
2240	</note>
2241	</desc>
2242	<param name="location" type="wstring" dir="in">
2243	<desc>
2244	Full path to the file that contains a valid floppy image.
2245	</desc>
2246	</param>
2247	<param name="id" type="uuid" mod="string" dir="in">
2248	<desc>
2249	UUID to assign to the given image file within this VirtualBox
2250	installation. If an empty (@c null) UUID is specified, the system will
2251	randomly generate a new UUID.
2252	</desc>
2253	</param>
2254	<param name="image" type="IMedium" dir="return">
2255	<desc>Opened floppy image object.</desc>
2256	</param>
2257	</method>
2258
2259	<method name="getFloppyImage">
2260	<desc>
2261	Returns a floppy image with the given UUID.
2262
2263	The image with the given UUID must be known to this VirtualBox
2264	installation, i.e. it must be previously opened by <link
2265	to="#openFloppyImage"/>, or mounted to some known virtual machine.
2266
2267	<result name="VBOX_E_OBJECT_NOT_FOUND">
2268	No matching floppy image found in the media registry.
2269	</result>
2270
2271	</desc>
2272	<param name="id" type="uuid" mod="string" dir="in">
2273	<desc>UUID of the image to look for.</desc>
2274	</param>
2275	<param name="image" type="IMedium" dir="return">
2276	<desc>Found floppy image object.</desc>
2277	</param>
2278	</method>
2279
2280	<method name="findFloppyImage">
2281	<desc>
2282	Returns a floppy image with the given image location.
2283
2284	The image with the given UUID must be known to this VirtualBox
2285	installation, i.e. it must be previously opened by <link
2286	to="#openFloppyImage"/>, or mounted to some known virtual machine.
2287
2288	The search is done by comparing the value of the @a location argument to
2289	the <link to="IMedium::location"/> attribute of each known floppy image.
2290
2291	The requested location can be a path relative to the
2292	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2293	only a file name without any path is given, the
2294	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2295	folder</link> will be prepended to the file name before searching. Note
2296	that on case sensitive file systems, a case sensitive comparison is
2297	performed, otherwise the case of symbols in the file path is ignored.
2298
2299	<result name="VBOX_E_FILE_ERROR">
2300	Invalid image file location.
2301	</result>
2302	<result name="VBOX_E_OBJECT_NOT_FOUND">
2303	No matching floppy image found in the media registry.
2304	</result>
2305
2306	</desc>
2307	<param name="location" type="wstring" dir="in">
2308	<desc>Floppy image file path to look for.</desc>
2309	</param>
2310	<param name="image" type="IMedium" dir="return">
2311	<desc>Found floppy image object.</desc>
2312	</param>
2313	</method>
2314
2315	<method name="getGuestOSType">
2316	<desc>
2317	Returns an object describing the specified guest OS type.
2318
2319	The requested guest OS type is specified using a string which is a
2320	mnemonic identifier of the guest operating system, such as
2321	<tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
2322	particular virtual machine can be read or set using the
2323	<link to="IMachine::OSTypeId"/> attribute.
2324
2325	The <link to="IVirtualBox::guestOSTypes"/> collection contains all
2326	available guest OS type objects. Each object has an
2327	<link to="IGuestOSType::id"/> attribute which contains an identifier of
2328	the guest OS this object describes.
2329
2330	<result name="E_INVALIDARG">
2331	@a id is not a valid Guest OS type.
2332	</result>
2333
2334	</desc>
2335	<param name="id" type="uuid" mod="string" dir="in">
2336	<desc>Guest OS type ID string.</desc>
2337	</param>
2338	<param name="type" type="IGuestOSType" dir="return">
2339	<desc>Guest OS type object.</desc>
2340	</param>
2341	</method>
2342
2343	<method name="createSharedFolder">
2344	<desc>
2345	Creates a new global shared folder by associating the given logical
2346	name with the given host path, adds it to the collection of shared
2347	folders and starts sharing it. Refer to the description of
2348	<link to="ISharedFolder"/> to read more about logical names.
2349	<note>
2350	In the current implementation, this operation is not
2351	implemented.
2352	</note>
2353	</desc>
2354	<param name="name" type="wstring" dir="in">
2355	<desc>Unique logical name of the shared folder.</desc>
2356	</param>
2357	<param name="hostPath" type="wstring" dir="in">
2358	<desc>Full path to the shared folder in the host file system.</desc>
2359	</param>
2360	<param name="writable" type="boolean" dir="in">
2361	<desc>Whether the share is writable or readonly</desc>
2362	</param>
2363	</method>
2364
2365	<method name="removeSharedFolder">
2366	<desc>
2367	Removes the global shared folder with the given name previously
2368	created by <link to="#createSharedFolder"/> from the collection of
2369	shared folders and stops sharing it.
2370	<note>
2371	In the current implementation, this operation is not
2372	implemented.
2373	</note>
2374	</desc>
2375	<param name="name" type="wstring" dir="in">
2376	<desc>Logical name of the shared folder to remove.</desc>
2377	</param>
2378	</method>
2379
2380	<method name="getExtraDataKeys">
2381	<desc>
2382	Returns an array representing the global extra data keys which currently
2383	have values defined.
2384	</desc>
2385	<param name="value" type="wstring" dir="return" safearray="yes">
2386	<desc>Array of extra data keys.</desc>
2387	</param>
2388	</method>
2389
2390	<method name="getExtraData">
2391	<desc>
2392	Returns associated global extra data.
2393
2394	If the requested data @a key does not exist, this function will
2395	succeed and return an empty string in the @a value argument.
2396
2397	<result name="VBOX_E_FILE_ERROR">
2398	Settings file not accessible.
2399	</result>
2400	<result name="VBOX_E_XML_ERROR">
2401	Could not parse the settings file.
2402	</result>
2403
2404	</desc>
2405	<param name="key" type="wstring" dir="in">
2406	<desc>Name of the data key to get.</desc>
2407	</param>
2408	<param name="value" type="wstring" dir="return">
2409	<desc>Value of the requested data key.</desc>
2410	</param>
2411	</method>
2412
2413	<method name="setExtraData">
2414	<desc>
2415	Sets associated global extra data.
2416
2417	If you pass @c null or empty string as a key @a value, the given @a key
2418	will be deleted.
2419
2420	<note>
2421	Before performing the actual data change, this method will ask all
2422	registered callbacks using the
2423	<link to="IVirtualBoxCallback::onExtraDataCanChange"/>
2424	notification for a permission. If one of the callbacks refuses the
2425	new value, the change will not be performed.
2426	</note>
2427	<note>
2428	On success, the
2429	<link to="IVirtualBoxCallback::onExtraDataChange"/> notification
2430	is called to inform all registered callbacks about a successful data
2431	change.
2432	</note>
2433
2434	<result name="VBOX_E_FILE_ERROR">
2435	Settings file not accessible.
2436	</result>
2437	<result name="VBOX_E_XML_ERROR">
2438	Could not parse the settings file.
2439	</result>
2440	<result name="E_ACCESSDENIED">
2441	Modification request refused.
2442	</result>
2443
2444	</desc>
2445	<param name="key" type="wstring" dir="in">
2446	<desc>Name of the data key to set.</desc>
2447	</param>
2448	<param name="value" type="wstring" dir="in">
2449	<desc>Value to assign to the key.</desc>
2450	</param>
2451	</method>
2452
2453	<method name="openSession">
2454	<desc>
2455	Opens a new direct session with the given virtual machine.
2456
2457	A direct session acts as a local lock on the given VM.
2458	There can be only one direct session open at a time for every
2459	virtual machine, protecting the VM from being manipulated by
2460	conflicting actions from different processes. Only after a
2461	direct session has been opened, one can change all VM settings
2462	and execute the VM in the process space of the session object.
2463
2464	Sessions therefore can be compared to mutex semaphores that
2465	lock a given VM for modification and execution.
2466	See <link to="ISession">ISession</link> for details.
2467
2468	<note>Unless you are writing a new VM frontend, you will not
2469	want to execute a VM in the current process. To spawn a new
2470	process that executes a VM, use
2471	<link to="IVirtualBox::openRemoteSession" />
2472	instead.</note>
2473
2474	Upon successful return, the session object can be used to
2475	get access to the machine and to the VM console.
2476
2477	In VirtualBox terminology, the machine becomes "mutable" after
2478	a session has been opened. Note that the "mutable" machine
2479	object, on which you may invoke IMachine methods to change its
2480	settings, will be a different object from the immutable IMachine
2481	objects returned by various IVirtualBox methods. To obtain a
2482	mutable IMachine object (upon which you can invoke settings methods),
2483	use the <link to="ISession::machine" /> attribute.
2484
2485	One must always call <link to="ISession::close" /> to release the
2486	lock on the machine, or the machine's state will eventually be
2487	set to "Aborted".
2488
2489	In other words, to change settings on a machine, the following
2490	sequence is typically performed:
2491
2492	<ol>
2493	<li>Call this method (openSession) to have a machine locked for
2494	the current session.</li>
2495
2496	<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
2497
2498	<li>Change the settings of the machine.</li>
2499
2500	<li>Call <link to="IMachine::saveSettings" />.</li>
2501
2502	<li>Close the session by calling <link to="ISession::close"/>.</li>
2503	</ol>
2504
2505	<result name="E_UNEXPECTED">
2506	Virtual machine not registered.
2507	</result>
2508	<result name="E_ACCESSDENIED">
2509	Process not started by OpenRemoteSession.
2510	</result>
2511	<result name="VBOX_E_OBJECT_NOT_FOUND">
2512	No matching virtual machine found.
2513	</result>
2514	<result name="VBOX_E_INVALID_OBJECT_STATE">
2515	Session already open or being opened.
2516	</result>
2517	<result name="VBOX_E_VM_ERROR">
2518	Failed to assign machine to session.
2519	</result>
2520
2521	</desc>
2522	<param name="session" type="ISession" dir="in">
2523	<desc>
2524	Session object that will represent the opened session after
2525	successful method invocation. This object must not represent
2526	the already open session.
2527	<note>
2528	This session will be automatically closed if the
2529	VirtualBox server is terminated for some reason.
2530	</note>
2531	</desc>
2532	</param>
2533	<param name="machineId" type="uuid" mod="string" dir="in">
2534	<desc>ID of the virtual machine to open a session with.</desc>
2535	</param>
2536	</method>
2537
2538	<method name="openRemoteSession">
2539	<desc>
2540	Spawns a new process that executes a virtual machine (called a
2541	"remote session").
2542
2543	Opening a remote session causes the VirtualBox server to start a new
2544	process that opens a direct session with the given VM. As a result, the
2545	VM is locked by that direct session in the new process, preventing
2546	conflicting changes from other processes. Since sessions act as locks
2547	that prevent conflicting changes, one cannot open a remote session
2548	for a VM that already has another open session (direct or remote), or
2549	is currently in the process of opening one (see <link
2550	to="IMachine::sessionState"/>).
2551
2552	While the remote session still provides some level of control over the
2553	VM execution to the caller (using the <link to="IConsole" /> interface),
2554	not all VM settings are available for modification within the remote
2555	session context.
2556
2557	This operation can take some time (a new VM is started in a new process,
2558	for which memory and other resources need to be set up). Because of this,
2559	an <link to="IProgress" /> is returned to allow the caller to wait for this
2560	asynchronous operation to be completed. Until then, the remote session
2561	object remains in the closed state, and accessing the machine or its
2562	console through it is invalid. It is recommended to use
2563	<link to="IProgress::waitForCompletion" /> or similar calls to wait for
2564	completion.
2565
2566	As with all <link to="ISession" /> objects, it is recommended to call
2567	<link to="ISession::close" /> on the local session object once openRemoteSession()
2568	has been called. However, the session's state (see <link to="ISession::state" />)
2569	will not return to "Closed" until the remote session has also closed (i.e.
2570	until the VM is no longer running). In that case, however, the state of
2571	the session will automatically change back to "Closed".
2572
2573	Currently supported session types (values of the @a type
2574	argument) are:
2575	<ul>
2576	<li><tt>"gui"</tt>: VirtualBox Qt GUI session</li>
2577	<li><tt>"vrdp"</tt>: VirtualBox VRDP Server session</li>
2578	<li><tt>"sdl"</tt>: VirtualBox SDL GUI session</li>
2579	</ul>
2580
2581	The @a environment argument is a string containing definitions of
2582	environment variables in the following format:
2583	@code
2584	NAME[=VALUE]\n
2585	NAME[=VALUE]\n
2586	...
2587	@endcode
2588	where <tt>\\n</tt> is the new line character. These environment
2589	variables will be appended to the environment of the VirtualBox server
2590	process. If an environment variable exists both in the server process
2591	and in this list, the value from this list takes precedence over the
2592	server's variable. If the value of the environment variable is
2593	omitted, this variable will be removed from the resulting environment.
2594	If the environment string is @c null or empty, the server environment
2595	is inherited by the started process as is.
2596
2597	<see>openExistingSession</see>
2598
2599	<result name="E_UNEXPECTED">
2600	Virtual machine not registered.
2601	</result>
2602	<result name="E_INVALIDARG">
2603	Invalid session type @a type.
2604	</result>
2605	<result name="VBOX_E_OBJECT_NOT_FOUND">
2606	No machine matching @a machineId found.
2607	</result>
2608	<result name="VBOX_E_INVALID_OBJECT_STATE">
2609	Session already open or being opened.
2610	</result>
2611	<result name="VBOX_E_IPRT_ERROR">
2612	Launching process for machine failed.
2613	</result>
2614	<result name="VBOX_E_VM_ERROR">
2615	Failed to assign machine to session.
2616	</result>
2617
2618	</desc>
2619	<param name="session" type="ISession" dir="in">
2620	<desc>
2621	Session object that will represent the opened remote session
2622	after successful method invocation (this object must not
2623	represent an already open session).
2624	</desc>
2625	</param>
2626	<param name="machineId" type="uuid" mod="string" dir="in">
2627	<desc>ID of the virtual machine to open a session with.</desc>
2628	</param>
2629	<param name="type" type="wstring" dir="in">
2630	<desc>
2631	Type of the remote session (case sensitive).
2632	</desc>
2633	</param>
2634	<param name="environment" type="wstring" dir="in">
2635	<desc>
2636	Environment to pass to the opened session.
2637	</desc>
2638	</param>
2639	<param name="progress" type="IProgress" dir="return">
2640	<desc>Progress object to track the operation completion.</desc>
2641	</param>
2642	</method>
2643
2644	<method name="openExistingSession">
2645	<desc>
2646	Opens a new remote session with the virtual machine for
2647	which a direct session is already open.
2648
2649	The remote session provides some level of control over the VM
2650	execution (using the IConsole interface) to the caller; however,
2651	within the remote session context, not all VM settings are available
2652	for modification.
2653
2654	As opposed to <link to="#openRemoteSession"/>, the number of
2655	remote sessions opened this way is not limited by the API
2656
2657	<note>
2658	It is an error to open a remote session with the machine that
2659	doesn't have an open direct session.
2660	</note>
2661
2662	<result name="E_UNEXPECTED">
2663	Virtual machine not registered.
2664	</result>
2665	<result name="VBOX_E_OBJECT_NOT_FOUND">
2666	No machine matching @a machineId found.
2667	</result>
2668	<result name="VBOX_E_INVALID_OBJECT_STATE">
2669	Session already open or being opened.
2670	</result>
2671	<result name="VBOX_E_INVALID_SESSION_STATE">
2672	Direct session state not Open.
2673	</result>
2674	<result name="VBOX_E_VM_ERROR">
2675	Failed to get console object from direct session or assign
2676	machine to session.
2677	</result>
2678
2679	<see>openRemoteSession</see>
2680	</desc>
2681	<param name="session" type="ISession" dir="in">
2682	<desc>
2683	Session object that will represent the open remote session
2684	after successful method invocation. This object must not
2685	represent an already open session.
2686	<note>
2687	This session will be automatically closed when the peer
2688	(direct) session dies or gets closed.
2689	</note>
2690	</desc>
2691	</param>
2692	<param name="machineId" type="uuid" mod="string" dir="in">
2693	<desc>ID of the virtual machine to open a session with.</desc>
2694	</param>
2695	</method>
2696
2697	<method name="registerCallback">
2698	<desc>
2699	Registers a new global VirtualBox callback. The methods of the given
2700	callback object will be called by VirtualBox when an appropriate
2701	event occurs.
2702
2703	<result name="E_INVALIDARG">
2704	A @c null callback cannot be registered.
2705	</result>
2706
2707	</desc>
2708	<param name="callback" type="IVirtualBoxCallback" dir="in">
2709	<desc>Callback object to register.</desc>
2710	</param>
2711	</method>
2712
2713	<method name="unregisterCallback">
2714	<desc>
2715	Unregisters the previously registered global VirtualBox callback.
2716
2717	<result name="E_INVALIDARG">
2718	Specified @a callback not registered.
2719	</result>
2720
2721	</desc>
2722	<param name="callback" type="IVirtualBoxCallback" dir="in">
2723	<desc>Callback object to unregister.</desc>
2724	</param>
2725	</method>
2726
2727	<method name="waitForPropertyChange">
2728	<desc>
2729	Blocks the caller until any of the properties represented by the
2730	@a what argument changes the value or until the given timeout interval
2731	expires.
2732
2733	The @a what argument is a comma separated list of property masks that
2734	describe properties the caller is interested in. The property mask is
2735	a string in the following format:
2736
2737	<pre>
2738	[[group.]subgroup.]name
2739	</pre>
2740
2741	where @c name is the property name and @c group, @c subgroup are zero
2742	or more property group specifiers. Each element (group or name) in
2743	the property mask may be either a Latin string or an asterisk symbol
2744	(@c "*") which is used to match any string for the given element. A
2745	property mask that doesn't contain asterisk symbols represents a
2746	single fully qualified property name.
2747
2748	Groups in the fully qualified property name go from more generic (the
2749	left-most part) to more specific (the right-most part). The first
2750	element is usually a name of the object the property belongs to. The
2751	second element may be either a property name, or a child object name,
2752	or an index if the preceding element names an object which is one of
2753	many objects of the same type. This way, property names form a
2754	hierarchy of properties. Here are some examples of property names:
2755
2756	<table>
2757	<tr>
2758	<td><tt>VirtualBox.version</tt></td>
2759	<td><link to="IVirtualBox::version"/> property</td>
2760	</tr>
2761	<tr>
2762	<td><tt>Machine.<UUID>.name</tt></td>
2763	<td><link to="IMachine::name"/> property of the machine with the
2764	given UUID</td>
2765	</tr>
2766	</table>
2767
2768	Most property names directly correspond to the properties of objects
2769	(components) provided by the VirtualBox library and may be used to
2770	track changes to these properties. However, there may be
2771	pseudo-property names that don't correspond to any existing object's
2772	property directly, as well as there may be object properties that
2773	don't have a corresponding property name that is understood by this
2774	method, and therefore changes to such properties cannot be
2775	tracked. See individual object's property descriptions to get a
2776	fully qualified property name that can be used with this method (if
2777	any).
2778
2779	There is a special property mask @c "*" (i.e. a string consisting of a
2780	single asterisk symbol) that can be used to match all properties.
2781	Below are more examples of property masks:
2782
2783	<table>
2784	<tr>
2785	<td><tt>VirtualBox.*</tt></td>
2786	<td>Track all properties of the VirtualBox object</td>
2787	</tr>
2788	<tr>
2789	<td><tt>Machine.*.name</tt></td>
2790	<td>Track changes to the <link to="IMachine::name"/> property of
2791	all registered virtual machines</td>
2792	</tr>
2793	</table>
2794
2795	<note>
2796	This function is not implemented in the current version of the
2797	product.
2798	</note>
2799	</desc>
2800	<param name="what" type="wstring" dir="in">
2801	<desc>Comma separated list of property masks.</desc>
2802	</param>
2803	<param name="timeout" type="unsigned long" dir="in">
2804	<desc>
2805	Wait timeout in milliseconds.
2806	Specify -1 for an indefinite wait.
2807	</desc>
2808	</param>
2809	<param name="changed" type="wstring" dir="out">
2810	<desc>
2811	Comma separated list of properties that have been changed and caused
2812	this method to return to the caller.
2813	</desc>
2814	</param>
2815	<param name="values" type="wstring" dir="out">
2816	<desc>Reserved, not currently used.</desc>
2817	</param>
2818	</method>
2819
2820	<!--method name="createDHCPServerForInterface">
2821	<desc>
2822	Creates a dhcp server settings to be used for the given interface
2823	<result name="E_INVALIDARG">
2824	Host network interface @a name already exists.
2825	</result>
2826	</desc>
2827	<param name="interface" type="IHostNetworkInterface" dir="in">
2828	<desc>Network Interface</desc>
2829	</param>
2830	<param name="server" type="IDHCPServer" dir="out">
2831	<desc>Dhcp server settings</desc>
2832	</param>
2833	</method-->
2834
2835	<method name="createDHCPServer">
2836	<desc>
2837	Creates a dhcp server settings to be used for the given internal network name
2838	<result name="E_INVALIDARG">
2839	Host network interface @a name already exists.
2840	</result>
2841	</desc>
2842	<param name="name" type="wstring" dir="in">
2843	<desc>server name</desc>
2844	</param>
2845	<param name="server" type="IDHCPServer" dir="return">
2846	<desc>Dhcp server settings</desc>
2847	</param>
2848	</method>
2849
2850	<method name="findDHCPServerByNetworkName">
2851	<desc>
2852	Searches a dhcp server settings to be used for the given internal network name
2853	<result name="E_INVALIDARG">
2854	Host network interface @a name already exists.
2855	</result>
2856
2857	</desc>
2858	<param name="name" type="wstring" dir="in">
2859	<desc>server name</desc>
2860	</param>
2861	<param name="server" type="IDHCPServer" dir="return">
2862	<desc>Dhcp server settings</desc>
2863	</param>
2864	</method>
2865
2866	<!--method name="findDHCPServerForInterface">
2867	<desc>
2868	Searches a dhcp server settings to be used for the given interface
2869	<result name="E_INVALIDARG">
2870	Host network interface @a name already exists.
2871	</result>
2872	</desc>
2873	<param name="interface" type="IHostNetworkInterface" dir="in">
2874	<desc>Network Interface</desc>
2875	</param>
2876	<param name="server" type="IDHCPServer" dir="out">
2877	<desc>Dhcp server settings</desc>
2878	</param>
2879	</method-->
2880
2881	<method name="removeDHCPServer">
2882	<desc>
2883	Removes the dhcp server settings
2884	<result name="E_INVALIDARG">
2885	Host network interface @a name already exists.
2886	</result>
2887	</desc>
2888	<param name="server" type="IDHCPServer" dir="in">
2889	<desc>Dhcp server settings to be removed</desc>
2890	</param>
2891	</method>
2892
2893	</interface>
2894
2895	<!--
2896	// IVFSExplorer
2897	/////////////////////////////////////////////////////////////////////////
2898	-->
2899
2900	<enum
2901	name="VFSType"
2902	uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
2903	>
2904	<desc>
2905	Virtual file systems supported by VFSExplorer.
2906	</desc>
2907
2908	<const name="File" value="1" />
2909	<const name="Cloud" value="2" />
2910	<const name="S3" value="3" />
2911	<const name="WebDav" value="4" />
2912	</enum>
2913
2914	<enum
2915	name="VFSFileType"
2916	uuid="714333cd-44e2-415f-a245-d378fa9b1242"
2917	>
2918	<desc>
2919	File types known by VFSExplorer.
2920	</desc>
2921
2922	<const name="Unknown" value="1" />
2923	<const name="Fifo" value="2" />
2924	<const name="DevChar" value="3" />
2925	<const name="Directory" value="4" />
2926	<const name="DevBlock" value="5" />
2927	<const name="File" value="6" />
2928	<const name="SymLink" value="7" />
2929	<const name="Socket" value="8" />
2930	<const name="WhiteOut" value="9" />
2931	</enum>
2932
2933	<interface
2934	name="IVFSExplorer" extends="$unknown"
2935	uuid="2bb864a1-02a3-4474-a1d4-fb5f23b742e1"
2936	wsmap="managed"
2937	>
2938	<desc>
2939	The VFSExplorer interface unifies access to different file system
2940	types. This includes local file systems as well remote file systems like
2941	S3. For a list of supported types see <link to="VFSType" />.
2942	An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
2943	</desc>
2944
2945	<attribute name="path" type="wstring" readonly="yes">
2946	<desc>Returns the current path in the virtual file system.</desc>
2947	</attribute>
2948
2949	<attribute name="type" type="VFSType" readonly="yes">
2950	<desc>Returns the file system type which is currently in use.</desc>
2951	</attribute>
2952
2953	<method name="update">
2954	<desc>Updates the internal list of files/directories from the
2955	current directory level. Use <link to="#entryList" /> to get the full list
2956	after a call to this method.</desc>
2957
2958	<param name="aProgress" type="IProgress" dir="return">
2959	<desc>Progress object to track the operation completion.</desc>
2960	</param>
2961	</method>
2962
2963	<method name="cd">
2964	<desc>Change the current directory level.</desc>
2965
2966	<param name="aDir" type="wstring" dir="in">
2967	<desc>The name of the directory to go in.</desc>
2968	</param>
2969
2970	<param name="aProgress" type="IProgress" dir="return">
2971	<desc>Progress object to track the operation completion.</desc>
2972	</param>
2973	</method>
2974
2975	<method name="cdUp">
2976	<desc>Go one directory upwards from the current directory level.</desc>
2977
2978	<param name="aProgress" type="IProgress" dir="return">
2979	<desc>Progress object to track the operation completion.</desc>
2980	</param>
2981	</method>
2982
2983	<method name="entryList">
2984	<desc>Returns a list of files/directories after a call to <link
2985	to="#update" />. The user is responsible for keeping this internal
2986	list up do date.</desc>
2987
2988	<param name="aNames" type="wstring" safearray="yes" dir="out">
2989	<desc>The list of names for the entries.</desc>
2990	</param>
2991
2992	<param name="aTypes" type="unsigned long" safearray="yes" dir="out">
2993	<desc>The list of types for the entries.</desc>
2994	</param>
2995	</method>
2996
2997	<method name="exists">
2998	<desc>Checks if the given file list exists in the current directory
2999	level.</desc>
3000
3001	<param name="aNames" type="wstring" safearray="yes" dir="in">
3002	<desc>The names to check.</desc>
3003	</param>
3004
3005	<param name="aExists" type="wstring" safearray="yes" dir="return">
3006	<desc>The names which exist.</desc>
3007	</param>
3008	</method>
3009
3010	<method name="remove">
3011	<desc>Deletes the given files in the current directory level.</desc>
3012
3013	<param name="aNames" type="wstring" safearray="yes" dir="in">
3014	<desc>The names to remove.</desc>
3015	</param>
3016
3017	<param name="aProgress" type="IProgress" dir="return">
3018	<desc>Progress object to track the operation completion.</desc>
3019	</param>
3020	</method>
3021
3022	</interface>
3023
3024	<!--
3025	// IAppliance
3026	/////////////////////////////////////////////////////////////////////////
3027	-->
3028
3029	<interface
3030	name="IAppliance" extends="$unknown"
3031	uuid="e3ba9ab9-ac2c-4266-8bd2-91c4bf721ceb"
3032	wsmap="managed"
3033	>
3034	<desc>
3035	Represents a platform-independent appliance in OVF format. An instance of this is returned
3036	by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
3037	appliances with VirtualBox.
3038
3039	The OVF standard suggests two different physical file formats:
3040
3041	<ol>
3042	<li>If the OVF is distributed as a set of files, then @a file must be a fully qualified
3043	path name to an existing OVF descriptor file with an <tt>.ovf</tt> file extension. If
3044	this descriptor file references other files, as OVF appliances distributed as a set of
3045	files most likely do, those files must be in the same directory as the descriptor file.</li>
3046
3047	<li>If the OVF is distributed as a single file, it must be in TAR format and have the
3048	<tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
3049	files and optionally other files.
3050
3051	At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
3052	be added with a later version.</li>
3053	</ol>
3054
3055	<b>Importing</b> an OVF appliance into VirtualBox as instances of
3056	<link to="IMachine" /> involves the following sequence of API calls:
3057
3058	<ol>
3059	<li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
3060	</li>
3061
3062	<li>On the new object, call <link to="#read" /> with the full path of the OVF file you
3063	would like to import. So long as this file is syntactically valid, this will succeed
3064	and return an instance of IAppliance that contains the parsed data from the OVF file.
3065	</li>
3066
3067	<li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
3068	contents of the IAppliance attributes accordingly. These can be inspected by a
3069	VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
3070	user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
3071	instances of <link to="IVirtualSystemDescription" /> which represent the virtual
3072	systems in the OVF, which in turn describe the virtual hardware prescribed by the
3073	OVF (network and hardware adapters, virtual disk images, memory size and so on).
3074	The GUI can then give the user the option to confirm and/or change these suggestions.
3075	</li>
3076
3077	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3078	virtual system to override the suggestions made by the interpret() routine.
3079	</li>
3080
3081	<li>Finally, call <link to="#importMachines" /> to create virtual machines in
3082	VirtualBox as instances of <link to="IMachine" /> that match the information in the
3083	virtual system descriptions.
3084	</li>
3085	</ol>
3086
3087	<b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
3088
3089	<ol>
3090	<li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
3091	an empty IAppliance object.
3092	</li>
3093
3094	<li>For each machine you would like to export, call <link to="IMachine::export" />
3095	with the IAppliance object you just created. This creates an instance of
3096	<link to="IVirtualSystemDescription" /> inside the appliance.
3097	</li>
3098
3099	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3100	virtual system to override the suggestions made by the export() routine.
3101	</li>
3102
3103	<li>Finally, call <link to="#write" /> with a path specification to have the OVF
3104	file written.</li>
3105	</ol>
3106
3107	</desc>
3108
3109	<attribute name="path" type="wstring" readonly="yes">
3110	<desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
3111	the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
3112	<link to="#write" /> (for export).
3113	This attribute is empty until one of these methods has been called.
3114	</desc>
3115	</attribute>
3116
3117	<attribute name="disks" type="wstring" readonly="yes" safearray="yes">
3118	<desc>
3119	Array of virtual disk definitions. One such description exists for each
3120	disk definition in the OVF; each string array item represents one such piece of
3121	disk information, with the information fields separated by tab (\\t) characters.
3122
3123	The caller should be prepared for additional fields being appended to
3124	this string in future versions of VirtualBox and therefore check for
3125	the number of tabs in the strings returned.
3126
3127	In the current version, the following eight fields are returned per string
3128	in the array:
3129
3130	<ol>
3131	<li>Disk ID (unique string identifier given to disk)</li>
3132
3133	<li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
3134
3135	<li>Populated size (optional unsigned integer indicating the current size of the
3136	disk; can be approximate; -1 if unspecified)</li>
3137
3138	<li>Format (string identifying the disk format, typically
3139	"http://www.vmware.com/specifications/vmdk.html#sparse")</li>
3140
3141	<li>Reference (where to find the disk image, typically a file name; if empty,
3142	then the disk should be created on import)</li>
3143
3144	<li>Image size (optional unsigned integer indicating the size of the image,
3145	which need not necessarily be the same as the values specified above, since
3146	the image may be compressed or sparse; -1 if not specified)</li>
3147
3148	<li>Chunk size (optional unsigned integer if the image is split into chunks;
3149	presently unsupported and always -1)</li>
3150
3151	<li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
3152	</ol>
3153	</desc>
3154	</attribute>
3155
3156	<attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
3157	<desc> Array of virtual system descriptions. One such description is created
3158	for each virtual system found in the OVF.
3159	This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
3160	(for export) has been called.
3161	</desc>
3162	</attribute>
3163
3164	<method name="read">
3165	<desc>
3166	Reads an OVF file into the appliance object.
3167
3168	This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
3169	mere fact that this method returns successfully does not mean that VirtualBox supports all
3170	features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
3171	</desc>
3172	<param name="file" type="wstring" dir="in">
3173	<desc>
3174	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3175	on whether the appliance is distributed as a set of files or as a single file, respectively).
3176	</desc>
3177	</param>
3178	<param name="aProgress" type="IProgress" dir="return">
3179	<desc></desc>
3180	</param>
3181	</method>
3182
3183	<method name="interpret">
3184	<desc>
3185	Interprets the OVF data that was read when the appliance was constructed. After
3186	calling this method, one can inspect the
3187	<link to="#virtualSystemDescriptions" /> array attribute, which will then contain
3188	one <link to="IVirtualSystemDescription" /> for each virtual machine found in
3189	the appliance.
3190
3191	Calling this method is the second step of importing an appliance into VirtualBox;
3192	see <link to="IAppliance" /> for an overview.
3193
3194	After calling this method, one should call <link to="#getWarnings" /> to find out
3195	if problems were encountered during the processing which might later lead to
3196	errors.
3197	</desc>
3198	</method>
3199
3200	<method name="importMachines">
3201	<desc>
3202	Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
3203	and other interfaces that match the information contained in the appliance as
3204	closely as possible, as represented by the import instructions in the
3205	<link to="#virtualSystemDescriptions" /> array.
3206
3207	Calling this method is the final step of importing an appliance into VirtualBox;
3208	see <link to="IAppliance" /> for an overview.
3209
3210	Since importing the appliance will most probably involve copying and converting
3211	disk images, which can take a long time, this method operates asynchronously and
3212	returns an IProgress object to allow the caller to monitor the progress.
3213	</desc>
3214
3215	<param name="aProgress" type="IProgress" dir="return">
3216	<desc></desc>
3217	</param>
3218	</method>
3219
3220	<method name="createVFSExplorer">
3221	<desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
3222
3223	<param name="aUri" type="wstring" dir="in">
3224	<desc>The URI describing the file system to use.</desc>
3225	</param>
3226
3227	<param name="aExplorer" type="IVFSExplorer" dir="return">
3228	<desc></desc>
3229	</param>
3230	</method>
3231
3232	<method name="write">
3233	<desc>
3234	Writes the contents of the appliance exports into a new OVF file.
3235
3236	Calling this method is the final step of exporting an appliance from VirtualBox;
3237	see <link to="IAppliance" /> for an overview.
3238
3239	Since exporting the appliance will most probably involve copying and converting
3240	disk images, which can take a long time, this method operates asynchronously and
3241	returns an IProgress object to allow the caller to monitor the progress.
3242	</desc>
3243	<param name="format" type="wstring" dir="in">
3244	<desc>
3245	Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
3246	future versions of VirtualBox may support additional formats.
3247	</desc>
3248	</param>
3249	<param name="path" type="wstring" dir="in">
3250	<desc>
3251	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3252	on whether the appliance is distributed as a set of files or as a single file, respectively).
3253	</desc>
3254	</param>
3255	<param name="aProgress" type="IProgress" dir="return">
3256	<desc>Progress object to track the operation completion.</desc>
3257	</param>
3258	</method>
3259
3260	<method name="getWarnings">
3261	<desc>Returns textual warnings which occured during execution of <link to="#interpret" />.</desc>
3262
3263	<param name="aWarnings" type="wstring" dir="return" safearray="yes">
3264	<desc></desc>
3265	</param>
3266	</method>
3267
3268	</interface>
3269
3270	<enum
3271	name="VirtualSystemDescriptionType"
3272	uuid="aacc58de-5b45-4f82-ae2e-dd9a824fc3b5"
3273	>
3274	<desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
3275	a configuration value.</desc>
3276
3277	<const name="Ignore" value="1" />
3278	<const name="OS" value="2" />
3279	<const name="Name" value="3" />
3280	<const name="Product" value="4" />
3281	<const name="Vendor" value="5" />
3282	<const name="Version" value="6" />
3283	<const name="ProductUrl" value="7" />
3284	<const name="VendorUrl" value="8" />
3285	<const name="Description" value="9" />
3286	<const name="License" value="10" />
3287	<const name="Miscellaneous" value="11" />
3288	<const name="CPU" value="12" />
3289	<const name="Memory" value="13" />
3290	<const name="HardDiskControllerIDE" value="14" />
3291	<const name="HardDiskControllerSATA" value="15" />
3292	<const name="HardDiskControllerSCSI" value="16" />
3293	<const name="HardDiskImage" value="17" />
3294	<const name="Floppy" value="18" />
3295	<const name="CDROM" value="19" />
3296	<const name="NetworkAdapter" value="20" />
3297	<const name="USBController" value="21" />
3298	<const name="SoundCard" value="22" />
3299
3300	</enum>
3301
3302	<enum
3303	name="VirtualSystemDescriptionValueType"
3304	uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
3305	>
3306	<desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
3307	type to fetch.</desc>
3308
3309	<const name="Reference" value="1" />
3310	<const name="Original" value="2" />
3311	<const name="Auto" value="3" />
3312	<const name="ExtraConfig" value="4" />
3313
3314	</enum>
3315
3316	<interface
3317	name="IVirtualSystemDescription" extends="$unknown"
3318	uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
3319	wsmap="managed"
3320	>
3321
3322	<desc>This interface is used in the <link to="IAppliance::virtualSystemDescriptions" /> array.
3323	After <link to="IAppliance::interpret" /> has been called, that array contains
3324	information about how the virtual systems described in the OVF should best be imported into VirtualBox
3325	virtual machines. See <link to="IAppliance" /> for the steps required to import an OVF
3326	into VirtualBox.
3327	</desc>
3328
3329	<attribute name="count" type="unsigned long" readonly="yes">
3330	<desc>Return the number of virtual system description entries.</desc>
3331	</attribute>
3332
3333	<method name="getDescription">
3334	<desc>Returns information about the virtual system as arrays of instruction items. In each array, the
3335	items with the same indices correspond and jointly represent an import instruction for VirtualBox.
3336
3337	The list below identifies the value sets that are possible depending on the
3338	<link to="VirtualSystemDescriptionType" /> enum value in the array item in aTypes[]. In each case,
3339	the array item with the same index in aOvfValues[] will contain the original value as contained
3340	in the OVF file (just for informational purposes), and the corresponding item in aVBoxValues[]
3341	will contain a suggested value to be used for VirtualBox. Depending on the description type,
3342	the aExtraConfigValues[] array item may also be used.
3343
3344	<ul>
3345	<li>
3346	"OS": the guest operating system type. There must be exactly one such array item on import. The
3347	corresponding item in aVBoxValues[] contains the suggested guest operating system for VirtualBox.
3348	This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
3349	item in aOvfValues[] will contain a numerical value that described the operating system in the OVF.
3350	</li>
3351	<li>
3352	"Name": the name to give to the new virtual machine. There can be at most one such array item;
3353	if none is present on import, then an automatic name will be created from the operating system
3354	type. The correponding item im aOvfValues[] will contain the suggested virtual machine name
3355	from the OVF file, and aVBoxValues[] will contain a suggestion for a unique VirtualBox
3356	<link to="IMachine" /> name that does not exist yet.
3357	</li>
3358	<li>
3359	"Description": an arbitrary description.
3360	</li>
3361	<li>
3362	"License": the EULA section from the OVF, if present. It is the responsibility of the calling
3363	code to display such a license for agreement; the Main API does not enforce any such policy.
3364	</li>
3365	<li>
3366	Miscellaneous: reserved for future use.
3367	</li>
3368	<li>
3369	"CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
3370	</li>
3371	<li>
3372	"Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
3373	is present on import, then VirtualBox will set a meaningful default based on the operating system
3374	type.
3375	</li>
3376	<li>
3377	"HarddiskControllerIDE": an IDE hard disk controller. There can be at most one such item. This
3378	has no value in aOvfValues[] or aVBoxValues[].
3379	The matching item in the aRefs[] array will contain an integer that items of the "Harddisk"
3380	type can use to specify which hard disk controller a virtual disk should be connected to.
3381	</li>
3382	<li>
3383	"HarddiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
3384	has no value in aOvfValues[] or aVBoxValues[].
3385	The matching item in the aRefs[] array will be used as with IDE controllers (see above).
3386	</li>
3387	<li>
3388	"HarddiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
3389	The items in aOvfValues[] and aVBoxValues[] will either be "LsiLogic" or "BusLogic".
3390	The matching item in the aRefs[] array will be used as with IDE controllers (see above).
3391	</li>
3392	<li>
3393	"HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
3394	arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
3395
3396	The array item in aOvfValues[] will contain the file specification from the OVF file (without
3397	a path since the image file should be in the same location as the OVF file itself), whereas the
3398	item in aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
3399	hard disk image. This means that on import the image will be copied and converted from the
3400	"ovf" location to the "vbox" location; on export, this will be handled the other way round.
3401	On import, the target image will also be registered with VirtualBox.
3402
3403	The matching item in the aExtraConfigValues[] array must contain a string of the following
3404	format: "controller=<index>;channel=<c>"
3405	In this string, <index> must be an integer specifying the hard disk controller to connect
3406	the image to. That number must be the index of an array item with one of the hard disk controller
3407	types (HarddiskControllerSCSI, HarddiskControllerSATA, HarddiskControllerIDE).
3408	In addition, <c> must specify the channel to use on that controller. For IDE controllers,
3409	this can range from 0-3 (which VirtualBox will interpret as primary master, primary slave, secondary master and
3410	secondary slave. For SATA and SCSI controllers, the channel can range from 0-29.
3411	</li>
3412	<li>
3413	"NetworkAdapter": a network adapter. The array item in aVBoxValues[] will specify the hardware
3414	for the network adapter, whereas the array item in aExtraConfigValues[] will have a string
3415	of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
3416	</li>
3417	<li>
3418	"USBController": a USB controller. There can be at most one such item. If and only if such an
3419	item ispresent, USB support will be enabled for the new virtual machine.
3420	</li>
3421	<li>
3422	"SoundCard": a sound card. There can be at most one such item. If and only if such an item is
3423	present, sound support will be enabled for the new virtual machine. Note that the virtual
3424	machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
3425	may be different from the virtual soundcard expected by the appliance.
3426	</li>
3427	</ul>
3428
3429	</desc>
3430
3431	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3432	<desc></desc>
3433	</param>
3434
3435	<param name="aRefs" type="wstring" dir="out" safearray="yes">
3436	<desc></desc>
3437	</param>
3438
3439	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3440	<desc></desc>
3441	</param>
3442
3443	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
3444	<desc></desc>
3445	</param>
3446
3447	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3448	<desc></desc>
3449	</param>
3450
3451	</method>
3452
3453	<method name="getDescriptionByType">
3454	<desc>This is the same as <link to="#getDescription" /> except that you can specify which types
3455	should be returned.</desc>
3456
3457	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3458	<desc></desc>
3459	</param>
3460
3461	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3462	<desc></desc>
3463	</param>
3464
3465	<param name="aRefs" type="wstring" dir="out" safearray="yes">
3466	<desc></desc>
3467	</param>
3468
3469	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3470	<desc></desc>
3471	</param>
3472
3473	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
3474	<desc></desc>
3475	</param>
3476
3477	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3478	<desc></desc>
3479	</param>
3480
3481	</method>
3482
3483	<method name="getValuesByType">
3484	<desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
3485	value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
3486	values.</desc>
3487
3488	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3489	<desc></desc>
3490	</param>
3491
3492	<param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
3493	<desc></desc>
3494	</param>
3495
3496	<param name="aValues" type="wstring" dir="return" safearray="yes">
3497	<desc></desc>
3498	</param>
3499
3500	</method>
3501
3502	<method name="setFinalValues">
3503	<desc>
3504	This method allows the appliance's user to change the configuration for the virtual
3505	system descriptions. For each array item returned from <link to="#getDescription" />,
3506	you must pass in one boolean value and one configuration value.
3507
3508	Each item in the boolean array determines whether the particular configuration item
3509	should be enabled.
3510	You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
3511	HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
3512	and SoundCard.
3513
3514	For the "vbox" and "extra configuration" values, if you pass in the same arrays
3515	as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription(),
3516	the configuration remains unchanged. Please see the documentation for getDescription()
3517	for valid configuration values for the individual array item types. If the
3518	corresponding item in the aEnabled array is @c false, the configuration value is ignored.
3519	</desc>
3520
3521	<param name="aEnabled" type="boolean" dir="in" safearray="yes">
3522	<desc></desc>
3523	</param>
3524
3525	<param name="aVBoxValues" type="wstring" dir="in" safearray="yes">
3526	<desc></desc>
3527	</param>
3528
3529	<param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
3530	<desc></desc>
3531	</param>
3532	</method>
3533
3534	<method name="addDescription">
3535	<desc>
3536	This method adds an additional description entry to the stack of already
3537	available descriptions for this virtual system. This is handy for writing
3538	values which aren't directly supported by VirtualBox. One example would
3539	be the License type of <link to="VirtualSystemDescriptionType" />.
3540	</desc>
3541
3542	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3543	<desc></desc>
3544	</param>
3545
3546	<param name="aVBoxValue" type="wstring" dir="in">
3547	<desc></desc>
3548	</param>
3549
3550	<param name="aExtraConfigValue" type="wstring" dir="in">
3551	<desc></desc>
3552	</param>
3553	</method>
3554	</interface>
3555
3556
3557	<!--
3558	// IMachine
3559	/////////////////////////////////////////////////////////////////////////
3560	-->
3561
3562	<interface
3563	name="IInternalMachineControl" extends="$unknown"
3564	uuid="6c08103e-b8e6-44fb-bc6c-36067153d4bd"
3565	internal="yes"
3566	wsmap="suppress"
3567	>
3568	<method name="setRemoveSavedState">
3569	<desc>
3570	Updates the flag whether saved state is removed on a machine state
3571	change from Saved to PoweredOff.
3572	</desc>
3573	<param name="aRemove" type="boolean" dir="in"/>
3574	</method>
3575
3576	<method name="updateState">
3577	<desc>
3578	Updates the VM state.
3579	<note>
3580	This operation will also update the settings file with
3581	the correct information about the saved state file
3582	and delete this file from disk when appropriate.
3583	</note>
3584	</desc>
3585	<param name="state" type="MachineState" dir="in"/>
3586	</method>
3587
3588	<method name="getIPCId">
3589	<param name="id" type="wstring" dir="return"/>
3590	</method>
3591
3592	<method name="runUSBDeviceFilters">
3593	<desc>
3594	Asks the server to run USB devices filters of the associated
3595	machine against the given USB device and tell if there is
3596	a match.
3597	<note>
3598	Intended to be used only for remote USB devices. Local
3599	ones don't require to call this method (this is done
3600	implicitly by the Host and USBProxyService).
3601	</note>
3602	</desc>
3603	<param name="device" type="IUSBDevice" dir="in"/>
3604	<param name="matched" type="boolean" dir="out"/>
3605	<param name="maskedInterfaces" type="unsigned long" dir="out"/>
3606	</method>
3607
3608	<method name="captureUSBDevice">
3609	<desc>
3610	Requests a capture of the given host USB device.
3611	When the request is completed, the VM process will
3612	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3613	notification.
3614	</desc>
3615	<param name="id" type="uuid" mod="string" dir="in"/>
3616	</method>
3617
3618	<method name="detachUSBDevice">
3619	<desc>
3620	Notification that a VM is going to detach (@a done = @c false) or has
3621	already detached (@a done = @c true) the given USB device.
3622	When the @a done = @c true request is completed, the VM process will
3623	get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3624	notification.
3625	<note>
3626	In the @a done = @c true case, the server must run its own filters
3627	and filters of all VMs but this one on the detached device
3628	as if it were just attached to the host computer.
3629	</note>
3630	</desc>
3631	<param name="id" type="uuid" mod="string" dir="in"/>
3632	<param name="done" type="boolean" dir="in"/>
3633	</method>
3634
3635	<method name="autoCaptureUSBDevices">
3636	<desc>
3637	Requests a capture all matching USB devices attached to the host.
3638	When the request is completed, the VM process will
3639	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3640	notification per every captured device.
3641	</desc>
3642	</method>
3643
3644	<method name="detachAllUSBDevices">
3645	<desc>
3646	Notification that a VM that is being powered down. The done
3647	parameter indicates whether which stage of the power down
3648	we're at. When @a done = @c false the VM is announcing its
3649	intentions, while when @a done = @c true the VM is reporting
3650	what it has done.
3651	<note>
3652	In the @a done = @c true case, the server must run its own filters
3653	and filters of all VMs but this one on all detach devices as
3654	if they were just attached to the host computer.
3655	</note>
3656	</desc>
3657	<param name="done" type="boolean" dir="in"/>
3658	</method>
3659
3660	<method name="onSessionEnd">
3661	<desc>
3662	Triggered by the given session object when the session is about
3663	to close normally.
3664	</desc>
3665	<param name="session" type="ISession" dir="in">
3666	<desc>Session that is being closed</desc>
3667	</param>
3668	<param name="progress" type="IProgress" dir="return">
3669	<desc>
3670	Used to wait until the corresponding machine is actually
3671	dissociated from the given session on the server.
3672	Returned only when this session is a direct one.
3673	</desc>
3674	</param>
3675	</method>
3676
3677	<method name="beginSavingState">
3678	<desc>
3679	Called by the VM process to inform the server it wants to
3680	save the current state and stop the VM execution.
3681	</desc>
3682	<param name="progress" type="IProgress" dir="in">
3683	<desc>
3684	Progress object created by the VM process to wait until
3685	the state is saved.
3686	</desc>
3687	</param>
3688	<param name="stateFilePath" type="wstring" dir="out">
3689	<desc>
3690	File path the VM process must save the execution state to.
3691	</desc>
3692	</param>
3693	</method>
3694
3695	<method name="endSavingState">
3696	<desc>
3697	Called by the VM process to inform the server that saving
3698	the state previously requested by #beginSavingState is either
3699	successfully finished or there was a failure.
3700
3701	<result name="VBOX_E_FILE_ERROR">
3702	Settings file not accessible.
3703	</result>
3704	<result name="VBOX_E_XML_ERROR">
3705	Could not parse the settings file.
3706	</result>
3707
3708	</desc>
3709
3710	<param name="success" type="boolean" dir="in">
3711	<desc>@c true to indicate success and @c false otherwise.
3712	</desc>
3713	</param>
3714	</method>
3715
3716	<method name="adoptSavedState">
3717	<desc>
3718	Gets called by IConsole::adoptSavedState.
3719	<result name="VBOX_E_FILE_ERROR">
3720	Invalid saved state file path.
3721	</result>
3722	</desc>
3723	<param name="savedStateFile" type="wstring" dir="in">
3724	<desc>Path to the saved state file to adopt.</desc>
3725	</param>
3726	</method>
3727
3728	<method name="beginTakingSnapshot">
3729	<desc>
3730	Called from the VM process to request from the server to perform the
3731	server-side actions of creating a snapshot (creating differencing images
3732	and the snapshot object).
3733
3734	<result name="VBOX_E_FILE_ERROR">
3735	Settings file not accessible.
3736	</result>
3737	<result name="VBOX_E_XML_ERROR">
3738	Could not parse the settings file.
3739	</result>
3740	</desc>
3741	<param name="initiator" type="IConsole" dir="in">
3742	<desc>The console object that initiated this call.</desc>
3743	</param>
3744	<param name="name" type="wstring" dir="in">
3745	<desc>Snapshot name.</desc>
3746	</param>
3747	<param name="description" type="wstring" dir="in">
3748	<desc>Snapshot description.</desc>
3749	</param>
3750	<param name="consoleProgress" type="IProgress" dir="in">
3751	<desc>
3752	Progress object created by the VM process tracking the
3753	snapshot's progress. This has the following sub-operations:
3754	<ul>
3755	<li>setting up (weight 1);</li>
3756	<li>one for each hard disk attachment that needs a differencing image (weight 1 each);</li>
3757	<li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
3758	<li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
3759	<li>finishing up (weight 1)</li>
3760	</ul>
3761	</desc>
3762	</param>
3763	<param name="fTakingSnapshotOnline" type="boolean" dir="in">
3764	<desc>
3765	Whether this is an online snapshot (i.e. the machine is running).
3766	</desc>
3767	</param>
3768	<param name="stateFilePath" type="wstring" dir="out">
3769	<desc>
3770	File path the VM process must save the execution state to.
3771	</desc>
3772	</param>
3773	</method>
3774
3775	<method name="endTakingSnapshot">
3776	<desc>
3777	Called by the VM process to inform the server that the snapshot
3778	previously requested by #beginTakingSnapshot is either
3779	successfully taken or there was a failure.
3780	</desc>
3781
3782	<param name="success" type="boolean" dir="in">
3783	<desc>@c true to indicate success and @c false otherwise</desc>
3784	</param>
3785	</method>
3786
3787	<method name="discardSnapshot">
3788	<desc>
3789	Gets called by IConsole::discardSnapshot.
3790	<result name="VBOX_E_INVALID_OBJECT_STATE">
3791	Snapshot has more than one child snapshot.
3792	</result>
3793	</desc>
3794	<param name="initiator" type="IConsole" dir="in">
3795	<desc>The console object that initiated this call.</desc>
3796	</param>
3797	<param name="id" type="uuid" mod="string" dir="in">
3798	<desc>UUID of the snapshot to discard.</desc>
3799	</param>
3800	<param name="machineState" type="MachineState" dir="out">
3801	<desc>New machine state after this operation is started.</desc>
3802	</param>
3803	<param name="progress" type="IProgress" dir="return">
3804	<desc>Progress object to track the operation completion.</desc>
3805	</param>
3806	</method>
3807
3808	<method name="discardCurrentState">
3809	<desc>
3810	Gets called by IConsole::discardCurrentState.
3811	<result name="VBOX_E_INVALID_OBJECT_STATE">
3812	Virtual machine does not have any snapshot.
3813	</result>
3814	</desc>
3815	<param name="initiator" type="IConsole" dir="in">
3816	<desc>The console object that initiated this call.</desc>
3817	</param>
3818	<param name="machineState" type="MachineState" dir="out">
3819	<desc>New machine state after this operation is started.</desc>
3820	</param>
3821	<param name="progress" type="IProgress" dir="return">
3822	<desc>Progress object to track the operation completion.</desc>
3823	</param>
3824	</method>
3825
3826	<method name="discardCurrentSnapshotAndState">
3827	<desc>
3828	Gets called by IConsole::discardCurrentSnapshotAndState.
3829	<result name="VBOX_E_INVALID_OBJECT_STATE">
3830	Virtual machine does not have any snapshot.
3831	</result>
3832	</desc>
3833	<param name="initiator" type="IConsole" dir="in">
3834	<desc>The console object that initiated this call.</desc>
3835	</param>
3836	<param name="machineState" type="MachineState" dir="out">
3837	<desc>New machine state after this operation is started.</desc>
3838	</param>
3839	<param name="progress" type="IProgress" dir="return">
3840	<desc>Progress object to track the operation completion.</desc>
3841	</param>
3842	</method>
3843
3844	<method name="pullGuestProperties">
3845	<desc>
3846	Get the list of the guest properties matching a set of patterns along
3847	with their values, time stamps and flags and give responsibility for
3848	managing properties to the console.
3849	</desc>
3850	<param name="name" type="wstring" dir="out" safearray="yes">
3851	<desc>
3852	The names of the properties returned.
3853	</desc>
3854	</param>
3855	<param name="value" type="wstring" dir="out" safearray="yes">
3856	<desc>
3857	The values of the properties returned. The array entries match the
3858	corresponding entries in the @a name array.
3859	</desc>
3860	</param>
3861	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
3862	<desc>
3863	The time stamps of the properties returned. The array entries match
3864	the corresponding entries in the @a name array.
3865	</desc>
3866	</param>
3867	<param name="flags" type="wstring" dir="out" safearray="yes">
3868	<desc>
3869	The flags of the properties returned. The array entries match the
3870	corresponding entries in the @a name array.
3871	</desc>
3872	</param>
3873	</method>
3874
3875	<method name="pushGuestProperties">
3876	<desc>
3877	Set the list of the guest properties matching a set of patterns along
3878	with their values, time stamps and flags and return responsibility for
3879	managing properties to IMachine.
3880	</desc>
3881	<param name="name" type="wstring" dir="in" safearray="yes">
3882	<desc>
3883	The names of the properties.
3884	</desc>
3885	</param>
3886	<param name="value" type="wstring" dir="in" safearray="yes">
3887	<desc>
3888	The values of the properties. The array entries match the
3889	corresponding entries in the @a name array.
3890	</desc>
3891	</param>
3892	<param name="timestamp" type="unsigned long long" dir="in" safearray="yes">
3893	<desc>
3894	The time stamps of the properties. The array entries match
3895	the corresponding entries in the @a name array.
3896	</desc>
3897	</param>
3898	<param name="flags" type="wstring" dir="in" safearray="yes">
3899	<desc>
3900	The flags of the properties. The array entries match the
3901	corresponding entries in the @a name array.
3902	</desc>
3903	</param>
3904	</method>
3905	<method name="pushGuestProperty">
3906	<desc>
3907	Update a single guest property in IMachine.
3908	</desc>
3909	<param name="name" type="wstring" dir="in">
3910	<desc>
3911	The name of the property to be updated.
3912	</desc>
3913	</param>
3914	<param name="value" type="wstring" dir="in">
3915	<desc>
3916	The value of the property.
3917	</desc>
3918	</param>
3919	<param name="timestamp" type="unsigned long long" dir="in">
3920	<desc>
3921	The timestamp of the property.
3922	</desc>
3923	</param>
3924	<param name="flags" type="wstring" dir="in">
3925	<desc>
3926	The flags of the property.
3927	</desc>
3928	</param>
3929	</method>
3930
3931	<method name="lockMedia">
3932	<desc>
3933	Locks all media attached to the machine for writing and parents of
3934	attached differencing media (if any) for reading. This operation is
3935	atomic so that if it fails no media is actually locked.
3936
3937	This method is intended to be called when the machine is in Starting or
3938	Restoring state. The locked media will be automatically unlocked when
3939	the machine is powered off or crashed.
3940	</desc>
3941	</method>
3942	</interface>
3943
3944	<interface
3945	name="IBIOSSettings" extends="$unknown"
3946	uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
3947	wsmap="managed"
3948	>
3949	<desc>
3950	The IBIOSSettings interface represents BIOS settings of the virtual
3951	machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
3952	</desc>
3953	<attribute name="logoFadeIn" type="boolean">
3954	<desc>Fade in flag for BIOS logo animation.</desc>
3955	</attribute>
3956
3957	<attribute name="logoFadeOut" type="boolean">
3958	<desc>Fade out flag for BIOS logo animation.</desc>
3959	</attribute>
3960
3961	<attribute name="logoDisplayTime" type="unsigned long">
3962	<desc>BIOS logo display time in milliseconds (0 = default).</desc>
3963	</attribute>
3964
3965	<attribute name="logoImagePath" type="wstring">
3966	<desc>Local file system path for external BIOS image.</desc>
3967	</attribute>
3968
3969	<attribute name="bootMenuMode" type="BIOSBootMenuMode">
3970	<desc>Mode of the BIOS boot device menu.</desc>
3971	</attribute>
3972
3973	<attribute name="ACPIEnabled" type="boolean">
3974	<desc>ACPI support flag.</desc>
3975	</attribute>
3976
3977	<attribute name="IOAPICEnabled" type="boolean">
3978	<desc>
3979	IO APIC support flag. If set, VirtualBox will provide an IO APIC
3980	and support IRQs above 15.
3981	</desc>
3982	</attribute>
3983
3984	<attribute name="timeOffset" type="long long">
3985	<desc>
3986	Offset in milliseconds from the host system time. This allows for
3987	guests running with a different system date/time than the host.
3988	It is equivalent to setting the system date/time in the BIOS except
3989	it is not an absolute value but a relative one. Guest Additions
3990	time synchronization honors this offset.
3991	</desc>
3992	</attribute>
3993
3994	<attribute name="PXEDebugEnabled" type="boolean">
3995	<desc>
3996	PXE debug logging flag. If set, VirtualBox will write extensive
3997	PXE trace information to the release log.
3998	</desc>
3999	</attribute>
4000
4001	</interface>
4002
4003	<interface
4004	name="IMachine" extends="$unknown"
4005	uuid="160b0ccc-c3d6-4c1b-bbe9-39b1a732f833"
4006	wsmap="managed"
4007	>
4008	<desc>
4009	The IMachine interface represents a virtual machine, or guest, created
4010	in VirtualBox.
4011
4012	This interface is used in two contexts. First of all, a collection of
4013	objects implementing this interface is stored in the
4014	<link to="IVirtualBox::machines"/> attribute which lists all the virtual
4015	machines that are currently registered with this VirtualBox
4016	installation. Also, once a session has been opened for the given virtual
4017	machine (e.g. the virtual machine is running), the machine object
4018	associated with the open session can be queried from the session object;
4019	see <link to="ISession"/> for details.
4020
4021	The main role of this interface is to expose the settings of the virtual
4022	machine and provide methods to change various aspects of the virtual
4023	machine's configuration. For machine objects stored in the
4024	<link to="IVirtualBox::machines"/> collection, all attributes are
4025	read-only unless explicitly stated otherwise in individual attribute
4026	and method descriptions. In order to change a machine setting, a session
4027	for this machine must be opened using one of
4028	<link to="IVirtualBox::openSession"/>,
4029	<link to="IVirtualBox::openRemoteSession"/> or
4030	<link to="IVirtualBox::openExistingSession"/> methods. After the
4031	session has been successfully opened, a mutable machine object needs to
4032	be queried from the session object and then the desired settings changes
4033	can be applied to the returned object using IMachine attributes and
4034	methods. See the <link to="ISession"/> interface description for more
4035	information about sessions.
4036
4037	Note that IMachine does not provide methods to control virtual machine
4038	execution (such as start the machine, or power it down) -- these methods
4039	are grouped in a separate interface called <link to="IConsole" />.
4040
4041	<see>ISession, IConsole</see>
4042	</desc>
4043
4044	<attribute name="parent" type="IVirtualBox" readonly="yes">
4045	<desc>Associated parent object.</desc>
4046	</attribute>
4047
4048	<attribute name="accessible" type="boolean" readonly="yes">
4049	<desc>
4050	Whether this virtual machine is currently accessible or not.
4051
4052	A machine is always deemed accessible unless it is registered <i>and</i>
4053	its settings file cannot be read or parsed (either because the file itself
4054	is unavailable or has invalid XML contents).
4055
4056	Every time this property is read, the accessibility state of
4057	this machine is re-evaluated. If the returned value is @c false,
4058	the <link to="#accessError"/> property may be used to get the
4059	detailed error information describing the reason of
4060	inaccessibility, including XML error messages.
4061
4062	When the machine is inaccessible, only the following properties
4063	can be used on it:
4064	<ul>
4065	<li><link to="#parent"/></li>
4066	<li><link to="#id"/></li>
4067	<li><link to="#settingsFilePath"/></li>
4068	<li><link to="#accessible"/></li>
4069	<li><link to="#accessError"/></li>
4070	</ul>
4071
4072	An attempt to access any other property or method will return
4073	an error.
4074
4075	The only possible action you can perform on an inaccessible
4076	machine is to unregister it using the
4077	<link to="IVirtualBox::unregisterMachine"/> call (or, to check
4078	for the accessibility state once more by querying this
4079	property).
4080
4081	<note>
4082	In the current implementation, once this property returns
4083	@c true, the machine will never become inaccessible
4084	later, even if its settings file cannot be successfully
4085	read/written any more (at least, until the VirtualBox
4086	server is restarted). This limitation may be removed in
4087	future releases.
4088	</note>
4089	</desc>
4090	</attribute>
4091
4092	<attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
4093	<desc>
4094	Error information describing the reason of machine
4095	inaccessibility.
4096
4097	Reading this property is only valid after the last call to
4098	<link to="#accessible"/> returned @c false (i.e. the
4099	machine is currently unaccessible). Otherwise, a @c null
4100	IVirtualBoxErrorInfo object will be returned.
4101	</desc>
4102	</attribute>
4103
4104	<attribute name="name" type="wstring">
4105	<desc>
4106	Name of the virtual machine.
4107
4108	Besides being used for human-readable identification purposes
4109	everywhere in VirtualBox, the virtual machine name is also used
4110	as a name of the machine's settings file and as a name of the
4111	subdirectory this settings file resides in. Thus, every time you
4112	change the value of this property, the settings file will be
4113	renamed once you call <link to="#saveSettings"/> to confirm the
4114	change. The containing subdirectory will be also renamed, but
4115	only if it has exactly the same name as the settings file
4116	itself prior to changing this property (for backward compatibility
4117	with previous API releases). The above implies the following
4118	limitations:
4119	<ul>
4120	<li>The machine name cannot be empty.</li>
4121	<li>The machine name can contain only characters that are valid
4122	file name characters according to the rules of the file
4123	system used to store VirtualBox configuration.</li>
4124	<li>You cannot have two or more machines with the same name
4125	if they use the same subdirectory for storing the machine
4126	settings files.</li>
4127	<li>You cannot change the name of the machine if it is running,
4128	or if any file in the directory containing the settings file
4129	is being used by another running machine or by any other
4130	process in the host operating system at a time when
4131	<link to="#saveSettings"/> is called.
4132	</li>
4133	</ul>
4134	If any of the above limitations are hit, <link to="#saveSettings"/>
4135	will return an appropriate error message explaining the exact
4136	reason and the changes you made to this machine will not be
4137	saved.
4138	<note>
4139	For "legacy" machines created using the
4140	<link to="IVirtualBox::createLegacyMachine"/> call,
4141	the above naming limitations do not apply because the
4142	machine name does not affect the settings file name.
4143	The settings file name remains the same as it was specified
4144	during machine creation and never changes.
4145	</note>
4146	</desc>
4147	</attribute>
4148
4149	<attribute name="description" type="wstring">
4150	<desc>
4151	Description of the virtual machine.
4152
4153	The description attribute can contain any text and is
4154	typically used to describe the hardware and software
4155	configuration of the virtual machine in detail (i.e. network
4156	settings, versions of the installed software and so on).
4157	</desc>
4158	</attribute>
4159
4160	<attribute name="id" type="uuid" mod="string" readonly="yes">
4161	<desc>UUID of the virtual machine.</desc>
4162	</attribute>
4163
4164	<attribute name="OSTypeId" type="wstring">
4165	<desc>
4166	User-defined identifier of the Guest OS type.
4167	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
4168	an IGuestOSType object representing details about the given
4169	Guest OS type.
4170	<note>
4171	This value may differ from the value returned by
4172	<link to="IGuest::OSTypeId"/> if Guest Additions are
4173	installed to the guest OS.
4174	</note>
4175	</desc>
4176	</attribute>
4177
4178	<attribute name="HardwareVersion" type="wstring">
4179	<desc>Hardware version identifier. Internal use only for now.</desc>
4180	</attribute>
4181
4182	<attribute name="CPUCount" type="unsigned long">
4183	<desc>Number of virtual CPUs in the VM.</desc>
4184	</attribute>
4185
4186	<attribute name="memorySize" type="unsigned long">
4187	<desc>System memory size in megabytes.</desc>
4188	</attribute>
4189
4190	<attribute name="memoryBalloonSize" type="unsigned long">
4191	<desc>Initial memory balloon size in megabytes.</desc>
4192	</attribute>
4193
4194	<attribute name="statisticsUpdateInterval" type="unsigned long">
4195	<desc>Initial interval to update guest statistics in seconds.</desc>
4196	</attribute>
4197
4198	<attribute name="VRAMSize" type="unsigned long">
4199	<desc>Video memory size in megabytes.</desc>
4200	</attribute>
4201
4202	<attribute name="accelerate3DEnabled" type="boolean" default="false">
4203	<desc>
4204	This setting determines whether VirtualBox allows this machine to make
4205	use of the 3D graphics support available on the host.</desc>
4206	</attribute>
4207
4208	<attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
4209	<desc>
4210	This setting determines whether VirtualBox allows this machine to make
4211	use of the 2D video acceleration support available on the host.</desc>
4212	</attribute>
4213
4214	<attribute name="monitorCount" type="unsigned long">
4215	<desc>
4216	Number of virtual monitors.
4217	<note>
4218	Only effective on Windows XP and later guests with
4219	Guest Additions installed.
4220	</note>
4221	</desc>
4222	</attribute>
4223
4224	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
4225	<desc>Object containing all BIOS settings.</desc>
4226	</attribute>
4227
4228	<attribute name="firmwareType" type="FirmwareType">
4229	<desc>Type of firmware (such as legacy BIOS or EFI), used for initial
4230	bootstrap in this VM.</desc>
4231	</attribute>
4232
4233	<attribute name="HWVirtExEnabled" type="boolean">
4234	<desc>
4235	This setting determines whether VirtualBox will try to make use of
4236	the host CPU's hardware virtualization extensions such as Intel VT-x
4237	and AMD-V. Note that in case such extensions are not available,
4238	they will not be used.
4239	</desc>
4240	</attribute>
4241
4242	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" default="false">
4243	<desc>
4244	This setting determines whether VirtualBox will try to make use of
4245	the nested paging extension of Intel VT-x and AMD-V. Note that in case
4246	such extensions are not available, they will not be used.
4247	</desc>
4248	</attribute>
4249
4250	<attribute name="HWVirtExVPIDEnabled" type="boolean" default="false">
4251	<desc>
4252	This setting determines whether VirtualBox will try to make use of
4253	the VPID extension of Intel VT-x. Note that in case such extensions are
4254	not available, they will not be used.
4255	</desc>
4256	</attribute>
4257
4258	<attribute name="PAEEnabled" type="boolean" default="false">
4259	<desc>
4260	This setting determines whether VirtualBox will expose the Physical Address
4261	Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
4262	is not available, it will not be reported.
4263	</desc>
4264	</attribute>
4265
4266	<attribute name="snapshotFolder" type="wstring">
4267	<desc>
4268	Full path to the directory used to store snapshot data
4269	(differencing media and saved state files) of this machine.
4270
4271	The initial value of this property is
4272	<tt><</tt><link to="#settingsFilePath">
4273	path_to_settings_file</link><tt>>/<</tt>
4274	<link to="#id">machine_uuid</link>
4275	<tt>></tt>.
4276
4277	Currently, it is an error to try to change this property on
4278	a machine that has snapshots (because this would require to
4279	move possibly large files to a different location).
4280	A separate method will be available for this purpose later.
4281
4282	<note>
4283	Setting this property to @c null or to an empty string will restore
4284	the initial value.
4285	</note>
4286	<note>
4287	When setting this property, the specified path can be
4288	absolute (full path) or relative to the directory where the
4289	<link to="#settingsFilePath">machine settings file</link>
4290	is located. When reading this property, a full path is
4291	always returned.
4292	</note>
4293	<note>
4294	The specified path may not exist, it will be created
4295	when necessary.
4296	</note>
4297	</desc>
4298	</attribute>
4299
4300	<attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
4301	<desc>VRDP server object.</desc>
4302	</attribute>
4303
4304	<attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
4305	<desc>Array of media attached to this machine.</desc>
4306	</attribute>
4307
4308	<attribute name="USBController" type="IUSBController" readonly="yes">
4309	<desc>
4310	Associated USB controller object.
4311
4312	<note>
4313	If USB functionality is not available in the given edition of
4314	VirtualBox, this method will set the result code to @c E_NOTIMPL.
4315	</note>
4316	</desc>
4317	</attribute>
4318
4319	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
4320	<desc>Associated audio adapter, always present.</desc>
4321	</attribute>
4322
4323	<attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
4324	<desc>Array of storage controllers attached to this machine.</desc>
4325	</attribute>
4326
4327	<attribute name="settingsFilePath" type="wstring" readonly="yes">
4328	<desc>
4329	Full name of the file containing machine settings data.
4330	</desc>
4331	</attribute>
4332
4333	<attribute name="settingsModified" type="boolean" readonly="yes">
4334	<desc>
4335	Whether the settings of this machine have been modified
4336	(but neither yet saved nor discarded).
4337	<note>
4338	Reading this property is only valid on instances returned
4339	by <link to="ISession::machine"/> and on new machines
4340	created by <link to="IVirtualBox::createMachine"/> or opened
4341	by <link to="IVirtualBox::openMachine"/> but not
4342	yet registered, or on unregistered machines after calling
4343	<link to="IVirtualBox::unregisterMachine"/>. For all other
4344	cases, the settings can never be modified.
4345	</note>
4346	<note>
4347	For newly created unregistered machines, the value of this
4348	property is always @c true until <link to="#saveSettings"/>
4349	is called (no matter if any machine settings have been
4350	changed after the creation or not). For opened machines
4351	the value is set to @c false (and then follows to normal rules).
4352	</note>
4353	</desc>
4354	</attribute>
4355
4356	<attribute name="sessionState" type="SessionState" readonly="yes">
4357	<desc>Current session state for this machine.</desc>
4358	</attribute>
4359
4360	<attribute name="sessionType" type="wstring" readonly="yes">
4361	<desc>
4362	Type of the session. If <link to="#sessionState"/> is
4363	SessionSpawning or SessionOpen, this attribute contains the
4364	same value as passed to the
4365	<link to="IVirtualBox::openRemoteSession"/> method in the
4366	@a type parameter. If the session was opened directly using
4367	<link to="IVirtualBox::openSession"/>, or if
4368	<link to="#sessionState"/> is SessionClosed, the value of this
4369	attribute is an empty string.
4370	</desc>
4371	</attribute>
4372
4373	<attribute name="sessionPid" type="unsigned long" readonly="yes">
4374	<desc>
4375	Identifier of the session process. This attribute contains the
4376	platform-dependent identifier of the process that has opened a
4377	direct session for this machine using the
4378	<link to="IVirtualBox::openSession"/> call. The returned value
4379	is only valid if <link to="#sessionState"/> is SessionOpen or
4380	SessionClosing (i.e. a session is currently open or being
4381	closed) by the time this property is read.
4382	</desc>
4383	</attribute>
4384
4385	<attribute name="state" type="MachineState" readonly="yes">
4386	<desc>Current execution state of this machine.</desc>
4387	</attribute>
4388
4389	<attribute name="lastStateChange" type="long long" readonly="yes">
4390	<desc>
4391	Time stamp of the last execution state change,
4392	in milliseconds since 1970-01-01 UTC.
4393	</desc>
4394	</attribute>
4395
4396	<attribute name="stateFilePath" type="wstring" readonly="yes">
4397	<desc>
4398	Full path to the file that stores the execution state of
4399	the machine when it is in the <link to="MachineState_Saved"/> state.
4400	<note>
4401	When the machine is not in the Saved state, this attribute is
4402	an empty string.
4403	</note>
4404	</desc>
4405	</attribute>
4406
4407	<attribute name="logFolder" type="wstring" readonly="yes">
4408	<desc>
4409	Full path to the folder that stores a set of rotated log files
4410	recorded during machine execution. The most recent log file is
4411	named <tt>VBox.log</tt>, the previous log file is
4412	named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4413	in the current version).
4414	</desc>
4415	</attribute>
4416
4417	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4418	<desc>
4419	Current snapshot of this machine. This is @c null if the machine
4420	currently has no snapshots. Otherwise, this is always the last snapshot
4421	in the current implementation; see <link to="ISnapshot"/> for details.
4422	</desc>
4423	</attribute>
4424
4425	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
4426	<desc>
4427	Number of snapshots taken on this machine. Zero means the
4428	machine doesn't have any snapshots.
4429	</desc>
4430	</attribute>
4431
4432	<attribute name="currentStateModified" type="boolean" readonly="yes">
4433	<desc>
4434	Returns @c true if the current state of the machine is not
4435	identical to the state stored in the current snapshot.
4436
4437	The current state is identical to the current snapshot right
4438	after one of the following calls are made:
4439	<ul>
4440	<li><link to="IConsole::discardCurrentState"/> or
4441	<link to="IConsole::discardCurrentSnapshotAndState"/>
4442	</li>
4443	<li><link to="IConsole::takeSnapshot"/> (issued on a
4444	powered off or saved machine, for which
4445	<link to="#settingsModified"/> returns @c false)
4446	</li>
4447	<li><link to="IMachine::setCurrentSnapshot"/>
4448	</li>
4449	</ul>
4450
4451	The current state remains identical until one of the following
4452	happens:
4453	<ul>
4454	<li>settings of the machine are changed</li>
4455	<li>the saved state is discarded</li>
4456	<li>the current snapshot is discarded</li>
4457	<li>an attempt to execute the machine is made</li>
4458	</ul>
4459
4460	<note>
4461	For machines that don't have snapshots, this property is
4462	always @c false.
4463	</note>
4464	</desc>
4465	</attribute>
4466
4467	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4468	<desc>
4469	Collection of shared folders for this machine (permanent shared
4470	folders). These folders are shared automatically at machine startup
4471	and available only to the guest OS installed within this machine.
4472
4473	New shared folders are added to the collection using
4474	<link to="#createSharedFolder"/>. Existing shared folders can be
4475	removed using <link to="#removeSharedFolder"/>.
4476	</desc>
4477	</attribute>
4478
4479	<attribute name="clipboardMode" type="ClipboardMode">
4480	<desc>
4481	Synchronization mode between the host OS clipboard
4482	and the guest OS clipboard.
4483	</desc>
4484	</attribute>
4485
4486	<attribute name="guestPropertyNotificationPatterns" type="wstring">
4487	<desc>
4488	A comma-separated list of simple glob patterns. Changes to guest
4489	properties whose name matches one of the patterns will generate an
4490	<link to="IVirtualBoxCallback::onGuestPropertyChange"/> signal.
4491	</desc>
4492	</attribute>
4493
4494	<attribute name="liveMigrationTarget" type="boolean">
4495	<desc>
4496	When set to @a true, the virtual machine becomes a live migration
4497	target. This can only set to @a true when the VM is in the @a
4498	PoweredOff state.
4499
4500	This property is automatically set to @a false when the VM is powered
4501	on.
4502	</desc>
4503	</attribute>
4504
4505	<attribute name="liveMigrationPort" type="unsigned long">
4506	<desc>
4507	The TCP port used for live migration. This can only be set when the
4508	VM is in the @a PoweredOff state.
4509
4510	0 means the port is automatically selected and the source machine will
4511	have to be told where to connected after the destination has been
4512	started.
4513	</desc>
4514	</attribute>
4515
4516	<attribute name="liveMigrationPassword" type="wstring">
4517	<desc>
4518	The password the live migration target will check for.
4519	</desc>
4520	</attribute>
4521
4522	<method name="setBootOrder">
4523	<desc>
4524	Puts the given device to the specified position in
4525	the boot order.
4526
4527	To indicate that no device is associated with the given position,
4528	<link to="DeviceType_Null"/> should be used.
4529
4530	@todo setHardDiskBootOrder(), setNetworkBootOrder()
4531
4532	<result name="E_INVALIDARG">
4533	Boot @a position out of range.
4534	</result>
4535	<result name="E_NOTIMPL">
4536	Booting from USB @a device currently not supported.
4537	</result>
4538
4539	</desc>
4540	<param name="position" type="unsigned long" dir="in">
4541	<desc>
4542	Position in the boot order (@c 1 to the total number of
4543	devices the machine can boot from, as returned by
4544	<link to="ISystemProperties::maxBootPosition"/>).
4545	</desc>
4546	</param>
4547	<param name="device" type="DeviceType" dir="in">
4548	<desc>
4549	The type of the device used to boot at the given position.
4550	</desc>
4551	</param>
4552	</method>
4553
4554	<method name="getBootOrder" const="yes">
4555	<desc>
4556	Returns the device type that occupies the specified
4557	position in the boot order.
4558
4559	@todo [remove?]
4560	If the machine can have more than one device of the returned type
4561	(such as hard disks), then a separate method should be used to
4562	retrieve the individual device that occupies the given position.
4563
4564	If here are no devices at the given position, then
4565	<link to="DeviceType_Null"/> is returned.
4566
4567	@todo getHardDiskBootOrder(), getNetworkBootOrder()
4568
4569	<result name="E_INVALIDARG">
4570	Boot @a position out of range.
4571	</result>
4572
4573	</desc>
4574	<param name="position" type="unsigned long" dir="in">
4575	<desc>
4576	Position in the boot order (@c 1 to the total number of
4577	devices the machine can boot from, as returned by
4578	<link to="ISystemProperties::maxBootPosition"/>).
4579	</desc>
4580	</param>
4581	<param name="device" type="DeviceType" dir="return">
4582	<desc>
4583	Device at the given position.
4584	</desc>
4585	</param>
4586	</method>
4587
4588	<method name="attachDevice">
4589	<desc>
4590	Attaches a device and optionally mounts a medium to the given storage
4591	controller (<link to="IStorageController" />, identified by @a name),
4592	at the indicated port and device.
4593
4594	This method is intended for managing storage devices in general (it works
4595	for both fixed and removable media). For storage devices supporting removable
4596	media (such as DVDs and floppies), you can also use <link to="IMedium::mountMedium"/>
4597	for changing the media while the machine is running.
4598
4599	For the IDE bus, the @a controllerPort parameter can be either
4600	@c 0 or @c 1, to specify the primary or secondary IDE controller,
4601	respectively. For each of these, @a device can then be either @c 0 or @c 1,
4602	to specify the master or the slave device, respectively. (In the
4603	default configuration of virtual machines, the secondary master is
4604	used for a CD/DVD drive.)
4605
4606	For an SATA controller, @a controllerPort must be a number ranging
4607	from @c 0 to @c 29. For a SCSI controller, @a controllerPort must
4608	be a number ranging from @c 0 to @c 15.
4609
4610	For both SCSI and SATA, the @a device parameter is unused and must
4611	be @c 0.
4612
4613	For fixed media such as hard disks, the given medium cannot be NULL. It may
4614	be NULL for removable media such as DVDs and floppies.
4615
4616	After calling this returns successfully, a new instance of
4617	<link to="IMediumAttachment"/> will appear in the machine's list of medium
4618	attachments (<link to="IMachine::mediumAttachments"/>).
4619
4620	The specified device slot must not have another disk attached to it, or
4621	this method will fail.
4622
4623	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
4624	information about attaching media.
4625
4626	<note>
4627	You cannot attach a hard disk to a running machine. Also, you cannot
4628	attach a hard disk to a newly created machine until this machine's
4629	settings are saved to disk using <link to="#saveSettings"/>.
4630	</note>
4631	<note>
4632	If the medium is being attached indirectly, a new differencing medium
4633	will implicitly be created for it and attached instead. If the
4634	changes made to the machine settings (including this indirect
4635	attachment) are later cancelled using <link to="#discardSettings"/>,
4636	this implicitly created differencing medium will implicitly
4637	be deleted.
4638	</note>
4639
4640	<result name="E_INVALIDARG">
4641	SATA device, SATA port, IDE port or IDE slot out of range.
4642	</result>
4643	<result name="VBOX_E_INVALID_OBJECT_STATE">
4644	Attempt to attach medium to an unregistered virtual machine.
4645	</result>
4646	<result name="VBOX_E_INVALID_VM_STATE">
4647	Invalid machine state.
4648	</result>
4649	<result name="VBOX_E_OBJECT_IN_USE">
4650	Hard disk already attached to this or another virtual machine.
4651	</result>
4652
4653	</desc>
4654	<param name="name" type="wstring" dir="in">
4655	<desc>Name of the storage controller to attach the device to.</desc>
4656	</param>
4657	<param name="controllerPort" type="long" dir="in">
4658	<desc>Port to attach the device to.</desc>
4659	</param>
4660	<param name="device" type="long" dir="in">
4661	<desc>Device slot in the given port to attach the device to.</desc>
4662	</param>
4663	<param name="type" type="DeviceType" dir="in">
4664	<desc>Device type of the attached device.</desc>
4665	</param>
4666	<param name="id" type="uuid" mod="string" dir="in">
4667	<desc>UUID of the medium to mount. NULL UUID means do not mount any
4668	medium.</desc>
4669	</param>
4670	</method>
4671
4672	<method name="detachDevice">
4673	<desc>
4674	Detaches the device attached to a device slot of the specified bus.
4675
4676	Detaching the device from the virtual machine is deferred. This means
4677	that the medium remains associated with the machine when this method
4678	returns and gets actually de-associated only after a successful
4679	<link to="#saveSettings"/> call. See <link to="IMedium"/>
4680	for more detailed information about attaching media.
4681
4682	<note>
4683	You cannot detach the hard disk from a running machine.
4684	</note>
4685	<note>
4686	Detaching differencing media implicitly created by <link
4687	to="#attachDevice"/> for the indirect attachment using this
4688	method will <b>not</b> implicitly delete them. The
4689	<link to="IMedium::deleteStorage"/> operation should be
4690	explicitly performed by the caller after the medium is successfully
4691	detached and the settings are saved with
4692	<link to="#saveSettings"/>, if it is the desired action.
4693	</note>
4694
4695	<result name="VBOX_E_INVALID_VM_STATE">
4696	Attempt to detach medium from a running virtual machine.
4697	</result>
4698	<result name="VBOX_E_OBJECT_NOT_FOUND">
4699	No medium attached to given slot/bus.
4700	</result>
4701	<result name="VBOX_E_NOT_SUPPORTED">
4702	Hard disk format does not support storage deletion.
4703	</result>
4704
4705	</desc>
4706	<param name="name" type="wstring" dir="in">
4707	<desc>Name of the storage controller to detach the medium from.</desc>
4708	</param>
4709	<param name="controllerPort" type="long" dir="in">
4710	<desc>Port number to detach the medium from.</desc>
4711	</param>
4712	<param name="device" type="long" dir="in">
4713	<desc>Device slot number to detach the medium from.</desc>
4714	</param>
4715	</method>
4716
4717	<method name="mountMedium">
4718	<desc>
4719	Mounts a medium (<link to="IMedium" />, identified
4720	by the given UUID @a id) to the given storage controller
4721	(<link to="IStorageController" />, identified by @a name),
4722	at the indicated port and device. The device must already exist;
4723	see <link to="IMachine::attachDevice"/> for how to attach a new device.
4724
4725	This method is intended only for managing removable media, where the
4726	device is fixed but media is changeable at runtime (such as DVDs
4727	and floppies). It cannot be used for fixed media such as hard disks.
4728
4729	The @a controllerPort and @a device parameters specify the device slot and
4730	have have the same meaning as with <link to="IMachine::attachDevice" />.
4731
4732	The specified device slot can have a medium mounted, which will be
4733	unmounted first. Specifying a NULL medium does just an unmount.
4734
4735	See <link to="IMedium"/> for more detailed information about
4736	attaching media.
4737
4738	<result name="E_INVALIDARG">
4739	SATA device, SATA port, IDE port or IDE slot out of range.
4740	</result>
4741	<result name="VBOX_E_INVALID_OBJECT_STATE">
4742	Attempt to attach medium to an unregistered virtual machine.
4743	</result>
4744	<result name="VBOX_E_INVALID_VM_STATE">
4745	Invalid machine state.
4746	</result>
4747	<result name="VBOX_E_OBJECT_IN_USE">
4748	Medium already attached to this or another virtual machine.
4749	</result>
4750
4751	</desc>
4752	<param name="name" type="wstring" dir="in">
4753	<desc>Name of the storage controller to attach the medium to.</desc>
4754	</param>
4755	<param name="controllerPort" type="long" dir="in">
4756	<desc>Port to attach the medium to.</desc>
4757	</param>
4758	<param name="device" type="long" dir="in">
4759	<desc>Device slot in the given port to attach the medium to.</desc>
4760	</param>
4761	<param name="id" type="uuid" mod="string" dir="in">
4762	<desc>UUID of the medium to attach.</desc>
4763	</param>
4764	</method>
4765
4766	<method name="getMedium" const="yes">
4767	<desc>
4768	Returns the virtual medium attached to a device slot of the specified
4769	bus.
4770
4771	Note that if the medium was indirectly attached by
4772	<link to="#mountMedium"/> to the given device slot then this
4773	method will return not the same object as passed to the
4774	<link to="#mountMedium"/> call. See <link to="IMedium"/> for
4775	more detailed information about mounting a medium.
4776
4777	<result name="VBOX_E_OBJECT_NOT_FOUND">
4778	No medium attached to given slot/bus.
4779	</result>
4780
4781	</desc>
4782	<param name="name" type="wstring" dir="in">
4783	<desc>Name of the storage controller the medium is attached to.</desc>
4784	</param>
4785	<param name="controllerPort" type="long" dir="in">
4786	<desc>Port to query.</desc>
4787	</param>
4788	<param name="device" type="long" dir="in">
4789	<desc>Device slot in the given port to query.</desc>
4790	</param>
4791	<param name="medium" type="IMedium" dir="return">
4792	<desc>Attached medium object.</desc>
4793	</param>
4794	</method>
4795
4796	<method name="getMediumAttachmentsOfController" const="yes">
4797	<desc>
4798	Returns an array of medium attachments which are attached to the
4799	the controller with the given name.
4800
4801	<result name="VBOX_E_OBJECT_NOT_FOUND">
4802	A storage controller with given name doesn't exist.
4803	</result>
4804	</desc>
4805	<param name="name" type="wstring" dir="in"/>
4806	<param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
4807	</method>
4808
4809	<method name="getMediumAttachment" const="yes">
4810	<desc>
4811	Returns a medium attachment which corresponds to the controller with
4812	the given name, on the given port and device slot.
4813
4814	<result name="VBOX_E_OBJECT_NOT_FOUND">
4815	No attachment exists for the given controller/port/device combination.
4816	</result>
4817	</desc>
4818	<param name="name" type="wstring" dir="in"/>
4819	<param name="controllerPort" type="long" dir="in"/>
4820	<param name="device" type="long" dir="in"/>
4821	<param name="attachment" type="IMediumAttachment" dir="return"/>
4822	</method>
4823
4824	<method name="getNetworkAdapter" const="yes">
4825	<desc>
4826	Returns the network adapter associated with the given slot.
4827	Slots are numbered sequentially, starting with zero. The total
4828	number of adapters per machine is defined by the
4829	<link to="ISystemProperties::networkAdapterCount"/> property,
4830	so the maximum slot number is one less than that property's value.
4831
4832	<result name="E_INVALIDARG">
4833	Invalid @a slot number.
4834	</result>
4835
4836	</desc>
4837	<param name="slot" type="unsigned long" dir="in"/>
4838	<param name="adapter" type="INetworkAdapter" dir="return"/>
4839	</method>
4840
4841	<method name="addStorageController">
4842	<desc>
4843	Adds a new storage controller (SCSI or SATA controller) to the
4844	machine and returns it as an instance of
4845	<link to="IStorageController" />.
4846
4847	@a name identifies the controller for subsequent calls such as
4848	<link to="#getStorageControllerByName" />,
4849	<link to="#removeStorageController" />,
4850	<link to="#attachDevice" /> or <link to="#mountMedium" />.
4851
4852	After the controller has been added, you can set its exact
4853	type by setting the <link to="IStorageController::controllerType" />.
4854
4855	<result name="VBOX_E_OBJECT_IN_USE">
4856	A storage controller with given name exists already.
4857	</result>
4858	<result name="E_INVALIDARG">
4859	Invalid @a controllerType.
4860	</result>
4861	</desc>
4862	<param name="name" type="wstring" dir="in"/>
4863	<param name="connectionType" type="StorageBus" dir="in"/>
4864	<param name="controller" type="IStorageController" dir="return"/>
4865	</method>
4866
4867	<method name="getStorageControllerByName" const="yes">
4868	<desc>
4869	Returns a storage controller with the given name.
4870
4871	<result name="VBOX_E_OBJECT_NOT_FOUND">
4872	A storage controller with given name doesn't exist.
4873	</result>
4874	</desc>
4875	<param name="name" type="wstring" dir="in"/>
4876	<param name="storageController" type="IStorageController" dir="return"/>
4877	</method>
4878
4879	<method name="removeStorageController">
4880	<desc>
4881	Removes a storage controller from the machine.
4882
4883	<result name="VBOX_E_OBJECT_NOT_FOUND">
4884	A storage controller with given name doesn't exist.
4885	</result>
4886	</desc>
4887	<param name="name" type="wstring" dir="in"/>
4888	</method>
4889
4890	<method name="getSerialPort" const="yes">
4891	<desc>
4892	Returns the serial port associated with the given slot.
4893	Slots are numbered sequentially, starting with zero. The total
4894	number of serial ports per machine is defined by the
4895	<link to="ISystemProperties::serialPortCount"/> property,
4896	so the maximum slot number is one less than that property's value.
4897
4898	<result name="E_INVALIDARG">
4899	Invalid @a slot number.
4900	</result>
4901
4902	</desc>
4903	<param name="slot" type="unsigned long" dir="in"/>
4904	<param name="port" type="ISerialPort" dir="return"/>
4905	</method>
4906
4907	<method name="getParallelPort" const="yes">
4908	<desc>
4909	Returns the parallel port associated with the given slot.
4910	Slots are numbered sequentially, starting with zero. The total
4911	number of parallel ports per machine is defined by the
4912	<link to="ISystemProperties::parallelPortCount"/> property,
4913	so the maximum slot number is one less than that property's value.
4914
4915	<result name="E_INVALIDARG">
4916	Invalid @a slot number.
4917	</result>
4918
4919	</desc>
4920	<param name="slot" type="unsigned long" dir="in"/>
4921	<param name="port" type="IParallelPort" dir="return"/>
4922	</method>
4923
4924	<method name="getExtraDataKeys">
4925	<desc>
4926	Returns an array representing the machine-specific extra data keys
4927	which currently have values defined.
4928	</desc>
4929	<param name="value" type="wstring" dir="return" safearray="yes">
4930	<desc>Array of extra data keys.</desc>
4931	</param>
4932	</method>
4933
4934	<method name="getExtraData">
4935	<desc>
4936	Returns associated machine-specific extra data.
4937
4938	If the requested data @a key does not exist, this function will
4939	succeed and return an empty string in the @a value argument.
4940
4941	<result name="VBOX_E_FILE_ERROR">
4942	Settings file not accessible.
4943	</result>
4944	<result name="VBOX_E_XML_ERROR">
4945	Could not parse the settings file.
4946	</result>
4947
4948	</desc>
4949	<param name="key" type="wstring" dir="in">
4950	<desc>Name of the data key to get.</desc>
4951	</param>
4952	<param name="value" type="wstring" dir="return">
4953	<desc>Value of the requested data key.</desc>
4954	</param>
4955	</method>
4956
4957	<method name="setExtraData">
4958	<desc>
4959	Sets associated machine-specific extra data.
4960
4961	If you pass @c null or an empty string as a key @a value, the given
4962	@a key will be deleted.
4963
4964	<note>
4965	Before performing the actual data change, this method will ask all
4966	registered callbacks using the
4967	<link to="IVirtualBoxCallback::onExtraDataCanChange"/>
4968	notification for a permission. If one of the callbacks refuses the
4969	new value, the change will not be performed.
4970	</note>
4971	<note>
4972	On success, the
4973	<link to="IVirtualBoxCallback::onExtraDataChange"/> notification
4974	is called to inform all registered callbacks about a successful data
4975	change.
4976	</note>
4977	<note>
4978	This method can be called outside the machine session and therefore
4979	it's a caller's responsibility to handle possible race conditions
4980	when several clients change the same key at the same time.
4981	</note>
4982
4983	<result name="VBOX_E_FILE_ERROR">
4984	Settings file not accessible.
4985	</result>
4986	<result name="VBOX_E_XML_ERROR">
4987	Could not parse the settings file.
4988	</result>
4989
4990	</desc>
4991	<param name="key" type="wstring" dir="in">
4992	<desc>Name of the data key to set.</desc>
4993	</param>
4994	<param name="value" type="wstring" dir="in">
4995	<desc>Value to assign to the key.</desc>
4996	</param>
4997	</method>
4998
4999	<method name="saveSettings">
5000	<desc>
5001	Saves any changes to machine settings made since the session
5002	has been opened or a new machine has been created, or since the
5003	last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
5004	For registered machines, new settings become visible to all
5005	other VirtualBox clients after successful invocation of this
5006	method.
5007	<note>
5008	The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
5009	notification event after the configuration has been successfully
5010	saved (only for registered machines).
5011	</note>
5012	<note>
5013	Calling this method is only valid on instances returned
5014	by <link to="ISession::machine"/> and on new machines
5015	created by <link to="IVirtualBox::createMachine"/> but not
5016	yet registered, or on unregistered machines after calling
5017	<link to="IVirtualBox::unregisterMachine"/>.
5018	</note>
5019
5020	<result name="VBOX_E_FILE_ERROR">
5021	Settings file not accessible.
5022	</result>
5023	<result name="VBOX_E_XML_ERROR">
5024	Could not parse the settings file.
5025	</result>
5026	<result name="E_ACCESSDENIED">
5027	Modification request refused.
5028	</result>
5029
5030	</desc>
5031	</method>
5032
5033	<method name="discardSettings">
5034	<desc>
5035	Discards any changes to the machine settings made since the session
5036	has been opened or since the last call to <link to="#saveSettings"/>
5037	or <link to="#discardSettings"/>.
5038	<note>
5039	Calling this method is only valid on instances returned
5040	by <link to="ISession::machine"/> and on new machines
5041	created by <link to="IVirtualBox::createMachine"/> or
5042	opened by <link to="IVirtualBox::openMachine"/> but not
5043	yet registered, or on unregistered machines after calling
5044	<link to="IVirtualBox::unregisterMachine"/>.
5045	</note>
5046
5047	<result name="VBOX_E_INVALID_VM_STATE">
5048	Virtual machine is not mutable.
5049	</result>
5050
5051	</desc>
5052	</method>
5053
5054	<method name="deleteSettings">
5055	<desc>
5056	Deletes the settings file of this machine from disk.
5057	The machine must not be registered in order for this operation
5058	to succeed.
5059	<note>
5060	<link to="#settingsModified"/> will return @c true after this
5061	method successfully returns.
5062	</note>
5063	<note>
5064	Calling this method is only valid on instances returned
5065	by <link to="ISession::machine"/> and on new machines
5066	created by <link to="IVirtualBox::createMachine"/> or
5067	opened by <link to="IVirtualBox::openMachine"/> but not
5068	yet registered, or on unregistered machines after calling
5069	<link to="IVirtualBox::unregisterMachine"/>.
5070	</note>
5071	<note>
5072	The deleted machine settings file can be restored (saved again)
5073	by calling <link to="#saveSettings"/>.
5074	</note>
5075
5076	<result name="VBOX_E_INVALID_VM_STATE">
5077	Cannot delete settings of a registered machine or
5078	machine not mutable.
5079	</result>
5080	<result name="VBOX_E_IPRT_ERROR">
5081	Could not delete the settings file.
5082	</result>
5083
5084	</desc>
5085	</method>
5086
5087	<method name="export">
5088	<desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
5089	steps required to export VirtualBox machines to OVF.
5090	</desc>
5091
5092	<param name="aAppliance" type="IAppliance" dir="in">
5093	<desc>Appliance to export this machine to.</desc>
5094	</param>
5095	<param name="aDescription" type="IVirtualSystemDescription" dir="return">
5096	<desc>VirtualSystemDescription object which is created for this machine.</desc>
5097	</param>
5098	</method >
5099
5100	<method name="getSnapshot">
5101	<desc>
5102	Returns a snapshot of this machine with the given UUID.
5103	A @c null UUID can be used to obtain the first snapshot
5104	taken on this machine. This is useful if you want to traverse
5105	the whole tree of snapshots starting from the root.
5106
5107	<result name="VBOX_E_OBJECT_NOT_FOUND">
5108	Virtual machine has no snapshots or snapshot not found.
5109	</result>
5110
5111	</desc>
5112	<param name="id" type="uuid" mod="string" dir="in">
5113	<desc>UUID of the snapshot to get</desc>
5114	</param>
5115	<param name="snapshot" type="ISnapshot" dir="return">
5116	<desc>Snapshot object with the given UUID.</desc>
5117	</param>
5118	</method>
5119
5120	<method name="findSnapshot">
5121	<desc>
5122	Returns a snapshot of this machine with the given name.
5123
5124	<result name="VBOX_E_OBJECT_NOT_FOUND">
5125	Virtual machine has no snapshots or snapshot not found.
5126	</result>
5127
5128	</desc>
5129	<param name="name" type="wstring" dir="in">
5130	<desc>Name of the snapshot to find</desc>
5131	</param>
5132	<param name="snapshot" type="ISnapshot" dir="return">
5133	<desc>Snapshot object with the given name.</desc>
5134	</param>
5135	</method>
5136
5137	<method name="setCurrentSnapshot">
5138	<desc>
5139	Sets the current snapshot of this machine.
5140	<note>
5141	In the current implementation, this operation is not
5142	implemented.
5143	</note>
5144	</desc>
5145	<param name="id" type="uuid" mod="string" dir="in">
5146	<desc>UUID of the snapshot to set as the current snapshot.</desc>
5147	</param>
5148	</method>
5149
5150	<method name="createSharedFolder">
5151	<desc>
5152	Creates a new permanent shared folder by associating the given logical
5153	name with the given host path, adds it to the collection of shared
5154	folders and starts sharing it. Refer to the description of
5155	<link to="ISharedFolder"/> to read more about logical names.
5156
5157	<result name="VBOX_E_OBJECT_IN_USE">
5158	Shared folder already exists.
5159	</result>
5160	<result name="VBOX_E_FILE_ERROR">
5161	Shared folder @a hostPath not accessible.
5162	</result>
5163
5164	</desc>
5165	<param name="name" type="wstring" dir="in">
5166	<desc>Unique logical name of the shared folder.</desc>
5167	</param>
5168	<param name="hostPath" type="wstring" dir="in">
5169	<desc>Full path to the shared folder in the host file system.</desc>
5170	</param>
5171	<param name="writable" type="boolean" dir="in">
5172	<desc>Whether the share is writable or readonly</desc>
5173	</param>
5174	</method>
5175
5176	<method name="removeSharedFolder">
5177	<desc>
5178	Removes the permanent shared folder with the given name previously
5179	created by <link to="#createSharedFolder"/> from the collection of
5180	shared folders and stops sharing it.
5181
5182	<result name="VBOX_E_INVALID_VM_STATE">
5183	Virtual machine is not mutable.
5184	</result>
5185	<result name="VBOX_E_OBJECT_NOT_FOUND">
5186	Shared folder @a name does not exist.
5187	</result>
5188
5189	</desc>
5190	<param name="name" type="wstring" dir="in">
5191	<desc>Logical name of the shared folder to remove.</desc>
5192	</param>
5193	</method>
5194
5195	<method name="canShowConsoleWindow">
5196	<desc>
5197	Returns @c true if the VM console process can activate the
5198	console window and bring it to foreground on the desktop of
5199	the host PC.
5200	<note>
5201	This method will fail if a session for this machine is not
5202	currently open.
5203	</note>
5204
5205	<result name="VBOX_E_INVALID_VM_STATE">
5206	Machine session is not open.
5207	</result>
5208
5209	</desc>
5210	<param name="canShow" type="boolean" dir="return">
5211	<desc>
5212	@c true if the console window can be shown and @c false otherwise.
5213	</desc>
5214	</param>
5215	</method>
5216
5217	<method name="showConsoleWindow">
5218	<desc>
5219	Activates the console window and brings it to foreground on
5220	the desktop of the host PC. Many modern window managers on
5221	many platforms implement some sort of focus stealing
5222	prevention logic, so that it may be impossible to activate
5223	a window without the help of the currently active
5224	application. In this case, this method will return a non-zero
5225	identifier that represents the top-level window of the VM
5226	console process. The caller, if it represents a currently
5227	active process, is responsible to use this identifier (in a
5228	platform-dependent manner) to perform actual window
5229	activation.
5230	<note>
5231	This method will fail if a session for this machine is not
5232	currently open.
5233	</note>
5234
5235	<result name="VBOX_E_INVALID_VM_STATE">
5236	Machine session is not open.
5237	</result>
5238
5239	</desc>
5240	<param name="winId" type="unsigned long long" dir="return">
5241	<desc>
5242	Platform-dependent identifier of the top-level VM console
5243	window, or zero if this method has performed all actions
5244	necessary to implement the <i>show window</i> semantics for
5245	the given platform and/or VirtualBox front-end.
5246	</desc>
5247	</param>
5248	</method>
5249
5250	<method name="getGuestProperty">
5251	<desc>
5252	Reads an entry from the machine's guest property store.
5253
5254	<result name="VBOX_E_INVALID_VM_STATE">
5255	Machine session is not open.
5256	</result>
5257
5258	</desc>
5259	<param name="name" type="wstring" dir="in">
5260	<desc>
5261	The name of the property to read.
5262	</desc>
5263	</param>
5264	<param name="value" type="wstring" dir="out">
5265	<desc>
5266	The value of the property. If the property does not exist then this
5267	will be empty.
5268	</desc>
5269	</param>
5270	<param name="timestamp" type="unsigned long long" dir="out">
5271	<desc>
5272	The time at which the property was last modified, as seen by the
5273	server process.
5274	</desc>
5275	</param>
5276	<param name="flags" type="wstring" dir="out">
5277	<desc>
5278	Additional property parameters, passed as a comma-separated list of
5279	"name=value" type entries.
5280	</desc>
5281	</param>
5282	</method>
5283
5284	<method name="getGuestPropertyValue">
5285	<desc>
5286	Reads a value from the machine's guest property store.
5287
5288	<result name="VBOX_E_INVALID_VM_STATE">
5289	Machine session is not open.
5290	</result>
5291
5292	</desc>
5293	<param name="property" type="wstring" dir="in">
5294	<desc>
5295	The name of the property to read.
5296	</desc>
5297	</param>
5298	<param name="value" type="wstring" dir="return">
5299	<desc>
5300	The value of the property. If the property does not exist then this
5301	will be empty.
5302	</desc>
5303	</param>
5304	</method>
5305
5306	<method name="getGuestPropertyTimestamp">
5307	<desc>
5308	Reads a property timestamp from the machine's guest property store.
5309
5310	<result name="VBOX_E_INVALID_VM_STATE">
5311	Machine session is not open.
5312	</result>
5313
5314	</desc>
5315	<param name="property" type="wstring" dir="in">
5316	<desc>
5317	The name of the property to read.
5318	</desc>
5319	</param>
5320	<param name="value" type="unsigned long long" dir="return">
5321	<desc>
5322	The timestamp. If the property does not exist then this will be
5323	empty.
5324	</desc>
5325	</param>
5326	</method>
5327
5328	<method name="setGuestProperty">
5329	<desc>
5330	Sets, changes or deletes an entry in the machine's guest property
5331	store.
5332
5333	<result name="E_ACCESSDENIED">
5334	Property cannot be changed.
5335	</result>
5336	<result name="E_INVALIDARG">
5337	Invalid @a flags.
5338	</result>
5339	<result name="VBOX_E_INVALID_VM_STATE">
5340	Virtual machine is not mutable or session not open.
5341	</result>
5342	<result name="VBOX_E_INVALID_OBJECT_STATE">
5343	Cannot set transient property when machine not running.
5344	</result>
5345
5346	</desc>
5347	<param name="property" type="wstring" dir="in">
5348	<desc>
5349	The name of the property to set, change or delete.
5350	</desc>
5351	</param>
5352	<param name="value" type="wstring" dir="in">
5353	<desc>
5354	The new value of the property to set, change or delete. If the
5355	property does not yet exist and value is non-empty, it will be
5356	created. If the value is @c null or empty, the property will be
5357	deleted if it exists.
5358	</desc>
5359	</param>
5360	<param name="flags" type="wstring" dir="in">
5361	<desc>
5362	Additional property parameters, passed as a comma-separated list of
5363	"name=value" type entries.
5364	</desc>
5365	</param>
5366	</method>
5367
5368	<method name="setGuestPropertyValue">
5369	<desc>
5370	Sets, changes or deletes a value in the machine's guest property
5371	store. The flags field will be left unchanged or created empty for a
5372	new property.
5373
5374	<result name="E_ACCESSDENIED">
5375	Property cannot be changed.
5376	</result>
5377	<result name="VBOX_E_INVALID_VM_STATE">
5378	Virtual machine is not mutable or session not open.
5379	</result>
5380	<result name="VBOX_E_INVALID_OBJECT_STATE">
5381	Cannot set transient property when machine not running.
5382	</result>
5383	</desc>
5384
5385	<param name="property" type="wstring" dir="in">
5386	<desc>
5387	The name of the property to set, change or delete.
5388	</desc>
5389	</param>
5390	<param name="value" type="wstring" dir="in">
5391	<desc>
5392	The new value of the property to set, change or delete. If the
5393	property does not yet exist and value is non-empty, it will be
5394	created. If the value is @c null or empty, the property will be
5395	deleted if it exists.
5396	</desc>
5397	</param>
5398	</method>
5399
5400	<method name="enumerateGuestProperties">
5401	<desc>
5402	Return a list of the guest properties matching a set of patterns along
5403	with their values, time stamps and flags.
5404	</desc>
5405	<param name="patterns" type="wstring" dir="in">
5406	<desc>
5407	The patterns to match the properties against, separated by '\|'
5408	characters. If this is empty or @c null, all properties will match.
5409	</desc>
5410	</param>
5411	<param name="name" type="wstring" dir="out" safearray="yes">
5412	<desc>
5413	The names of the properties returned.
5414	</desc>
5415	</param>
5416	<param name="value" type="wstring" dir="out" safearray="yes">
5417	<desc>
5418	The values of the properties returned. The array entries match the
5419	corresponding entries in the @a name array.
5420	</desc>
5421	</param>
5422	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
5423	<desc>
5424	The time stamps of the properties returned. The array entries match
5425	the corresponding entries in the @a name array.
5426	</desc>
5427	</param>
5428	<param name="flags" type="wstring" dir="out" safearray="yes">
5429	<desc>
5430	The flags of the properties returned. The array entries match the
5431	corresponding entries in the @a name array.
5432	</desc>
5433	</param>
5434	</method>
5435	</interface>
5436
5437	<!--
5438	// IConsole
5439	/////////////////////////////////////////////////////////////////////////
5440	-->
5441
5442	<interface
5443	name="IConsoleCallback" extends="$unknown"
5444	uuid="d6239535-bda2-4ef7-83f4-f4722e4a3b2c"
5445	wsmap="suppress"
5446	>
5447
5448	<desc>
5449	This interface is used by a client of the Main API that need to
5450	be notified of events. For example, a graphical user interface
5451	can use this to learn about machine state changes so they can
5452	update the list of virtual machines without having to rely
5453	on polling.
5454
5455	Whenever relevant events occur in VirtualBox, the callbacks in
5456	objects of this interface are called. In order for this to be
5457	useful, a client needs to create its own subclass that implements
5458	this interface in which the methods for the relevant callbacks
5459	are overridden. An instance of this subclass interface can then
5460	be passed to <link to="IConsole::registerCallback" />.
5461	</desc>
5462
5463	<method name="onMousePointerShapeChange">
5464	<desc>
5465	Notification when the guest mouse pointer shape has
5466	changed. The new shape data is given.
5467	</desc>
5468	<param name="visible" type="boolean" dir="in">
5469	<desc>
5470	Flag whether the pointer is visible.
5471	</desc>
5472	</param>
5473	<param name="alpha" type="boolean" dir="in">
5474	<desc>
5475	Flag whether the pointer has an alpha channel.
5476	</desc>
5477	</param>
5478	<param name="xHot" type="unsigned long" dir="in">
5479	<desc>
5480	The pointer hot spot x coordinate.
5481	</desc>
5482	</param>
5483	<param name="yHot" type="unsigned long" dir="in">
5484	<desc>
5485	The pointer hot spot y coordinate.
5486	</desc>
5487	</param>
5488	<param name="width" type="unsigned long" dir="in">
5489	<desc>
5490	Width of the pointer shape in pixels.
5491	</desc>
5492	</param>
5493	<param name="height" type="unsigned long" dir="in">
5494	<desc>
5495	Height of the pointer shape in pixels.
5496	</desc>
5497	</param>
5498	<param name="shape" type="octet" mod="ptr" dir="in">
5499	<desc>
5500	Address of the shape buffer.
5501
5502	The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
5503	followed by a 32-bpp XOR (color) mask.
5504
5505	For pointers without alpha channel the XOR mask pixels are 32
5506	bit values: (lsb)BGR0(msb). For pointers with alpha channel
5507	the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
5508
5509	An AND mask is used for pointers with alpha channel, so if the
5510	callback does not support alpha, the pointer could be
5511	displayed as a normal color pointer.
5512
5513	The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
5514	size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
5515	height</tt>. The padding bits at the end of each scanline are
5516	undefined.
5517
5518	The XOR mask follows the AND mask on the next 4-byte aligned
5519	offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
5520	Bytes in the gap between the AND and the XOR mask are undefined.
5521	The XOR mask scanlines have no gap between them and the size of
5522	the XOR mask is: <tt>cXor = width * 4 * height</tt>.
5523
5524	<note>
5525	If @a shape is 0, only the pointer visibility is changed.
5526	</note>
5527	</desc>
5528	</param>
5529	</method>
5530
5531	<method name="onMouseCapabilityChange">
5532	<desc>
5533	Notification when the mouse capabilities reported by the
5534	guest have changed. The new capabilities are passed.
5535	</desc>
5536	<param name="supportsAbsolute" type="boolean" dir="in"/>
5537	<param name="needsHostCursor" type="boolean" dir="in"/>
5538	</method>
5539
5540	<method name="onKeyboardLedsChange">
5541	<desc>
5542	Notification when the guest OS executes the KBD_CMD_SET_LEDS command
5543	to alter the state of the keyboard LEDs.
5544	</desc>
5545	<param name="numLock" type="boolean" dir="in"/>
5546	<param name="capsLock" type="boolean" dir="in"/>
5547	<param name="scrollLock" type="boolean" dir="in"/>
5548	</method>
5549
5550	<method name="onStateChange">
5551	<desc>
5552	Notification when the execution state of the machine has changed.
5553	The new state will be given.
5554	</desc>
5555	<param name="state" type="MachineState" dir="in"/>
5556	</method>
5557
5558	<method name="onAdditionsStateChange">
5559	<desc>
5560	Notification when a Guest Additions property changes.
5561	Interested callees should query IGuest attributes to
5562	find out what has changed.
5563	</desc>
5564	</method>
5565
5566	<method name="onNetworkAdapterChange">
5567	<desc>
5568	Notification when a property of one of the
5569	virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
5570	changes. Interested callees should use INetworkAdapter methods and
5571	attributes to find out what has changed.
5572	</desc>
5573	<param name="networkAdapter" type="INetworkAdapter" dir="in">
5574	<desc>Network adapter that is subject to change.</desc>
5575	</param>
5576	</method>
5577
5578	<method name="onSerialPortChange">
5579	<desc>
5580	Notification when a property of one of the
5581	virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
5582	Interested callees should use ISerialPort methods and attributes
5583	to find out what has changed.
5584	</desc>
5585	<param name="serialPort" type="ISerialPort" dir="in">
5586	<desc>Serial port that is subject to change.</desc>
5587	</param>
5588	</method>
5589
5590	<method name="onParallelPortChange">
5591	<desc>
5592	Notification when a property of one of the
5593	virtual <link to="IMachine::getParallelPort">parallel ports</link>
5594	changes. Interested callees should use ISerialPort methods and
5595	attributes to find out what has changed.
5596	</desc>
5597	<param name="parallelPort" type="IParallelPort" dir="in">
5598	<desc>Parallel port that is subject to change.</desc>
5599	</param>
5600	</method>
5601
5602	<method name="onStorageControllerChange">
5603	<desc>
5604	Notification when a property of one of the
5605	virtual <link to="IMachine::storageControllers">storage controllers</link>
5606	changes. Interested callees should query the corresponding collections
5607	to find out what has changed.
5608	</desc>
5609	</method>
5610
5611	<method name="onMediumChange">
5612	<desc>
5613	Notification when a
5614	<link to="IMachine::mediumAttachments">medium attachment</link>
5615	changes.
5616	</desc>
5617	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
5618	<desc>Medium attachment that is subject to change.</desc>
5619	</param>
5620	</method>
5621
5622	<method name="onVRDPServerChange">
5623	<desc>
5624	Notification when a property of the
5625	<link to="IMachine::VRDPServer">VRDP server</link> changes.
5626	Interested callees should use IVRDPServer methods and attributes to
5627	find out what has changed.
5628	</desc>
5629	</method>
5630
5631	<method name="onRemoteDisplayInfoChange">
5632	<desc>
5633	Notification when the status of the VRDP server changes. Interested callees
5634	should use <link to="IConsole::RemoteDisplayInfo">IRemoteDisplayInfo</link>
5635	attributes to find out what is the current status.
5636	</desc>
5637	</method>
5638
5639	<method name="onUSBControllerChange">
5640	<desc>
5641	Notification when a property of the virtual
5642	<link to="IMachine::USBController">USB controller</link> changes.
5643	Interested callees should use IUSBController methods and attributes to
5644	find out what has changed.
5645	</desc>
5646	</method>
5647
5648	<method name="onUSBDeviceStateChange">
5649	<desc>
5650	Notification when a USB device is attached to or detached from
5651	the virtual USB controller.
5652
5653	This notification is sent as a result of the indirect
5654	request to attach the device because it matches one of the
5655	machine USB filters, or as a result of the direct request
5656	issued by <link to="IConsole::attachUSBDevice"/> or
5657	<link to="IConsole::detachUSBDevice"/>.
5658
5659	This notification is sent in case of both a succeeded and a
5660	failed request completion. When the request succeeds, the
5661	@a error parameter is @c null, and the given device has been
5662	already added to (when @a attached is @c true) or removed from
5663	(when @a attached is @c false) the collection represented by
5664	<link to="IConsole::USBDevices"/>. On failure, the collection
5665	doesn't change and the @a error parameter represents the error
5666	message describing the failure.
5667
5668	</desc>
5669	<param name="device" type="IUSBDevice" dir="in">
5670	<desc>Device that is subject to state change.</desc>
5671	</param>
5672	<param name="attached" type="boolean" dir="in">
5673	<desc>
5674	@c true if the device was attached and @c false otherwise.
5675	</desc>
5676	</param>
5677	<param name="error" type="IVirtualBoxErrorInfo" dir="in">
5678	<desc>
5679	@c null on success or an error message object on failure.
5680	</desc>
5681	</param>
5682	</method>
5683
5684	<method name="onSharedFolderChange">
5685	<desc>
5686	Notification when a shared folder is added or removed.
5687	The @a scope argument defines one of three scopes:
5688	<link to="IVirtualBox::sharedFolders">global shared folders</link>
5689	(<link to="Scope_Global">Global</link>),
5690	<link to="IMachine::sharedFolders">permanent shared folders</link> of
5691	the machine (<link to="Scope_Machine">Machine</link>) or <link
5692	to="IConsole::sharedFolders">transient shared folders</link> of the
5693	machine (<link to="Scope_Session">Session</link>). Interested callees
5694	should use query the corresponding collections to find out what has
5695	changed.
5696	</desc>
5697	<param name="scope" type="Scope" dir="in">
5698	<desc>Scope of the notification.</desc>
5699	</param>
5700	</method>
5701
5702	<method name="onRuntimeError">
5703	<desc>
5704	Notification when an error happens during the virtual
5705	machine execution.
5706
5707	There are three kinds of runtime errors:
5708	<ul>
5709	<li><i>fatal</i></li>
5710	<li><i>non-fatal with retry</i></li>
5711	<li><i>non-fatal warnings</i></li>
5712	</ul>
5713
5714	<b>Fatal</b> errors are indicated by the @a fatal parameter set
5715	to @c true. In case of fatal errors, the virtual machine
5716	execution is always paused before calling this notification, and
5717	the notification handler is supposed either to immediately save
5718	the virtual machine state using <link to="IConsole::saveState"/>
5719	or power it off using <link to="IConsole::powerDown"/>.
5720	Resuming the execution can lead to unpredictable results.
5721
5722	<b>Non-fatal</b> errors and warnings are indicated by the
5723	@a fatal parameter set to @c false. If the virtual machine
5724	is in the Paused state by the time the error notification is
5725	received, it means that the user can <i>try to resume</i> the machine
5726	execution after attempting to solve the problem that caused the
5727	error. In this case, the notification handler is supposed
5728	to show an appropriate message to the user (depending on the
5729	value of the @a id parameter) that offers several actions such
5730	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
5731	wants to retry, the notification handler should continue
5732	the machine execution using the <link to="IConsole::resume"/>
5733	call. If the machine execution is not Paused during this
5734	notification, then it means this notification is a <i>warning</i>
5735	(for example, about a fatal condition that can happen very soon);
5736	no immediate action is required from the user, the machine
5737	continues its normal execution.
5738
5739	Note that in either case the notification handler
5740	<b>must not</b> perform any action directly on a thread
5741	where this notification is called. Everything it is allowed to
5742	do is to post a message to another thread that will then talk
5743	to the user and take the corresponding action.
5744
5745	Currently, the following error identifiers are known:
5746	<ul>
5747	<li><tt>"HostMemoryLow"</tt></li>
5748	<li><tt>"HostAudioNotResponding"</tt></li>
5749	<li><tt>"VDIStorageFull"</tt></li>
5750	<li><tt>"3DSupportIncompatibleAdditions"</tt></li>
5751	</ul>
5752
5753	<note>
5754	This notification is not designed to be implemented by
5755	more than one callback at a time. If you have multiple
5756	IConsoleCallback instances registered on the given
5757	IConsole object, make sure you simply do nothing but
5758	return @c S_OK from all but one of them that does actual
5759	user notification and performs necessary actions.
5760	</note>
5761
5762	</desc>
5763	<param name="fatal" type="boolean" dir="in">
5764	<desc>Whether the error is fatal or not</desc>
5765	</param>
5766	<param name="id" type="wstring" dir="in">
5767	<desc>Error identifier</desc>
5768	</param>
5769	<param name="message" type="wstring" dir="in">
5770	<desc>Optional error message</desc>
5771	</param>
5772	</method>
5773
5774	<method name="onCanShowWindow">
5775	<desc>
5776	Notification when a call to
5777	<link to="IMachine::canShowConsoleWindow"/> is made by a
5778	front-end to check if a subsequent call to
5779	<link to="IMachine::showConsoleWindow"/> can succeed.
5780
5781	The callee should give an answer appropriate to the current
5782	machine state in the @a canShow argument. This answer must
5783	remain valid at least until the next
5784	<link to="IConsole::state">machine state</link> change.
5785
5786	<note>
5787	This notification is not designed to be implemented by
5788	more than one callback at a time. If you have multiple
5789	IConsoleCallback instances registered on the given
5790	IConsole object, make sure you simply do nothing but
5791	return @c true and @c S_OK from all but one of them that
5792	actually manages console window activation.
5793	</note>
5794	</desc>
5795	<param name="canShow" type="boolean" dir="return">
5796	<desc>
5797	@c true if the console window can be shown and @c false otherwise.
5798	</desc>
5799	</param>
5800	</method>
5801
5802	<method name="onShowWindow">
5803	<desc>
5804	Notification when a call to
5805	<link to="IMachine::showConsoleWindow"/>
5806	requests the console window to be activated and brought to
5807	foreground on the desktop of the host PC.
5808
5809	This notification should cause the VM console process to
5810	perform the requested action as described above. If it is
5811	impossible to do it at a time of this notification, this
5812	method should return a failure.
5813
5814	Note that many modern window managers on many platforms
5815	implement some sort of focus stealing prevention logic, so
5816	that it may be impossible to activate a window without the
5817	help of the currently active application (which is supposedly
5818	an initiator of this notification). In this case, this method
5819	must return a non-zero identifier that represents the
5820	top-level window of the VM console process. The caller, if it
5821	represents a currently active process, is responsible to use
5822	this identifier (in a platform-dependent manner) to perform
5823	actual window activation.
5824
5825	This method must set @a winId to zero if it has performed all
5826	actions necessary to complete the request and the console
5827	window is now active and in foreground, to indicate that no
5828	further action is required on the caller's side.
5829
5830	<note>
5831	This notification is not designed to be implemented by
5832	more than one callback at a time. If you have multiple
5833	IConsoleCallback instances registered on the given
5834	IConsole object, make sure you simply do nothing but
5835	return @c S_OK from all but one of them that actually
5836	manages console window activation.
5837	</note>
5838	</desc>
5839	<param name="winId" type="unsigned long long" dir="return">
5840	<desc>
5841	Platform-dependent identifier of the top-level VM console
5842	window, or zero if this method has performed all actions
5843	necessary to implement the <i>show window</i> semantics for
5844	the given platform and/or this VirtualBox front-end.
5845	</desc>
5846	</param>
5847	</method>
5848
5849	</interface>
5850
5851	<interface
5852	name="IRemoteDisplayInfo" extends="$unknown"
5853	uuid="b3741084-806f-4c3b-8c42-ebad1a81e45a"
5854	wsmap="struct"
5855	>
5856	<desc>
5857	Contains information about the remote display (VRDP) capabilities and status.
5858	This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
5859	</desc>
5860
5861	<attribute name="active" type="boolean" readonly="yes">
5862	<desc>
5863	Whether the remote display connection is active.
5864	</desc>
5865	</attribute>
5866
5867	<attribute name="port" type="long" readonly="yes">
5868	<desc>
5869	VRDP server port number. If this property is equal to <tt>0</tt>, then
5870	the VRDP server failed to start, usually because there are no free TCP
5871	ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDP
5872	server has not yet been started.
5873	</desc>
5874	</attribute>
5875
5876	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
5877	<desc>
5878	How many times a client connected.
5879	</desc>
5880	</attribute>
5881
5882	<attribute name="beginTime" type="long long" readonly="yes">
5883	<desc>
5884	When the last connection was established, in milliseconds since 1970-01-01 UTC.
5885	</desc>
5886	</attribute>
5887
5888	<attribute name="endTime" type="long long" readonly="yes">
5889	<desc>
5890	When the last connection was terminated or the current time, if
5891	connection is still active, in milliseconds since 1970-01-01 UTC.
5892	</desc>
5893	</attribute>
5894
5895	<attribute name="bytesSent" type="unsigned long long" readonly="yes">
5896	<desc>
5897	How many bytes were sent in last or current, if still active, connection.
5898	</desc>
5899	</attribute>
5900
5901	<attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
5902	<desc>
5903	How many bytes were sent in all connections.
5904	</desc>
5905	</attribute>
5906
5907	<attribute name="bytesReceived" type="unsigned long long" readonly="yes">
5908	<desc>
5909	How many bytes were received in last or current, if still active, connection.
5910	</desc>
5911	</attribute>
5912
5913	<attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
5914	<desc>
5915	How many bytes were received in all connections.
5916	</desc>
5917	</attribute>
5918
5919	<attribute name="user" type="wstring" readonly="yes">
5920	<desc>
5921	Login user name supplied by the client.
5922	</desc>
5923	</attribute>
5924
5925	<attribute name="domain" type="wstring" readonly="yes">
5926	<desc>
5927	Login domain name supplied by the client.
5928	</desc>
5929	</attribute>
5930
5931	<attribute name="clientName" type="wstring" readonly="yes">
5932	<desc>
5933	The client name supplied by the client.
5934	</desc>
5935	</attribute>
5936
5937	<attribute name="clientIP" type="wstring" readonly="yes">
5938	<desc>
5939	The IP address of the client.
5940	</desc>
5941	</attribute>
5942
5943	<attribute name="clientVersion" type="unsigned long" readonly="yes">
5944	<desc>
5945	The client software version number.
5946	</desc>
5947	</attribute>
5948
5949	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
5950	<desc>
5951	Public key exchange method used when connection was established.
5952	Values: 0 - RDP4 public key exchange scheme.
5953	1 - X509 certificates were sent to client.
5954	</desc>
5955	</attribute>
5956
5957	</interface>
5958
5959	<interface
5960	name="IConsole" extends="$unknown"
5961	uuid="c47486e1-3d99-4212-b1c5-86451978999d"
5962	wsmap="managed"
5963	>
5964	<desc>
5965	The IConsole interface represents an interface to control virtual
5966	machine execution.
5967
5968	The console object that implements the IConsole interface is obtained
5969	from a session object after the session for the given machine has been
5970	opened using one of <link to="IVirtualBox::openSession"/>,
5971	<link to="IVirtualBox::openRemoteSession"/> or
5972	<link to="IVirtualBox::openExistingSession"/> methods.
5973
5974	Methods of the IConsole interface allow the caller to query the current
5975	virtual machine execution state, pause the machine or power it down, save
5976	the machine state or take a snapshot, attach and detach removable media
5977	and so on.
5978
5979	<see>ISession</see>
5980	</desc>
5981
5982	<attribute name="machine" type="IMachine" readonly="yes">
5983	<desc>
5984	Machine object this console is sessioned with.
5985	<note>
5986	This is a convenience property, it has the same value as
5987	<link to="ISession::machine"/> of the corresponding session
5988	object.
5989	</note>
5990	</desc>
5991	</attribute>
5992
5993	<attribute name="state" type="MachineState" readonly="yes">
5994	<desc>
5995	Current execution state of the machine.
5996	<note>
5997	This property always returns the same value as the corresponding
5998	property of the IMachine object this console is sessioned with.
5999	For the process that owns (executes) the VM, this is the
6000	preferable way of querying the VM state, because no IPC
6001	calls are made.
6002	</note>
6003	</desc>
6004	</attribute>
6005
6006	<attribute name="guest" type="IGuest" readonly="yes">
6007	<desc>Guest object.</desc>
6008	</attribute>
6009
6010	<attribute name="keyboard" type="IKeyboard" readonly="yes">
6011	<desc>
6012	Virtual keyboard object.
6013	<note>
6014	If the machine is not running, any attempt to use
6015	the returned object will result in an error.
6016	</note>
6017	</desc>
6018	</attribute>
6019
6020	<attribute name="mouse" type="IMouse" readonly="yes">
6021	<desc>
6022	Virtual mouse object.
6023	<note>
6024	If the machine is not running, any attempt to use
6025	the returned object will result in an error.
6026	</note>
6027	</desc>
6028	</attribute>
6029
6030	<attribute name="display" type="IDisplay" readonly="yes">
6031	<desc>Virtual display object.
6032	<note>
6033	If the machine is not running, any attempt to use
6034	the returned object will result in an error.
6035	</note>
6036	</desc>
6037	</attribute>
6038
6039	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
6040	<desc>Debugging interface.</desc>
6041	</attribute>
6042
6043	<attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
6044	<desc>
6045	Collection of USB devices currently attached to the virtual
6046	USB controller.
6047	<note>
6048	The collection is empty if the machine is not running.
6049	</note>
6050	</desc>
6051	</attribute>
6052
6053	<attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6054	<desc>
6055	List of USB devices currently attached to the remote VRDP client.
6056	Once a new device is physically attached to the remote host computer,
6057	it appears in this list and remains there until detached.
6058	</desc>
6059	</attribute>
6060
6061	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
6062	<desc>
6063	Collection of shared folders for the current session. These folders
6064	are called transient shared folders because they are available to the
6065	guest OS running inside the associated virtual machine only for the
6066	duration of the session (as opposed to
6067	<link to="IMachine::sharedFolders"/> which represent permanent shared
6068	folders). When the session is closed (e.g. the machine is powered down),
6069	these folders are automatically discarded.
6070
6071	New shared folders are added to the collection using
6072	<link to="#createSharedFolder"/>. Existing shared folders can be
6073	removed using <link to="#removeSharedFolder"/>.
6074	</desc>
6075	</attribute>
6076
6077	<attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
6078	<desc>
6079	Interface that provides information on Remote Display (VRDP) connection.
6080	</desc>
6081	</attribute>
6082
6083	<method name="powerUp">
6084	<desc>
6085	Starts the virtual machine execution using the current machine
6086	state (that is, its current execution state, current settings and
6087	current hard disks).
6088
6089	If the machine is powered off or aborted, the execution will
6090	start from the beginning (as if the real hardware were just
6091	powered on).
6092
6093	If the machine is in the <link to="MachineState_Saved"/> state,
6094	it will continue its execution the point where the state has
6095	been saved.
6096
6097	<note>
6098	Unless you are trying to write a new VirtualBox front-end that
6099	performs direct machine execution (like the VirtualBox or VBoxSDL
6100	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
6101	session opened by <link to="IVirtualBox::openSession"/> and use this
6102	session only to change virtual machine settings. If you simply want to
6103	start virtual machine execution using one of the existing front-ends
6104	(for example the VirtualBox GUI or headless server), simply use
6105	<link to="IVirtualBox::openRemoteSession"/>; these front-ends will
6106	power up the machine automatically for you.
6107	</note>
6108
6109	<see>#saveState</see>
6110	<result name="VBOX_E_INVALID_VM_STATE">
6111	Virtual machine already running.
6112	</result>
6113	<result name="VBOX_E_HOST_ERROR">
6114	Host interface does not exist or name not set.
6115	</result>
6116	<result name="VBOX_E_FILE_ERROR">
6117	Invalid saved state file.
6118	</result>
6119	</desc>
6120	<param name="progress" type="IProgress" dir="return">
6121	<desc>Progress object to track the operation completion.</desc>
6122	</param>
6123	</method>
6124
6125	<method name="powerUpPaused">
6126	<desc>
6127	Identical to powerUp except that the VM will enter the
6128	<link to="MachineState_Paused"/> state, instead of
6129	<link to="MachineState_Running"/>.
6130
6131	<see>#powerUp</see>
6132	<result name="VBOX_E_INVALID_VM_STATE">
6133	Virtual machine already running.
6134	</result>
6135	<result name="VBOX_E_HOST_ERROR">
6136	Host interface does not exist or name not set.
6137	</result>
6138	<result name="VBOX_E_FILE_ERROR">
6139	Invalid saved state file.
6140	</result>
6141	</desc>
6142	<param name="progress" type="IProgress" dir="return">
6143	<desc>Progress object to track the operation completion.</desc>
6144	</param>
6145	</method>
6146
6147	<method name="powerDown">
6148	<desc>
6149	Initiates the power down procedure to stop the virtual machine
6150	execution.
6151
6152	The completion of the power down procedure is tracked using the returned
6153	IProgress object. After the operation is complete, the machine will go
6154	to the PoweredOff state.
6155	<result name="VBOX_E_INVALID_VM_STATE">
6156	Virtual machine must be Running, Paused or Stuck to be powered down.
6157	</result>
6158	</desc>
6159	<param name="progress" type="IProgress" dir="return">
6160	<desc>Progress object to track the operation completion.</desc>
6161	</param>
6162	</method>
6163
6164	<method name="reset">
6165	<desc>Resets the virtual machine.
6166	<result name="VBOX_E_INVALID_VM_STATE">
6167	Virtual machine not in Running state.
6168	</result>
6169	<result name="VBOX_E_VM_ERROR">
6170	Virtual machine error in reset operation.
6171	</result>
6172	</desc>
6173	</method>
6174
6175	<method name="pause">
6176	<desc>Pauses the virtual machine execution.
6177	<result name="VBOX_E_INVALID_VM_STATE">
6178	Virtual machine not in Running state.
6179	</result>
6180	<result name="VBOX_E_VM_ERROR">
6181	Virtual machine error in suspend operation.
6182	</result>
6183	</desc>
6184	</method>
6185
6186	<method name="resume">
6187	<desc>Resumes the virtual machine execution.
6188	<result name="VBOX_E_INVALID_VM_STATE">
6189	Virtual machine not in Paused state.
6190	</result>
6191	<result name="VBOX_E_VM_ERROR">
6192	Virtual machine error in resume operation.
6193	</result>
6194	</desc>
6195	</method>
6196
6197	<method name="powerButton">
6198	<desc>Sends the ACPI power button event to the guest.
6199	<result name="VBOX_E_INVALID_VM_STATE">
6200	Virtual machine not in Running state.
6201	</result>
6202	<result name="VBOX_E_PDM_ERROR">
6203	Controlled power off failed.
6204	</result>
6205	</desc>
6206	</method>
6207
6208	<method name="sleepButton">
6209	<desc>Sends the ACPI sleep button event to the guest.
6210	<result name="VBOX_E_INVALID_VM_STATE">
6211	Virtual machine not in Running state.
6212	</result>
6213	<result name="VBOX_E_PDM_ERROR">
6214	Sending sleep button event failed.
6215	</result>
6216	</desc>
6217	</method>
6218
6219	<method name="getPowerButtonHandled">
6220	<desc>Checks if the last power button event was handled by guest.
6221	<result name="VBOX_E_PDM_ERROR">
6222	Checking if the event was handled by the guest OS failed.
6223	</result>
6224	</desc>
6225	<param name="handled" type="boolean" dir="return"/>
6226	</method>
6227
6228	<method name="getGuestEnteredACPIMode">
6229	<desc>Checks if the guest entered the ACPI mode G0 (working) or
6230	G1 (sleeping). If this method returns @c false, the guest will
6231	most likely not respond to external ACPI events.
6232	<result name="VBOX_E_INVALID_VM_STATE">
6233	Virtual machine not in Running state.
6234	</result>
6235	</desc>
6236	<param name="entered" type="boolean" dir="return"/>
6237	</method>
6238
6239	<method name="saveState">
6240	<desc>
6241	Saves the current execution state of a running virtual machine
6242	and stops its execution.
6243
6244	After this operation completes, the machine will go to the
6245	Saved state. Next time it is powered up, this state will
6246	be restored and the machine will continue its execution from
6247	the place where it was saved.
6248
6249	This operation differs from taking a snapshot to the effect
6250	that it doesn't create new differencing media. Also, once
6251	the machine is powered up from the state saved using this method,
6252	the saved state is deleted, so it will be impossible to return
6253	to this state later.
6254
6255	<note>
6256	On success, this method implicitly calls
6257	<link to="IMachine::saveSettings"/> to save all current machine
6258	settings (including runtime changes to the DVD medium, etc.).
6259	Together with the impossibility to change any VM settings when it is
6260	in the Saved state, this guarantees adequate hardware
6261	configuration of the machine when it is restored from the saved
6262	state file.
6263	</note>
6264
6265	<note>
6266	The machine must be in the Running or Paused state, otherwise
6267	the operation will fail.
6268	</note>
6269	<result name="VBOX_E_INVALID_VM_STATE">
6270	Virtual machine state neither Running nor Paused.
6271	</result>
6272	<result name="VBOX_E_FILE_ERROR">
6273	Failed to create directory for saved state file.
6274	</result>
6275
6276	<see><link to="#takeSnapshot"/></see>
6277	</desc>
6278	<param name="progress" type="IProgress" dir="return">
6279	<desc>Progress object to track the operation completion.</desc>
6280	</param>
6281	</method>
6282
6283	<method name="adoptSavedState">
6284	<desc>
6285	Associates the given saved state file to the virtual machine.
6286
6287	On success, the machine will go to the Saved state. Next time it is
6288	powered up, it will be restored from the adopted saved state and
6289	continue execution from the place where the saved state file was
6290	created.
6291
6292	The specified saved state file path may be absolute or relative to the
6293	folder the VM normally saves the state to (usually,
6294	<link to="IMachine::snapshotFolder"/>).
6295
6296	<note>
6297	It's a caller's responsibility to make sure the given saved state
6298	file is compatible with the settings of this virtual machine that
6299	represent its virtual hardware (memory size, hard disk configuration
6300	etc.). If there is a mismatch, the behavior of the virtual machine
6301	is undefined.
6302	</note>
6303	<result name="VBOX_E_INVALID_VM_STATE">
6304	Virtual machine state neither PoweredOff nor Aborted.
6305	</result>
6306	</desc>
6307	<param name="savedStateFile" type="wstring" dir="in">
6308	<desc>Path to the saved state file to adopt.</desc>
6309	</param>
6310	</method>
6311
6312	<method name="forgetSavedState">
6313	<desc>
6314	Forgets the saved state of the virtual machine previously created
6315	by <link to="#saveState"/>. Next time the machine is powered up, a
6316	clean boot will occur. If @a remove is @c true the saved state file
6317	is deleted.
6318	<note>
6319	This operation is equivalent to resetting or powering off
6320	the machine without doing a proper shutdown in the guest OS.
6321	</note>
6322	<result name="VBOX_E_INVALID_VM_STATE">
6323	Virtual machine not in state Saved.
6324	</result>
6325	</desc>
6326	<param name="remove" type="boolean" dir="in">
6327	<desc>If @c true remove the saved state file.</desc>
6328	</param>
6329	</method>
6330
6331	<method name="getDeviceActivity">
6332	<desc>
6333	Gets the current activity type of a given device or device group.
6334	<result name="E_INVALIDARG">
6335	Invalid device type.
6336	</result>
6337	</desc>
6338	<param name="type" type="DeviceType" dir="in"/>
6339	<param name="activity" type="DeviceActivity" dir="return"/>
6340	</method>
6341
6342	<method name="attachUSBDevice">
6343	<desc>
6344	Attaches a host USB device with the given UUID to the
6345	USB controller of the virtual machine.
6346
6347	The device needs to be in one of the following states:
6348	<link to="USBDeviceState_Busy"/>,
6349	<link to="USBDeviceState_Available"/> or
6350	<link to="USBDeviceState_Held"/>,
6351	otherwise an error is immediately returned.
6352
6353	When the device state is
6354	<link to="USBDeviceState_Busy">Busy</link>, an error may also
6355	be returned if the host computer refuses to release it for some reason.
6356
6357	<see>IUSBController::deviceFilters, USBDeviceState</see>
6358	<result name="VBOX_E_INVALID_VM_STATE">
6359	Virtual machine state neither Running nor Paused.
6360	</result>
6361	<result name="VBOX_E_PDM_ERROR">
6362	Virtual machine does not have a USB controller.
6363	</result>
6364	</desc>
6365	<param name="id" type="uuid" mod="string" dir="in">
6366	<desc>UUID of the host USB device to attach.</desc>
6367	</param>
6368	</method>
6369
6370	<method name="detachUSBDevice">
6371	<desc>
6372	Detaches an USB device with the given UUID from the USB controller
6373	of the virtual machine.
6374
6375	After this method succeeds, the VirtualBox server re-initiates
6376	all USB filters as if the device were just physically attached
6377	to the host, but filters of this machine are ignored to avoid
6378	a possible automatic re-attachment.
6379
6380	<see>IUSBController::deviceFilters, USBDeviceState</see>
6381
6382	<result name="VBOX_E_PDM_ERROR">
6383	Virtual machine does not have a USB controller.
6384	</result>
6385	<result name="E_INVALIDARG">
6386	USB device not attached to this virtual machine.
6387	</result>
6388	</desc>
6389	<param name="id" type="uuid" mod="string" dir="in">
6390	<desc>UUID of the USB device to detach.</desc>
6391	</param>
6392	<param name="device" type="IUSBDevice" dir="return">
6393	<desc>Detached USB device.</desc>
6394	</param>
6395	</method>
6396
6397	<method name="findUSBDeviceByAddress">
6398	<desc>
6399	Searches for a USB device with the given host address.
6400
6401	<result name="VBOX_E_OBJECT_NOT_FOUND">
6402	Given @c name does not correspond to any USB device.
6403	</result>
6404
6405	<see>IUSBDevice::address</see>
6406	</desc>
6407	<param name="name" type="wstring" dir="in">
6408	<desc>
6409	Address of the USB device (as assigned by the host) to
6410	search for.
6411	</desc>
6412	</param>
6413	<param name="device" type="IUSBDevice" dir="return">
6414	<desc>Found USB device object.</desc>
6415	</param>
6416	</method>
6417
6418	<method name="findUSBDeviceById">
6419	<desc>
6420	Searches for a USB device with the given UUID.
6421
6422	<result name="VBOX_E_OBJECT_NOT_FOUND">
6423	Given @c id does not correspond to any USB device.
6424	</result>
6425
6426	<see>IUSBDevice::id</see>
6427	</desc>
6428	<param name="id" type="uuid" mod="string" dir="in">
6429	<desc>UUID of the USB device to search for.</desc>
6430	</param>
6431	<param name="device" type="IUSBDevice" dir="return">
6432	<desc>Found USB device object.</desc>
6433	</param>
6434	</method>
6435
6436	<method name="createSharedFolder">
6437	<desc>
6438	Creates a transient new shared folder by associating the given logical
6439	name with the given host path, adds it to the collection of shared
6440	folders and starts sharing it. Refer to the description of
6441	<link to="ISharedFolder"/> to read more about logical names.
6442
6443	<result name="VBOX_E_INVALID_VM_STATE">
6444	Virtual machine in Saved state or currently changing state.
6445	</result>
6446	<result name="VBOX_E_FILE_ERROR">
6447	Shared folder already exists or not accessible.
6448	</result>
6449	</desc>
6450	<param name="name" type="wstring" dir="in">
6451	<desc>Unique logical name of the shared folder.</desc>
6452	</param>
6453	<param name="hostPath" type="wstring" dir="in">
6454	<desc>Full path to the shared folder in the host file system.</desc>
6455	</param>
6456	<param name="writable" type="boolean" dir="in">
6457	<desc>Whether the share is writable or readonly</desc>
6458	</param>
6459	</method>
6460
6461	<method name="removeSharedFolder">
6462	<desc>
6463	Removes a transient shared folder with the given name previously
6464	created by <link to="#createSharedFolder"/> from the collection of
6465	shared folders and stops sharing it.
6466	<result name="VBOX_E_INVALID_VM_STATE">
6467	Virtual machine in Saved state or currently changing state.
6468	</result>
6469	<result name="VBOX_E_FILE_ERROR">
6470	Shared folder does not exists.
6471	</result>
6472	</desc>
6473	<param name="name" type="wstring" dir="in">
6474	<desc>Logical name of the shared folder to remove.</desc>
6475	</param>
6476	</method>
6477
6478	<method name="takeSnapshot">
6479	<desc>
6480	Saves the current execution state
6481	and all settings of the machine and creates differencing images
6482	for all normal (non-independent) media.
6483	See <link to="ISnapshot" /> for an introduction to snapshots.
6484
6485	This method can be called for a PoweredOff, Saved (see
6486	<link to="#saveState"/>), Running or
6487	Paused virtual machine. When the machine is PoweredOff, an
6488	offline snapshot is created. When the machine is Running a live
6489	snapshot is created, and an online snapshot is is created when Paused.
6490
6491	The taken snapshot is always based on the
6492	<link to="IMachine::currentSnapshot">current snapshot</link>
6493	of the associated virtual machine and becomes a new current snapshot.
6494
6495	<note>
6496	This method implicitly calls <link to="IMachine::saveSettings"/> to
6497	save all current machine settings before taking an offline snapshot.
6498	</note>
6499
6500	<result name="VBOX_E_INVALID_VM_STATE">
6501	Virtual machine currently changing state.
6502	</result>
6503	</desc>
6504	<param name="name" type="wstring" dir="in">
6505	<desc>Short name for the snapshot.</desc>
6506	</param>
6507	<param name="description" type="wstring" dir="in">
6508	<desc>Optional description of the snapshot.</desc>
6509	</param>
6510	<param name="progress" type="IProgress" dir="return">
6511	<desc>Progress object to track the operation completion.</desc>
6512	</param>
6513	</method>
6514
6515	<method name="discardSnapshot">
6516	<desc>
6517	Starts discarding the specified snapshot asynchronously.
6518	See <link to="ISnapshot" /> for an introduction to snapshots.
6519
6520	The execution state
6521	and settings of the associated machine stored in the snapshot
6522	will be deleted. The contents of all differencing media of
6523	this snapshot will be merged with the contents of their
6524	dependent child media to keep the disks valid (in other
6525	words, all changes represented by media being discarded
6526	will be propagated to their child medium). After that, this
6527	snapshot's differencing medium will be deleted. The parent
6528	of this snapshot will become a new parent for all its child
6529	snapshots.
6530
6531	If the discarded snapshot is the current one, its parent
6532	snapshot will become a new current snapshot. The current machine
6533	state is not directly affected in this case, except that
6534	currently attached differencing media based on media
6535	of the discarded snapshot will be also merged as described
6536	above.
6537
6538	If the discarded snapshot is the first one (the root snapshot)
6539	and it has exactly one child snapshot, this child snapshot will
6540	become the first snapshot after discarding. If there are no
6541	children at all (i.e. the first snapshot is the only snapshot of
6542	the machine), both the current and the first snapshot of the
6543	machine will be set to @c null. In all other cases, the first
6544	snapshot cannot be discarded.
6545
6546	You cannot discard the snapshot if it
6547	stores <link to="MediumType_Normal">normal</link> (non-differencing)
6548	media that have differencing media based on them. Snapshots of
6549	such kind can be discarded only when every normal medium has either
6550	no children at all or exactly one child. In the former case, the normal
6551	medium simply becomes unused (i.e. not attached to any VM). In the
6552	latter case, it receives all the changes stored in the child medium,
6553	and then it replaces the child medium in the configuration of the
6554	corresponding snapshot or machine.
6555
6556	Also, you cannot discard the snapshot if it stores media
6557	(of any type) having differencing child media that belong
6558	to other machines. Such snapshots can be only discarded after
6559	you discard all snapshots of other machines containing "foreign"
6560	child disks, or detach these "foreign" child disks from machines
6561	they are attached to.
6562
6563	One particular example of the snapshot storing normal media
6564	is the first snapshot of a virtual machine that had normal media
6565	attached when taking the snapshot. Be careful when
6566	discarding such snapshots because this implicitly commits
6567	changes (made since the snapshot being discarded has been taken)
6568	to normal media (as described above), which may be not what
6569	you want.
6570
6571	The virtual machine is put to
6572	the <link to="MachineState_Discarding">Discarding</link> state until
6573	the discard operation is completed.
6574
6575	<note>
6576	The machine must not be running, otherwise the operation
6577	will fail.
6578	</note>
6579
6580	<note>
6581	Child media of all normal media of the discarded snapshot
6582	must be accessible (see <link to="IMedium::state"/>) for this
6583	operation to succeed. In particular, this means that all virtual
6584	machines, whose media are directly or indirectly based on the
6585	media of discarded snapshot, must be powered off.
6586	</note>
6587	<note>
6588	Merging medium contents can be very time and disk space
6589	consuming, if these disks are big in size and have many
6590	children. However, if the snapshot being discarded is the last
6591	(head) snapshot on the branch, the operation will be rather
6592	quick.
6593	</note>
6594	<note>
6595	Note that discarding the current snapshot
6596	will implicitly call <link to="IMachine::saveSettings"/> to
6597	make all current machine settings permanent.
6598	</note>
6599	<result name="VBOX_E_INVALID_VM_STATE">
6600	Virtual machine is running.
6601	</result>
6602	</desc>
6603	<param name="id" type="uuid" mod="string" dir="in">
6604	<desc>UUID of the snapshot to discard.</desc>
6605	</param>
6606	<param name="progress" type="IProgress" dir="return">
6607	<desc>Progress object to track the operation completion.</desc>
6608	</param>
6609	</method>
6610
6611	<method name="discardCurrentState">
6612	<desc>
6613	Starts resetting the machine's current state to the state contained
6614	in the current snapshot, asynchronously. All current settings of the
6615	machine will be reset and changes stored in differencing media
6616	will be lost.
6617	See <link to="ISnapshot" /> for an introduction to snapshots.
6618
6619	After this operation is successfully completed, new empty differencing
6620	media are created for all normal media of the machine.
6621
6622	If the current snapshot of the machine is an online snapshot, the
6623	machine will go to the <link to="MachineState_Saved"> saved
6624	state</link>, so that the next time it is powered on, the execution
6625	state will be restored from the current snapshot.
6626
6627	<note>
6628	The machine must not be running, otherwise the operation will fail.
6629	</note>
6630
6631	<note>
6632	If the machine state is <link to="MachineState_Saved">Saved</link>
6633	prior to this operation, the saved state file will be implicitly
6634	discarded (as if <link to="IConsole::forgetSavedState"/> were
6635	called).
6636	</note>
6637
6638	<result name="VBOX_E_INVALID_VM_STATE">
6639	Virtual machine is running.
6640	</result>
6641	</desc>
6642	<param name="progress" type="IProgress" dir="return">
6643	<desc>Progress object to track the operation completion.</desc>
6644	</param>
6645	</method>
6646
6647	<method name="discardCurrentSnapshotAndState">
6648	<desc>
6649
6650	This method is equivalent to
6651	doing <link to="IConsole::discardSnapshot">discardSnapshot</link>
6652	(currentSnapshot.id(), progress) followed by
6653	<link to="IConsole::discardCurrentState"/>.
6654
6655	As a result, the machine will be fully restored from the
6656	snapshot preceding the current snapshot, while both the current
6657	snapshot and the current machine state will be discarded.
6658
6659	If the current snapshot is the first snapshot of the machine (i.e. it
6660	has the only snapshot), the current machine state will be
6661	discarded <b>before</b> discarding the snapshot. In other words, the
6662	machine will be restored from its last snapshot, before discarding
6663	it. This differs from performing a single
6664	<link to="IConsole::discardSnapshot"/> call (note that no
6665	<link to="IConsole::discardCurrentState"/> will be possible after it)
6666	to the effect that the latter will preserve the current state instead of
6667	discarding it.
6668
6669	Unless explicitly mentioned otherwise, all remarks and
6670	limitations of the above two methods also apply to this method.
6671
6672	<note>
6673	The machine must not be running, otherwise the operation
6674	will fail.
6675	</note>
6676
6677	<note>
6678	If the machine state is <link to="MachineState_Saved">Saved</link>
6679	prior to this operation, the saved state file will be implicitly
6680	discarded (as if <link to="#forgetSavedState"/> were
6681	called).
6682	</note>
6683
6684	<note>
6685	This method is more efficient than calling both of the above
6686	methods separately: it requires less IPC calls and provides
6687	a single progress object.
6688	</note>
6689
6690	<result name="VBOX_E_INVALID_VM_STATE">
6691	Virtual machine is running.
6692	</result>
6693	</desc>
6694	<param name="progress" type="IProgress" dir="return">
6695	<desc>Progress object to track the operation completion.</desc>
6696	</param>
6697	</method>
6698
6699	<method name="migrate">
6700	<desc>
6701	Migrate the VM to a different host machine.
6702
6703	TODO explain the details.
6704
6705	<result name="VBOX_E_INVALID_VM_STATE">
6706	Virtual machine not running or paused.
6707	</result>
6708	</desc>
6709	<param name="hostname" type="wstring" dir="in">
6710	<desc>The name or IP of the host to migrate to.</desc>
6711	</param>
6712	<param name="tcpport" type="unsigned long" dir="in">
6713	<desc>The TCP port to connect to (1..65535).</desc>
6714	</param>
6715	<param name="password" type="wstring" dir="in">
6716	<desc>The password.</desc>
6717	</param>
6718	<param name="progress" type="IProgress" dir="return">
6719	<desc>Progress object to track the operation completion.</desc>
6720	</param>
6721	</method>
6722
6723	<method name="registerCallback">
6724	<desc>
6725	Registers a new console callback on this instance. The methods of the
6726	callback interface will be called by this instance when the appropriate
6727	event occurs.
6728	</desc>
6729	<param name="callback" type="IConsoleCallback" dir="in"/>
6730	</method>
6731
6732	<method name="unregisterCallback">
6733	<desc>
6734	Unregisters the console callback previously registered using
6735	<link to="#registerCallback"/>.
6736	<result name="E_INVALIDARG">
6737	Given @a callback handler is not registered.
6738	</result>
6739	</desc>
6740	<param name="callback" type="IConsoleCallback" dir="in"/>
6741	</method>
6742	</interface>
6743
6744	<!--
6745	// IHost
6746	/////////////////////////////////////////////////////////////////////////
6747	-->
6748
6749	<enum
6750	name="HostNetworkInterfaceMediumType"
6751	uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
6752	>
6753	<desc>
6754	Type of encapsulation. Ethernet encapsulation includes both wired and
6755	wireless Ethernet connections.
6756	<see>IHostNetworkInterface</see>
6757	</desc>
6758
6759	<const name="Unknown" value="0">
6760	<desc>
6761	The type of interface cannot be determined.
6762	</desc>
6763	</const>
6764	<const name="Ethernet" value="1">
6765	<desc>
6766	Ethernet frame encapsulation.
6767	</desc>
6768	</const>
6769	<const name="PPP" value="2">
6770	<desc>
6771	Point-to-point protocol encapsulation.
6772	</desc>
6773	</const>
6774	<const name="SLIP" value="3">
6775	<desc>
6776	Serial line IP encapsulation.
6777	</desc>
6778	</const>
6779	</enum>
6780
6781	<enum
6782	name="HostNetworkInterfaceStatus"
6783	uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
6784	>
6785	<desc>
6786	Current status of the interface.
6787	<see>IHostNetworkInterface</see>
6788	</desc>
6789
6790	<const name="Unknown" value="0">
6791	<desc>
6792	The state of interface cannot be determined.
6793	</desc>
6794	</const>
6795	<const name="Up" value="1">
6796	<desc>
6797	The interface is fully operational.
6798	</desc>
6799	</const>
6800	<const name="Down" value="2">
6801	<desc>
6802	The interface is not functioning.
6803	</desc>
6804	</const>
6805	</enum>
6806
6807	<enum
6808	name="HostNetworkInterfaceType"
6809	uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
6810	>
6811	<desc>
6812	Network interface type.
6813	</desc>
6814	<const name="Bridged" value="1"/>
6815	<const name="HostOnly" value="2"/>
6816	</enum>
6817
6818	<interface
6819	name="IHostNetworkInterface" extends="$unknown"
6820	uuid="ce6fae58-7642-4102-b5db-c9005c2320a8"
6821	wsmap="managed"
6822	>
6823	<desc>
6824	Represents one of host's network interfaces. IP V6 address and network
6825	mask are strings of 32 hexdecimal digits grouped by four. Groups are
6826	separated by colons.
6827	For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
6828	</desc>
6829	<attribute name="name" type="wstring" readonly="yes">
6830	<desc>Returns the host network interface name.</desc>
6831	</attribute>
6832
6833	<attribute name="id" type="uuid" mod="string" readonly="yes">
6834	<desc>Returns the interface UUID.</desc>
6835	</attribute>
6836
6837	<attribute name="networkName" type="wstring" readonly="yes">
6838	<desc>Returns the name of a virtual network the interface gets attached to.</desc>
6839	</attribute>
6840
6841	<attribute name="dhcpEnabled" type="boolean" readonly="yes">
6842	<desc>Specifies whether the DHCP is enabled for the interface.</desc>
6843	</attribute>
6844
6845	<attribute name="IPAddress" type="wstring" readonly="yes">
6846	<desc>Returns the IP V4 address of the interface.</desc>
6847	</attribute>
6848
6849	<attribute name="networkMask" type="wstring" readonly="yes">
6850	<desc>Returns the network mask of the interface.</desc>
6851	</attribute>
6852
6853	<attribute name="IPV6Supported" type="boolean" readonly="yes">
6854	<desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
6855	</attribute>
6856
6857	<attribute name="IPV6Address" type="wstring" readonly="yes">
6858	<desc>Returns the IP V6 address of the interface.</desc>
6859	</attribute>
6860
6861	<attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
6862	<desc>Returns the length IP V6 network mask prefix of the interface.</desc>
6863	</attribute>
6864
6865	<attribute name="hardwareAddress" type="wstring" readonly="yes">
6866	<desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
6867	</attribute>
6868
6869	<attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
6870	<desc>Type of protocol encapsulation used.</desc>
6871	</attribute>
6872
6873	<attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
6874	<desc>Status of the interface.</desc>
6875	</attribute>
6876
6877	<attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
6878	<desc>specifies the host interface type.</desc>
6879	</attribute>
6880
6881	<method name="enableStaticIpConfig">
6882	<desc>sets and enables the static IP V4 configuration for the given interface.</desc>
6883	<param name="IPAddress" type="wstring" dir="in">
6884	<desc>
6885	IP address.
6886	</desc>
6887	</param>
6888	<param name="networkMask" type="wstring" dir="in">
6889	<desc>
6890	network mask.
6891	</desc>
6892	</param>
6893	</method>
6894
6895	<method name="enableStaticIpConfigV6">
6896	<desc>sets and enables the static IP V6 configuration for the given interface.</desc>
6897	<param name="IPV6Address" type="wstring" dir="in">
6898	<desc>
6899	IP address.
6900	</desc>
6901	</param>
6902	<param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
6903	<desc>
6904	network mask.
6905	</desc>
6906	</param>
6907	</method>
6908
6909	<method name="enableDynamicIpConfig">
6910	<desc>enables the dynamic IP configuration.</desc>
6911	</method>
6912
6913	<method name="dhcpRediscover">
6914	<desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
6915	</method>
6916
6917	</interface>
6918
6919	<interface
6920	name="IHost" extends="$unknown"
6921	uuid="95522f11-1ecc-443b-9242-3af6b24d430c"
6922	wsmap="managed"
6923	>
6924	<desc>
6925	The IHost interface represents the physical machine that this VirtualBox
6926	installation runs on.
6927
6928	An object implementing this interface is returned by the
6929	<link to="IVirtualBox::host" /> attribute. This interface contains
6930	read-only information about the host's physical hardware (such as what
6931	processors and disks are available, what the host operating system is,
6932	and so on) and also allows for manipulating some of the host's hardware,
6933	such as global USB device filters and host interface networking.
6934
6935	</desc>
6936	<attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
6937	<desc>List of DVD drives available on the host.</desc>
6938	</attribute>
6939
6940	<attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
6941	<desc>List of floppy drives available on the host.</desc>
6942	</attribute>
6943
6944	<attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6945	<desc>
6946	List of USB devices currently attached to the host.
6947	Once a new device is physically attached to the host computer,
6948	it appears in this list and remains there until detached.
6949
6950	<note>
6951	If USB functionality is not available in the given edition of
6952	VirtualBox, this method will set the result code to @c E_NOTIMPL.
6953	</note>
6954	</desc>
6955	</attribute>
6956
6957	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
6958	<desc>
6959	List of USB device filters in action.
6960	When a new device is physically attached to the host computer,
6961	filters from this list are applied to it (in order they are stored
6962	in the list). The first matched filter will determine the
6963	<link to="IHostUSBDeviceFilter::action">action</link>
6964	performed on the device.
6965
6966	Unless the device is ignored by these filters, filters of all
6967	currently running virtual machines
6968	(<link to="IUSBController::deviceFilters"/>) are applied to it.
6969
6970	<note>
6971	If USB functionality is not available in the given edition of
6972	VirtualBox, this method will set the result code to @c E_NOTIMPL.
6973	</note>
6974
6975	<see>IHostUSBDeviceFilter, USBDeviceState</see>
6976	</desc>
6977	</attribute>
6978
6979	<attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
6980	<desc>List of host network interfaces currently defined on the host.</desc>
6981	</attribute>
6982
6983	<attribute name="processorCount" type="unsigned long" readonly="yes">
6984	<desc>Number of (logical) CPUs installed in the host system.</desc>
6985	</attribute>
6986
6987	<attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
6988	<desc>Number of (logical) CPUs online in the host system.</desc>
6989	</attribute>
6990
6991	<method name="getProcessorSpeed">
6992	<desc>Query the (approximate) maximum speed of a specified host CPU in
6993	Megahertz.
6994	</desc>
6995	<param name="cpuId" type="unsigned long" dir="in">
6996	<desc>
6997	Identifier of the CPU.
6998	</desc>
6999	</param>
7000	<param name="speed" type="unsigned long" dir="return">
7001	<desc>
7002	Speed value. 0 is returned if value is not known or @a cpuId is
7003	invalid.
7004	</desc>
7005	</param>
7006	</method>
7007
7008	<method name="getProcessorFeature">
7009	<desc>Query whether a CPU feature is supported or not.</desc>
7010	<param name="feature" type="ProcessorFeature" dir="in">
7011	<desc>
7012	CPU Feature identifier.
7013	</desc>
7014	</param>
7015	<param name="supported" type="boolean" dir="return">
7016	<desc>
7017	Feature is supported or not.
7018	</desc>
7019	</param>
7020	</method>
7021
7022	<method name="getProcessorDescription">
7023	<desc>Query the model string of a specified host CPU.
7024	</desc>
7025	<param name="cpuId" type="unsigned long" dir="in">
7026	<desc>
7027	Identifier of the CPU.
7028	</desc>
7029	</param>
7030	<param name="description" type="wstring" dir="return">
7031	<desc>
7032	Model string. An empty string is returned if value is not known or
7033	@a cpuId is invalid.
7034	</desc>
7035	</param>
7036	</method>
7037
7038	<attribute name="memorySize" type="unsigned long" readonly="yes">
7039	<desc>Amount of system memory in megabytes installed in the host system.</desc>
7040	</attribute>
7041
7042	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
7043	<desc>Available system memory in the host system.</desc>
7044	</attribute>
7045
7046	<attribute name="operatingSystem" type="wstring" readonly="yes">
7047	<desc>Name of the host system's operating system.</desc>
7048	</attribute>
7049
7050	<attribute name="OSVersion" type="wstring" readonly="yes">
7051	<desc>Host operating system's version string.</desc>
7052	</attribute>
7053
7054	<attribute name="UTCTime" type="long long" readonly="yes">
7055	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
7056	</attribute>
7057
7058	<attribute name="Acceleration3DAvailable" type="boolean" readonly="yes">
7059	<desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
7060	</attribute>
7061
7062	<method name="createHostOnlyNetworkInterface">
7063	<desc>
7064	Creates a new adapter for Host Only Networking.
7065	<result name="E_INVALIDARG">
7066	Host network interface @a name already exists.
7067	</result>
7068	</desc>
7069	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
7070	<desc>
7071	Created host interface object.
7072	</desc>
7073	</param>
7074	<param name="progress" type="IProgress" dir="return">
7075	<desc>
7076	Progress object to track the operation completion.
7077	</desc>
7078	</param>
7079	</method>
7080
7081	<method name="removeHostOnlyNetworkInterface">
7082	<desc>
7083	Removes the given Host Only Networking interface.
7084	<result name="VBOX_E_OBJECT_NOT_FOUND">
7085	No host network interface matching @a id found.
7086	</result>
7087	</desc>
7088	<param name="id" type="uuid" mod="string" dir="in">
7089	<desc>
7090	Adapter GUID.
7091	</desc>
7092	</param>
7093	<param name="progress" type="IProgress" dir="return">
7094	<desc>
7095	Progress object to track the operation completion.
7096	</desc>
7097	</param>
7098	</method>
7099
7100	<method name="createUSBDeviceFilter">
7101	<desc>
7102	Creates a new USB device filter. All attributes except
7103	the filter name are set to empty (any match),
7104	<i>active</i> is @c false (the filter is not active).
7105
7106	The created filter can be added to the list of filters using
7107	<link to="#insertUSBDeviceFilter"/>.
7108
7109	<see>#USBDeviceFilters</see>
7110	</desc>
7111	<param name="name" type="wstring" dir="in">
7112	<desc>
7113	Filter name. See <link to="IHostUSBDeviceFilter::name"/>
7114	for more info.
7115	</desc>
7116	</param>
7117	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
7118	<desc>Created filter object.</desc>
7119	</param>
7120	</method>
7121
7122	<method name="insertUSBDeviceFilter">
7123	<desc>
7124	Inserts the given USB device to the specified position
7125	in the list of filters.
7126
7127	Positions are numbered starting from @c 0. If the specified
7128	position is equal to or greater than the number of elements in
7129	the list, the filter is added at the end of the collection.
7130
7131	<note>
7132	Duplicates are not allowed, so an attempt to insert a
7133	filter already in the list is an error.
7134	</note>
7135	<note>
7136	If USB functionality is not available in the given edition of
7137	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7138	</note>
7139
7140	<see>#USBDeviceFilters</see>
7141
7142	<result name="VBOX_E_INVALID_OBJECT_STATE">
7143	USB device filter is not created within this VirtualBox instance.
7144	</result>
7145	<result name="E_INVALIDARG">
7146	USB device filter already in list.
7147	</result>
7148
7149	</desc>
7150	<param name="position" type="unsigned long" dir="in">
7151	<desc>Position to insert the filter to.</desc>
7152	</param>
7153	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
7154	<desc>USB device filter to insert.</desc>
7155	</param>
7156	</method>
7157
7158	<method name="removeUSBDeviceFilter">
7159	<desc>
7160	Removes a USB device filter from the specified position in the
7161	list of filters.
7162
7163	Positions are numbered starting from @c 0. Specifying a
7164	position equal to or greater than the number of elements in
7165	the list will produce an error.
7166
7167	<note>
7168	If USB functionality is not available in the given edition of
7169	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7170	</note>
7171
7172	<see>#USBDeviceFilters</see>
7173
7174	<result name="E_INVALIDARG">
7175	USB device filter list empty or invalid @a position.
7176	</result>
7177
7178	</desc>
7179	<param name="position" type="unsigned long" dir="in">
7180	<desc>Position to remove the filter from.</desc>
7181	</param>
7182	</method>
7183
7184	<method name="findHostDVDDrive">
7185	<desc>
7186	Searches for a host DVD drive with the given @c name.
7187
7188	<result name="VBOX_E_OBJECT_NOT_FOUND">
7189	Given @c name does not correspond to any host drive.
7190	</result>
7191
7192	</desc>
7193	<param name="name" type="wstring" dir="in">
7194	<desc>Name of the host drive to search for</desc>
7195	</param>
7196	<param name="drive" type="IMedium" dir="return">
7197	<desc>Found host drive object</desc>
7198	</param>
7199	</method>
7200
7201	<method name="findHostFloppyDrive">
7202	<desc>
7203	Searches for a host floppy drive with the given @c name.
7204
7205	<result name="VBOX_E_OBJECT_NOT_FOUND">
7206	Given @c name does not correspond to any host floppy drive.
7207	</result>
7208
7209	</desc>
7210	<param name="name" type="wstring" dir="in">
7211	<desc>Name of the host floppy drive to search for</desc>
7212	</param>
7213	<param name="drive" type="IMedium" dir="return">
7214	<desc>Found host floppy drive object</desc>
7215	</param>
7216	</method>
7217
7218	<method name="findHostNetworkInterfaceByName">
7219	<desc>
7220	Searches through all host network interfaces for an interface with
7221	the given @c name.
7222	<note>
7223	The method returns an error if the given @c name does not
7224	correspond to any host network interface.
7225	</note>
7226	</desc>
7227	<param name="name" type="wstring" dir="in">
7228	<desc>Name of the host network interface to search for.</desc>
7229	</param>
7230	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
7231	<desc>Found host network interface object.</desc>
7232	</param>
7233	</method>
7234	<method name="findHostNetworkInterfaceById">
7235	<desc>
7236	Searches through all host network interfaces for an interface with
7237	the given GUID.
7238	<note>
7239	The method returns an error if the given GUID does not
7240	correspond to any host network interface.
7241	</note>
7242	</desc>
7243	<param name="id" type="uuid" mod="string" dir="in">
7244	<desc>GUID of the host network interface to search for.</desc>
7245	</param>
7246	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
7247	<desc>Found host network interface object.</desc>
7248	</param>
7249	</method>
7250	<method name="findHostNetworkInterfacesOfType">
7251	<desc>
7252	Searches through all host network interfaces and returns a list of interfaces of the specified type
7253	</desc>
7254	<param name="type" type="HostNetworkInterfaceType" dir="in">
7255	<desc>type of the host network interfaces to search for.</desc>
7256	</param>
7257	<param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
7258	<desc>Found host network interface objects.</desc>
7259	</param>
7260	</method>
7261
7262	<method name="findUSBDeviceById">
7263	<desc>
7264	Searches for a USB device with the given UUID.
7265
7266	<result name="VBOX_E_OBJECT_NOT_FOUND">
7267	Given @c id does not correspond to any USB device.
7268	</result>
7269
7270	<see>IHostUSBDevice::id</see>
7271	</desc>
7272	<param name="id" type="uuid" mod="string" dir="in">
7273	<desc>UUID of the USB device to search for.</desc>
7274	</param>
7275	<param name="device" type="IHostUSBDevice" dir="return">
7276	<desc>Found USB device object.</desc>
7277	</param>
7278	</method>
7279
7280	<method name="findUSBDeviceByAddress">
7281	<desc>
7282	Searches for a USB device with the given host address.
7283
7284	<result name="VBOX_E_OBJECT_NOT_FOUND">
7285	Given @c name does not correspond to any USB device.
7286	</result>
7287
7288	<see>IHostUSBDevice::address</see>
7289	</desc>
7290	<param name="name" type="wstring" dir="in">
7291	<desc>
7292	Address of the USB device (as assigned by the host) to
7293	search for.
7294	</desc>
7295	</param>
7296	<param name="device" type="IHostUSBDevice" dir="return">
7297	<desc>Found USB device object.</desc>
7298	</param>
7299	</method>
7300
7301	</interface>
7302
7303	<!--
7304	// ISystemProperties
7305	/////////////////////////////////////////////////////////////////////////
7306	-->
7307
7308	<interface
7309	name="ISystemProperties"
7310	extends="$unknown"
7311	uuid="4b78105a-d066-4eab-ae48-ccb2c0ba5057"
7312	wsmap="managed"
7313	>
7314	<desc>
7315	The ISystemProperties interface represents global properties of the given
7316	VirtualBox installation.
7317
7318	These properties define limits and default values for various attributes
7319	and parameters. Most of the properties are read-only, but some can be
7320	changed by a user.
7321	</desc>
7322
7323	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
7324	<desc>Minimum guest system memory in Megabytes.</desc>
7325	</attribute>
7326
7327	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
7328	<desc>Maximum guest system memory in Megabytes.</desc>
7329	</attribute>
7330
7331	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
7332	<desc>Minimum guest video memory in Megabytes.</desc>
7333	</attribute>
7334
7335	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
7336	<desc>Maximum guest video memory in Megabytes.</desc>
7337	</attribute>
7338
7339	<attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
7340	<desc>Minimum CPU count.</desc>
7341	</attribute>
7342
7343	<attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
7344	<desc>Maximum CPU count.</desc>
7345	</attribute>
7346
7347	<attribute name="maxVDISize" type="unsigned long long" readonly="yes">
7348	<desc>Maximum size of a virtual disk image in Megabytes.</desc>
7349	</attribute>
7350
7351	<attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
7352	<desc>
7353	Number of network adapters associated with every
7354	<link to="IMachine"/> instance.
7355	</desc>
7356	</attribute>
7357
7358	<attribute name="serialPortCount" type="unsigned long" readonly="yes">
7359	<desc>
7360	Number of serial ports associated with every
7361	<link to="IMachine"/> instance.
7362	</desc>
7363	</attribute>
7364
7365	<attribute name="parallelPortCount" type="unsigned long" readonly="yes">
7366	<desc>
7367	Number of parallel ports associated with every
7368	<link to="IMachine"/> instance.
7369	</desc>
7370	</attribute>
7371
7372	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
7373	<desc>
7374	Maximum device position in the boot order. This value corresponds
7375	to the total number of devices a machine can boot from, to make it
7376	possible to include all possible devices to the boot list.
7377	<see><link to="IMachine::setBootOrder"/></see>
7378	</desc>
7379	</attribute>
7380
7381	<attribute name="defaultMachineFolder" type="wstring">
7382	<desc>
7383	Full path to the default directory used to create new or open
7384	existing machines when a settings file name contains no
7385	path.
7386
7387	The initial value of this property is
7388	<tt><</tt><link to="IVirtualBox::homeFolder">
7389	VirtualBox_home</link><tt>>/Machines</tt>.
7390
7391	<note>
7392	Setting this property to @c null or an empty string will restore the
7393	initial value.
7394	</note>
7395	<note>
7396	When settings this property, the specified path can be
7397	absolute (full path) or relative
7398	to the <link to="IVirtualBox::homeFolder">
7399	VirtualBox home directory</link>.
7400	When reading this property, a full path is
7401	always returned.
7402	</note>
7403	<note>
7404	The specified path may not exist, it will be created
7405	when necessary.
7406	</note>
7407
7408	<see>
7409	<link to="IVirtualBox::createMachine"/>,
7410	<link to="IVirtualBox::openMachine"/>
7411	</see>
7412	</desc>
7413	</attribute>
7414
7415	<attribute name="defaultHardDiskFolder" type="wstring">
7416	<desc>
7417	Full path to the default directory used to create new or open existing
7418	virtual disks.
7419
7420	This path is used when the storage unit of a hard disk is a regular file
7421	in the host's file system and only a file name that contains no path is
7422	given.
7423
7424	The initial value of this property is
7425	<tt><</tt>
7426	<link to="IVirtualBox::homeFolder">VirtualBox_home</link>
7427	<tt>>/HardDisks</tt>.
7428
7429	<note>
7430	Setting this property to @c null or empty string will restore the
7431	initial value.
7432	</note>
7433	<note>
7434	When settings this property, the specified path can be relative
7435	to the
7436	<link to="IVirtualBox::homeFolder">VirtualBox home directory</link> or
7437	absolute. When reading this property, a full path is
7438	always returned.
7439	</note>
7440	<note>
7441	The specified path may not exist, it will be created
7442	when necessary.
7443	</note>
7444
7445	<see>
7446	IMedium,
7447	<link to="IVirtualBox::createHardDisk"/>,
7448	<link to="IVirtualBox::openHardDisk"/>,
7449	<link to="IMedium::location"/>
7450	</see>
7451	</desc>
7452	</attribute>
7453
7454	<attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
7455	<desc>
7456	List of all medium storage formats supported by this VirtualBox
7457	installation.
7458
7459	Keep in mind that the medium format identifier
7460	(<link to="IMediumFormat::id"/>) used in other API calls like
7461	<link to="IVirtualBox::createHardDisk"/> to refer to a particular
7462	medium format is a case-insensitive string. This means that, for
7463	example, all of the following strings:
7464	<pre>
7465	"VDI"
7466	"vdi"
7467	"VdI"</pre>
7468	refer to the same medium format.
7469
7470	Note that the virtual medium framework is backend-based, therefore
7471	the list of supported formats depends on what backends are currently
7472	installed.
7473
7474	<see>
7475	<link to="IMediumFormat"/>,
7476	</see>
7477	</desc>
7478	</attribute>
7479
7480	<attribute name="defaultHardDiskFormat" type="wstring">
7481	<desc>
7482	Identifier of the default medium format used by VirtualBox.
7483
7484	The medium format set by this attribute is used by VirtualBox
7485	when the medium format was not specified explicitly. One example is
7486	<link to="IVirtualBox::createHardDisk"/> with the empty
7487	format argument. A more complex example is implicit creation of
7488	differencing media when taking a snapshot of a virtual machine:
7489	this operation will try to use a format of the parent medium first
7490	and if this format does not support differencing media the default
7491	format specified by this argument will be used.
7492
7493	The list of supported medium formats may be obtained by the
7494	<link to="#mediaFormats"/> call. Note that the default medium
7495	format must have a capability to create differencing media;
7496	otherwise operations that create media implicitly may fail
7497	unexpectedly.
7498
7499	The initial value of this property is <tt>"VDI"</tt> in the current
7500	version of the VirtualBox product, but may change in the future.
7501
7502	<note>
7503	Setting this property to @c null or empty string will restore the
7504	initial value.
7505	</note>
7506
7507	<see>
7508	<link to="#mediaFormats"/>,
7509	<link to="IMediumFormat::id"/>,
7510	<link to="IVirtualBox::createHardDisk"/>
7511	</see>
7512	</desc>
7513	</attribute>
7514
7515	<attribute name="remoteDisplayAuthLibrary" type="wstring">
7516	<desc>
7517	Library that provides authentication for VRDP clients. The library
7518	is used if a virtual machine's authentication type is set to "external"
7519	in the VM RemoteDisplay configuration.
7520
7521	The system library extension (".DLL" or ".so") must be omitted.
7522	A full path can be specified; if not, then the library must reside on the
7523	system's default library path.
7524
7525	The default value of this property is <tt>"VRDPAuth"</tt>. There is a library
7526	of that name in one of the default VirtualBox library directories.
7527
7528	For details about VirtualBox authentication libraries and how to implement
7529	them, please refer to the VirtualBox manual.
7530
7531	<note>
7532	Setting this property to @c null or empty string will restore the
7533	initial value.
7534	</note>
7535	</desc>
7536	</attribute>
7537
7538	<attribute name="webServiceAuthLibrary" type="wstring">
7539	<desc>
7540	Library that provides authentication for webservice clients. The library
7541	is used if a virtual machine's authentication type is set to "external"
7542	in the VM RemoteDisplay configuration and will be called from
7543	within the <link to="IWebsessionManager::logon" /> implementation.
7544
7545	As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
7546	there is no per-VM setting for this, as the webservice is a global
7547	resource (if it is running). Only for this setting (for the webservice),
7548	setting this value to a literal <tt>"null"</tt> string disables authentication,
7549	meaning that <link to="IWebsessionManager::logon" /> will always succeed,
7550	no matter what user name and password are supplied.
7551
7552	The initial value of this property is <tt>"VRDPAuth"</tt>,
7553	meaning that the webservice will use the same authentication
7554	library that is used by default for VBoxVRDP (again, see
7555	<link to="ISystemProperties::remoteDisplayAuthLibrary" />).
7556	The format and calling convention of authentication libraries
7557	is the same for the webservice as it is for VBoxVRDP.
7558
7559	<note>
7560	Setting this property to @c null or empty string will restore the
7561	initial value.
7562	</note>
7563	</desc>
7564	</attribute>
7565
7566	<attribute name="LogHistoryCount" type="unsigned long">
7567	<desc>
7568	This value specifies how many old release log files are kept.
7569	</desc>
7570	</attribute>
7571
7572	<attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
7573	<desc>This value hold the default audio driver for the current
7574	system.</desc>
7575	</attribute>
7576
7577	<method name="getMaxDevicesPerPortForStorageBus">
7578	<desc>Returns the maximum number of devices which can be attached to a port
7579	for the given storage bus.</desc>
7580
7581	<param name="bus" type="StorageBus" dir="in">
7582	<desc>The storage bus type to get the value for.</desc>
7583	</param>
7584
7585	<param name="maxDevicesPerPort" type="unsigned long" dir="return">
7586	<desc>The maximum number of devices which can eb attached to the port for the given
7587	storage bus.</desc>
7588	</param>
7589	</method>
7590
7591	<method name="getMinPortCountForStorageBus">
7592	<desc>Returns the minimum number of ports the given storage bus supports.</desc>
7593
7594	<param name="bus" type="StorageBus" dir="in">
7595	<desc>The storage bus type to get the value for.</desc>
7596	</param>
7597
7598	<param name="minPortCount" type="unsigned long" dir="return">
7599	<desc>The minimum number of ports for the given storage bus.</desc>
7600	</param>
7601	</method>
7602
7603	<method name="getMaxPortCountForStorageBus">
7604	<desc>Returns the maximum number of ports the given storage bus supports.</desc>
7605
7606	<param name="bus" type="StorageBus" dir="in">
7607	<desc>The storage bus type to get the value for.</desc>
7608	</param>
7609
7610	<param name="maxPortCount" type="unsigned long" dir="return">
7611	<desc>The maximum number of ports for the given storage bus.</desc>
7612	</param>
7613	</method>
7614
7615	<method name="getMaxInstancesOfStorageBus">
7616	<desc>Returns the maximum number of storage bus instances which
7617	can be configured for each VM. This corresponds to the number of
7618	storage controllers one can have.</desc>
7619
7620	<param name="bus" type="StorageBus" dir="in">
7621	<desc>The storage bus type to get the value for.</desc>
7622	</param>
7623
7624	<param name="maxInstances" type="unsigned long" dir="return">
7625	<desc>The maximum number of instances for the given storage bus.</desc>
7626	</param>
7627	</method>
7628	</interface>
7629
7630	<!--
7631	// IGuest
7632	/////////////////////////////////////////////////////////////////////////
7633	-->
7634
7635	<interface
7636	name="IGuestOSType" extends="$unknown"
7637	uuid="cfe9e64c-4430-435b-9e7c-e3d8e417bd58"
7638	wsmap="struct"
7639	>
7640	<desc>
7641	</desc>
7642
7643	<attribute name="familyId" type="wstring" readonly="yes">
7644	<desc>Guest OS family identifier string.</desc>
7645	</attribute>
7646
7647	<attribute name="familyDescription" type="wstring" readonly="yes">
7648	<desc>Human readable description of the guest OS family.</desc>
7649	</attribute>
7650
7651	<attribute name="id" type="wstring" readonly="yes">
7652	<desc>Guest OS identifier string.</desc>
7653	</attribute>
7654
7655	<attribute name="description" type="wstring" readonly="yes">
7656	<desc>Human readable description of the guest OS.</desc>
7657	</attribute>
7658
7659	<attribute name="is64Bit" type="boolean" readonly="yes">
7660	<desc>Returns @c true if the given OS is 64-bit</desc>
7661	</attribute>
7662
7663	<attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
7664	<desc>Returns @c true if IO APIC recommended for this OS type.</desc>
7665	</attribute>
7666
7667	<attribute name="recommendedVirtEx" type="boolean" readonly="yes">
7668	<desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
7669	</attribute>
7670
7671	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
7672	<desc>Recommended RAM size in Megabytes.</desc>
7673	</attribute>
7674
7675	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
7676	<desc>Recommended video RAM size in Megabytes.</desc>
7677	</attribute>
7678
7679	<attribute name="recommendedHDD" type="unsigned long" readonly="yes">
7680	<desc>Recommended hard disk size in Megabytes.</desc>
7681	</attribute>
7682
7683	<attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
7684	<desc>Returns recommended network adapter for this OS type.</desc>
7685	</attribute>
7686	</interface>
7687
7688	<interface
7689	name="IGuest" extends="$unknown"
7690	uuid="d8556fca-81bc-12af-fca3-365528fa38ca"
7691	wsmap="managed"
7692	>
7693	<desc>
7694	The IGuest interface represents information about the operating system
7695	running inside the virtual machine. Used in
7696	<link to="IConsole::guest"/>.
7697
7698	IGuest provides information about the guest operating system, whether
7699	Guest Additions are installed and other OS-specific virtual machine
7700	properties.
7701	</desc>
7702
7703	<attribute name="OSTypeId" type="wstring" readonly="yes">
7704	<desc>
7705	Identifier of the Guest OS type as reported by the Guest
7706	Additions.
7707	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
7708	an IGuestOSType object representing details about the given
7709	Guest OS type.
7710	<note>
7711	If Guest Additions are not installed, this value will be
7712	the same as <link to="IMachine::OSTypeId"/>.
7713	</note>
7714	</desc>
7715	</attribute>
7716
7717	<attribute name="additionsActive" type="boolean" readonly="yes">
7718	<desc>
7719	Flag whether the Guest Additions are installed and active
7720	in which case their version will be returned by the
7721	<link to="#additionsVersion"/> property.
7722	</desc>
7723	</attribute>
7724
7725	<attribute name="additionsVersion" type="wstring" readonly="yes">
7726	<desc>
7727	Version of the Guest Additions (3 decimal numbers separated
7728	by dots) or empty when the Additions are not installed. The
7729	Additions may also report a version but yet not be active as
7730	the version might be refused by VirtualBox (incompatible) or
7731	other failures occurred.
7732	</desc>
7733	</attribute>
7734
7735	<attribute name="supportsSeamless" type="boolean" readonly="yes">
7736	<desc>
7737	Flag whether seamless guest display rendering (seamless desktop
7738	integration) is supported.
7739	</desc>
7740	</attribute>
7741
7742	<attribute name="supportsGraphics" type="boolean" readonly="yes">
7743	<desc>
7744	Flag whether the guest is in graphics mode. If it is not, then
7745	seamless rendering will not work, resize hints are not immediately
7746	acted on and guest display resizes are probably not initiated by
7747	the guest additions.
7748	</desc>
7749	</attribute>
7750
7751	<attribute name="memoryBalloonSize" type="unsigned long">
7752	<desc>Guest system memory balloon size in megabytes.</desc>
7753	</attribute>
7754
7755	<attribute name="statisticsUpdateInterval" type="unsigned long">
7756	<desc>Interval to update guest statistics in seconds.</desc>
7757	</attribute>
7758
7759	<method name="setCredentials">
7760	<desc>
7761	Store login credentials that can be queried by guest operating
7762	systems with Additions installed. The credentials are transient
7763	to the session and the guest may also choose to erase them. Note
7764	that the caller cannot determine whether the guest operating system
7765	has queried or made use of the credentials.
7766
7767	<result name="VBOX_E_VM_ERROR">
7768	VMM device is not available.
7769	</result>
7770
7771	</desc>
7772	<param name="userName" type="wstring" dir="in">
7773	<desc>User name string, can be empty</desc>
7774	</param>
7775	<param name="password" type="wstring" dir="in">
7776	<desc>Password string, can be empty</desc>
7777	</param>
7778	<param name="domain" type="wstring" dir="in">
7779	<desc>Domain name (guest logon scheme specific), can be empty</desc>
7780	</param>
7781	<param name="allowInteractiveLogon" type="boolean" dir="in">
7782	<desc>
7783	Flag whether the guest should alternatively allow the user to
7784	interactively specify different credentials. This flag might
7785	not be supported by all versions of the Additions.
7786	</desc>
7787	</param>
7788	</method>
7789
7790	<method name="getStatistic">
7791	<desc>
7792	Query specified guest statistics as reported by the VirtualBox Additions.
7793	</desc>
7794	<param name="cpuId" type="unsigned long" dir="in">
7795	<desc>Virtual CPU id; not relevant for all statistic types</desc>
7796	</param>
7797	<param name="statistic" type="GuestStatisticType" dir="in">
7798	<desc>Statistic type.</desc>
7799	</param>
7800	<param name="statVal" type="unsigned long" dir="return">
7801	<desc>Statistics value</desc>
7802	</param>
7803	</method>
7804
7805	</interface>
7806
7807
7808	<!--
7809	// IProgress
7810	/////////////////////////////////////////////////////////////////////////
7811	-->
7812
7813	<interface
7814	name="IProgress" extends="$unknown"
7815	uuid="62827ef1-c098-40eb-be96-36d0508489a6"
7816	wsmap="managed"
7817	>
7818	<desc>
7819	The IProgress interface is used to track and control
7820	asynchronous tasks within VirtualBox.
7821
7822	An instance of this is returned every time VirtualBox starts
7823	an asynchronous task (in other words, a separate thread) which
7824	continues to run after a method call returns. For example,
7825	<link to="IConsole::saveState" />, which saves the state of
7826	a running virtual machine, can take a long time to complete.
7827	To be able to display a progress bar, a user interface such as
7828	the VirtualBox graphical user interface can use the IProgress
7829	object returned by that method.
7830
7831	Note that IProgress is a "read-only" interface in the sense
7832	that only the VirtualBox internals behind the Main API can
7833	create and manipulate progress objects, whereas client code
7834	can only use the IProgress object to monitor a task's
7835	progress and, if <link to="#cancelable" /> is @c true,
7836	cancel the task by calling <link to="#cancel" />.
7837
7838	A task represented by IProgress consists of either one or
7839	several sub-operations that run sequentially, one by one (see
7840	<link to="#operation" /> and <link to="#operationCount" />).
7841	Every operation is identified by a number (starting from 0)
7842	and has a separate description.
7843
7844	You can find the individual percentage of completion of the current
7845	operation in <link to="#operationPercent" /> and the
7846	percentage of completion of the task as a whole
7847	in <link to="#percent" />.
7848
7849	Similarly, you can wait for the completion of a particular
7850	operation via <link to="#waitForOperationCompletion" /> or
7851	for the completion of the whole task via
7852	<link to="#waitForCompletion" />.
7853	</desc>
7854
7855	<attribute name="id" type="uuid" mod="string" readonly="yes">
7856	<desc>ID of the task.</desc>
7857	</attribute>
7858
7859	<attribute name="description" type="wstring" readonly="yes">
7860	<desc>Description of the task.</desc>
7861	</attribute>
7862
7863	<attribute name="initiator" type="$unknown" readonly="yes">
7864	<desc>Initiator of the task.</desc>
7865	</attribute>
7866
7867	<attribute name="cancelable" type="boolean" readonly="yes">
7868	<desc>Whether the task can be interrupted.</desc>
7869	</attribute>
7870
7871	<attribute name="percent" type="unsigned long" readonly="yes">
7872	<desc>
7873	Current progress value of the task as a whole, in percent.
7874	This value depends on how many operations are already complete.
7875	Returns 100 if <link to="#completed" /> is @c true.
7876	</desc>
7877	</attribute>
7878
7879	<attribute name="timeRemaining" type="long" readonly="yes">
7880	<desc>
7881	Estimated remaining time until the task completes, in
7882	seconds. Returns 0 once the task has completed; returns -1
7883	if the remaining time cannot be computed, in particular if
7884	the current progress is 0.
7885
7886	Even if a value is returned, the estimate will be unreliable
7887	for low progress values. It will become more reliable as the
7888	task progresses; it is not recommended to display an ETA
7889	before at least 20% of a task have completed.
7890	</desc>
7891	</attribute>
7892
7893	<attribute name="completed" type="boolean" readonly="yes">
7894	<desc>Whether the task has been completed.</desc>
7895	</attribute>
7896
7897	<attribute name="canceled" type="boolean" readonly="yes">
7898	<desc>Whether the task has been canceled.</desc>
7899	</attribute>
7900
7901	<attribute name="resultCode" type="long" readonly="yes">
7902	<desc>
7903	Result code of the progress task.
7904	Valid only if <link to="#completed"/> is @c true.
7905	</desc>
7906	</attribute>
7907
7908	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
7909	<desc>
7910	Extended information about the unsuccessful result of the
7911	progress operation. May be @c null if no extended information
7912	is available.
7913	Valid only if <link to="#completed"/> is @c true and
7914	<link to="#resultCode"/> indicates a failure.
7915	</desc>
7916	</attribute>
7917
7918	<attribute name="operationCount" type="unsigned long" readonly="yes">
7919	<desc>
7920	Number of sub-operations this task is divided into.
7921	Every task consists of at least one suboperation.
7922	</desc>
7923	</attribute>
7924
7925	<attribute name="operation" type="unsigned long" readonly="yes">
7926	<desc>Number of the sub-operation being currently executed.</desc>
7927	</attribute>
7928
7929	<attribute name="operationDescription" type="wstring" readonly="yes">
7930	<desc>
7931	Description of the sub-operation being currently executed.
7932	</desc>
7933	</attribute>
7934
7935	<attribute name="operationPercent" type="unsigned long" readonly="yes">
7936	<desc>Progress value of the current sub-operation only, in percent.</desc>
7937	</attribute>
7938
7939	<method name="setCurrentOperationProgress">
7940	<desc>Internal method, not to be called externally.</desc>
7941	<param name="percent" type="unsigned long" dir="in" />
7942	</method>
7943	<method name="setNextOperation">
7944	<desc>Internal method, not to be called externally.</desc>
7945	<param name="nextOperationDescription" type="wstring" dir="in" />
7946	<param name="nextOperationsWeight" type="unsigned long" dir="in" />
7947	</method>
7948
7949	<method name="waitForCompletion">
7950	<desc>
7951	Waits until the task is done (including all sub-operations)
7952	with a given timeout in milliseconds; specify -1 for an indefinite wait.
7953
7954	<result name="VBOX_E_IPRT_ERROR">
7955	Failed to wait for task completion.
7956	</result>
7957	</desc>
7958
7959	<param name="timeout" type="long" dir="in">
7960	<desc>
7961	Maximum time in milliseconds to wait or -1 to wait indefinitely.
7962	</desc>
7963	</param>
7964	</method>
7965
7966	<method name="waitForOperationCompletion">
7967	<desc>
7968	Waits until the given operation is done with a given timeout in
7969	milliseconds; specify -1 for an indefinite wait.
7970
7971	<result name="VBOX_E_IPRT_ERROR">
7972	Failed to wait for operation completion.
7973	</result>
7974
7975	</desc>
7976	<param name="operation" type="unsigned long" dir="in">
7977	<desc>
7978	Number of the operation to wait for.
7979	Must be less than <link to="#operationCount"/>.
7980	</desc>
7981	</param>
7982	<param name="timeout" type="long" dir="in">
7983	<desc>
7984	Maximum time in milliseconds to wait or -1 to wait indefinitely.
7985	</desc>
7986	</param>
7987	</method>
7988
7989	<method name="cancel">
7990	<desc>
7991	Cancels the task.
7992	<note>
7993	If <link to="#cancelable"/> is @c false, then this method will fail.
7994	</note>
7995
7996	<result name="VBOX_E_INVALID_OBJECT_STATE">
7997	Operation cannot be canceled.
7998	</result>
7999
8000	</desc>
8001	</method>
8002
8003	</interface>
8004
8005
8006	<!--
8007	// ISnapshot
8008	/////////////////////////////////////////////////////////////////////////
8009	-->
8010
8011	<interface
8012	name="ISnapshot" extends="$unknown"
8013	uuid="1a2d0551-58a4-4107-857e-ef414fc42ffc"
8014	wsmap="managed"
8015	>
8016	<desc>
8017	The ISnapshot interface represents a snapshot of the virtual
8018	machine.
8019
8020	Together with the differencing media that are created
8021	when a snapshot is taken, a machine can be brought back to
8022	the exact state it was in when the snapshot was taken.
8023
8024	The ISnapshot interface has no methods, only attributes; snapshots
8025	are controlled through methods of the <link to="IConsole" /> interface
8026	which also manage the media associated with the snapshot.
8027	The following operations exist:
8028
8029	<ul>
8030	<li><link to="IConsole::takeSnapshot"/>: creates a new snapshot
8031	by creating new, empty differencing images for the machine's
8032	media and saving the VM settings and (if the VM is running)
8033	the current VM state in the snapshot.
8034
8035	The differencing images will then receive all data written to
8036	the machine's media, while their parent (base) images
8037	remain unmodified after the snapshot has been taken (see
8038	<link to="IMedium" /> for details about differencing images).
8039	This simplifies restoring a machine to the state of a snapshot:
8040	only the differencing images need to be deleted.
8041
8042	The current machine state is not changed by taking a snapshot.
8043	If the machine is running, it will resume execution after the
8044	snapshot has been taken.
8045	</li>
8046
8047	<li><link to="IConsole::discardCurrentState"/>: this goes back to
8048	a previous snapshot. This resets the machine's state to that of
8049	the previous snapshot by deleting the differencing image of each
8050	of the machine's media and setting the machine's settings
8051	and state to the state that was saved in the snapshot (if any).
8052
8053	This destroys the machine's current state.
8054	</li>
8055
8056	<li><link to="IConsole::discardSnapshot"/>: deletes a snapshot
8057	without affecting the current machine state.
8058
8059	This does not change the machine, but instead frees the resources
8060	allocated when the snapshot was taken: the settings and machine state
8061	is deleted (if any), and the snapshot's differencing image for each
8062	of the machine's media gets merged with its parent image.
8063
8064	Neither the current machine state nor other snapshots are affected
8065	by this operation, except that parent disk images will be modified
8066	to contain the disk data associated with the snapshot being deleted.
8067	</li>
8068
8069	<li><link to="IConsole::discardCurrentSnapshotAndState"/>:
8070	this completely reverts the virtual machine to the state it was in
8071	before the current snapshot has been taken. Effectively, this goes
8072	back to the state before the current snapshot, which might be
8073	an earlier snapshot.
8074
8075	The current state, as well as the current snapshot, are lost.
8076	</li>
8077	</ul>
8078
8079	Each snapshot contains the settings of the virtual machine (hardware
8080	configuration etc.). In addition, if the machine was running when the
8081	snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
8082	the current VM state is saved in the snapshot (similarly to what happens
8083	when a VM's state is saved). The snapshot is then said to
8084	be <i>online</i> because when restoring it, the VM will be running.
8085
8086	If the machine is saved (<link to="MachineState_Saved"/>), the snapshot
8087	receives a copy of the execution state file (<link to="IMachine::stateFilePath"/>).
8088
8089	Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
8090	or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
8091	it then contains a so-called "zero execution state", representing a
8092	machine that is powered off.
8093
8094	<h3>Snapshot branches and the "current" snapshot</h3>
8095
8096	Snapshots can be chained, whereby every next snapshot is based on the
8097	previous one. This chaining is related to medium branching
8098	(see the <link to="IMedium"/> description) in that every time
8099	a new snapshot is created, a new differencing medium is implicitly
8100	created for all normal media attached to the machine.
8101
8102	Each virtual machine has a "current snapshot", identified by
8103	<link to="IMachine::currentSnapshot"/>. Presently, this is always set
8104	to the last snapshot in the chain. In a future version of VirtualBox,
8105	it will be possible to reset a machine's current state to that of an
8106	earlier snapshot without discarding the current state so that it will be
8107	possible to create alternative snapshot paths in a snapshot tree.
8108
8109	In the current implementation, multiple snapshot branches within one
8110	virtual machine are not allowed. Every machine has a single branch,
8111	and <link to="IConsole::takeSnapshot"/> operation adds a new
8112	snapshot to the top of that branch.
8113	</desc>
8114
8115	<attribute name="id" type="uuid" mod="string" readonly="yes">
8116	<desc>UUID of the snapshot.</desc>
8117	</attribute>
8118
8119	<attribute name="name" type="wstring">
8120	<desc>Short name of the snapshot.</desc>
8121	</attribute>
8122
8123	<attribute name="description" type="wstring">
8124	<desc>Optional description of the snapshot.</desc>
8125	</attribute>
8126
8127	<attribute name="timeStamp" type="long long" readonly="yes">
8128	<desc>
8129	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
8130	</desc>
8131	</attribute>
8132
8133	<attribute name="online" type="boolean" readonly="yes">
8134	<desc>
8135	@c true if this snapshot is an online snapshot and @c false otherwise.
8136
8137	When this attribute is @c true, the
8138	<link to="IMachine::stateFilePath"/> attribute of the
8139	<link to="#machine"/> object associated with this snapshot
8140	will point to the saved state file. Otherwise, it will be
8141	an empty string.
8142	</desc>
8143	</attribute>
8144
8145	<attribute name="machine" type="IMachine" readonly="yes">
8146	<desc>
8147	Virtual machine this snapshot is taken on. This object
8148	stores all settings the machine had when taking this snapshot.
8149	<note>
8150	The returned machine object is immutable, i.e. no
8151	any settings can be changed.
8152	</note>
8153	</desc>
8154	</attribute>
8155
8156	<attribute name="parent" type="ISnapshot" readonly="yes">
8157	<desc>
8158	Parent snapshot (a snapshot this one is based on), or
8159	@c null if the snapshot has no parent.
8160	</desc>
8161	</attribute>
8162
8163	<attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
8164	<desc>
8165	Child snapshots (all snapshots having this one as a parent).
8166	<note>
8167	In the current implementation, there can be only one
8168	child snapshot, or no children at all, meaning this is the
8169	last (head) snapshot.
8170	</note>
8171	</desc>
8172	</attribute>
8173
8174	</interface>
8175
8176
8177	<!--
8178	// IMedium
8179	/////////////////////////////////////////////////////////////////////////
8180	-->
8181
8182	<enum
8183	name="MediumState"
8184	uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
8185	>
8186	<desc>
8187	Virtual medium state.
8188	<see>IMedium</see>
8189	</desc>
8190
8191	<const name="NotCreated" value="0">
8192	<desc>
8193	Associated medium storage does not exist (either was not created yet or
8194	was deleted).
8195	</desc>
8196	</const>
8197	<const name="Created" value="1">
8198	<desc>
8199	Associated storage exists and accessible.
8200	</desc>
8201	</const>
8202	<const name="LockedRead" value="2">
8203	<desc>
8204	Medium is locked for reading, no data modification is possible.
8205	</desc>
8206	</const>
8207	<const name="LockedWrite" value="3">
8208	<desc>
8209	Medium is locked for writing, no concurrent data reading or modification
8210	is possible.
8211	</desc>
8212	</const>
8213	<const name="Inaccessible" value="4">
8214	<desc>
8215	Associated medium storage is not accessible.
8216	</desc>
8217	</const>
8218	<const name="Creating" value="5">
8219	<desc>
8220	Associated medium storage is being created.
8221	</desc>
8222	</const>
8223	<const name="Deleting" value="6">
8224	<desc>
8225	Associated medium storage is being deleted.
8226	</desc>
8227	</const>
8228	</enum>
8229
8230	<enum
8231	name="MediumType"
8232	uuid="11f6f7a5-0327-409a-9d42-7db6a0cec578"
8233	>
8234	<desc>
8235	Virtual medium type.
8236	<see>IMedium</see>
8237	</desc>
8238
8239	<const name="Normal" value="0">
8240	<desc>
8241	Normal medium (attached directly or indirectly, preserved
8242	when taking snapshots).
8243	</desc>
8244	</const>
8245	<const name="Immutable" value="1">
8246	<desc>
8247	Immutable medium (attached indirectly, changes are wiped out
8248	after powering off the virtual machine).
8249	</desc>
8250	</const>
8251	<const name="Writethrough" value="2">
8252	<desc>
8253	Write through medium (attached directly, ignored when
8254	taking snapshots).
8255	</desc>
8256	</const>
8257	</enum>
8258
8259	<enum
8260	name="MediumVariant"
8261	uuid="584ea502-143b-4ab0-ad14-d1028fdf0316"
8262	>
8263	<desc>
8264	Virtual medium image variant. More than one flag may be set.
8265	<see>IMedium</see>
8266	</desc>
8267
8268	<const name="Standard" value="0">
8269	<desc>
8270	No particular variant requested, results in using the backend default.
8271	</desc>
8272	</const>
8273	<const name="VmdkSplit2G" value="0x01">
8274	<desc>
8275	VMDK image split in chunks of less than 2GByte.
8276	</desc>
8277	</const>
8278	<const name="VmdkStreamOptimized" value="0x04">
8279	<desc>
8280	VMDK streamOptimized image. Special import/export format which is
8281	read-only/append-only.
8282	</desc>
8283	</const>
8284	<const name="VmdkESX" value="0x08">
8285	<desc>
8286	VMDK format variant used on ESX products.
8287	</desc>
8288	</const>
8289	<const name="Fixed" value="0x10000">
8290	<desc>
8291	Fixed image. Only allowed for base images.
8292	</desc>
8293	</const>
8294	<const name="Diff" value="0x20000">
8295	<desc>
8296	Fixed image. Only allowed for base images.
8297	</desc>
8298	</const>
8299	</enum>
8300
8301	<interface
8302	name="IMediumAttachment" extends="$unknown"
8303	uuid="0dcf987b-a024-453f-bace-7eb9f885a413"
8304	wsmap="struct"
8305	>
8306	<desc>
8307	The IMediumAttachment interface represents the attachment
8308	of a storage medium to a virtual machine. Each machine contains
8309	an array of its medium attachments in <link to="IMachine::mediumAttachments"/>.
8310
8311	Each medium attachment specifies a storage controller as well as a port
8312	and device number. Fixed media (hard disks) will always also specify
8313	an instance of IMedium in <link to="#medium" />, referring to the hard disk
8314	image or images that represent the virtual hard disk. For removeable media,
8315	the IMedia instance is optional; it can be NULL if no media is mounted (see
8316	<link to="IMachine::mountMedium" />).
8317	</desc>
8318
8319	<attribute name="medium" type="IMedium" readonly="yes">
8320	<desc>Medium object associated with this attachment; it
8321	can be NULL for removable devices.</desc>
8322	</attribute>
8323
8324	<attribute name="controller" type="wstring" readonly="yes">
8325	<desc>Name of the storage controller of this attachment; this
8326	refers to one of the controllers in <link to="IMachine::storageControllers" />
8327	by name.</desc>
8328	</attribute>
8329
8330	<attribute name="port" type="long" readonly="yes">
8331	<desc>Port number of this attachment.</desc>
8332	</attribute>
8333
8334	<attribute name="device" type="long" readonly="yes">
8335	<desc>Device slot number of this attachment.</desc>
8336	</attribute>
8337
8338	<attribute name="type" type="DeviceType" readonly="yes">
8339	<desc>Device type of this attachment.</desc>
8340	</attribute>
8341
8342	<attribute name="passthrough" type="boolean" readonly="no">
8343	<desc>Pass I/O requests through to a device on the host.</desc>
8344	</attribute>
8345
8346	</interface>
8347
8348	<interface
8349	name="IMedium" extends="$unknown"
8350	uuid="62551115-83b8-4d20-925f-79e9d3c00f96"
8351	wsmap="managed"
8352	>
8353	<desc>
8354	The IMedium interface represents virtual storage for a machine's
8355	hard disks, CD/DVD or floppy drives. It will typically represent
8356	a disk image on the host, for example a VDI or VMDK file representing
8357	a virtual hard disk, or an ISO or RAW file representing virtual
8358	removable media, but can also point to a network location (e.g.
8359	for iSCSI targets).
8360
8361	Instances of IMedium are connected to virtual machines by way of
8362	medium attachments (see <link to="IMediumAttachment" />), which link
8363	the storage medium to a particular device slot of a storage controller
8364	of the virtual machine.
8365	In the VirtualBox API, virtual storage is therefore always represented
8366	by the following chain of object links:
8367
8368	<ul>
8369	<li><link to="IMachine::storageControllers"/> contains an array of
8370	storage controllers (IDE, SATA, SCSI or a floppy controller;
8371	these are instances of <link to="IStorageController"/>).</li>
8372	<li><link to="IMachine::mediumAttachments"/> contains an array of
8373	medium attachments (instances of <link to="IMediumAttachment"/>),
8374	each containing the name of a storage controller from the above
8375	array, a port/device specification, and an instance of
8376	IMedium representing the medium storage (image file). For removable
8377	media, the storage medium is optional; a medium attachment with no
8378	medium represents a CD/DVD or floppy drive with no medium inserted.
8379	By contrast, hard disk attachments will always have an IMedium
8380	object attached.</li>
8381	<li>Each IMedium in turn points to a storage unit (such as a file on the host
8382	computer or a network resource) that holds actual data. The location of
8383	the storage unit is represented by the <link to="#location"/> attribute.
8384	The value of this attribute is medium type dependent.</li>
8385	</ul>
8386
8387	Existing media are opened using the following methods, depending on the
8388	media type:
8389	<ul>
8390	<li><link to="IVirtualBox::openHardDisk"/></li>
8391	<li><link to="IVirtualBox::openDVDImage"/></li>
8392	<li><link to="IVirtualBox::openFloppyImage"/></li>
8393	</ul>
8394
8395	New hard disk media can be created with the VirtualBox API using the
8396	<link to="IVirtualBox::createHardDisk"/> method.
8397
8398	CD/DVD and floppy images (ISO and RAW files) are usually created outside
8399	VirtualBox, e.g. by storing a copy of the real medium of the corresponding
8400	type in a regular file.
8401
8402	Only for CD/DVDs and floppies, an IMedium instance can also represent a host
8403	drive; in that case the <link to="#id" /> attribute contains the UUID of
8404	one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
8405
8406	<h3>Known media</h3>
8407
8408	When an existing medium is opened for the first time, it is automatically
8409	remembered by the given VirtualBox installation or, in other words, becomes
8410	a <i>known medium</i>. Known media are stored in the media
8411	registry transparently maintained by VirtualBox and stored in settings
8412	files so that this registry is preserved when VirtualBox is not running.
8413
8414	Newly created virtual media are remembered only when the associated
8415	storage unit is actually created.
8416
8417	All known media can be enumerated using
8418	<link to="IVirtualBox::hardDisks"/>,
8419	<link to="IVirtualBox::DVDImages"/> and
8420	<link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
8421	quickly found by UUID using <link to="IVirtualBox::getHardDisk"/>
8422	and similar methods or by location using
8423	<link to="IVirtualBox::findHardDisk"/> and similar methods.
8424
8425	Only known media can be attached to virtual machines.
8426
8427	Removing known media from the media registry is performed when the given
8428	medium is closed using the <link to="#close"/> method or when its
8429	associated storage unit is deleted.
8430
8431	<h3>Accessibility checks</h3>
8432
8433	The given medium (with the created storage unit) is considered to be
8434	<i>accessible</i> when its storage unit can be read. In that case, the
8435	<link to="#state"/> attribute has a value of "Created".
8436	When the storage unit cannot be read (for example, because it is located on
8437	a disconnected network resource, or was accidentally deleted outside VirtualBox),
8438	the medium is considered to be <i>inaccessible</i>, which is indicated by the
8439	"Inaccessible" state. The exact reason why the medium is inaccessible can be
8440	obtained by reading the <link to="#lastAccessError"/> attribute.
8441
8442	A new accessibility check is performed each time the <link to="#state"/>
8443	attribute is read. This check may take long time (several seconds or even
8444	minutes, depending on the storage unit location and format), and will
8445	block the calling thread until finished. For this reason, it is recommended
8446	to never read this attribute on the main UI thread to avoid making the UI
8447	unresponsive.
8448
8449	Note that when VirtualBox starts up (e.g. the VirtualBox object gets
8450	created for the first time), all known media are in the
8451	<link to="MediumState_Inaccessible"/> state but the value of the <link
8452	to="#lastAccessError"/> attribute is an empty string because no actual
8453	accessibility check is made on startup. This is done to make the
8454	VirtualBox object ready for serving requests as
8455	fast as possible and let the end-user application decide if it needs to
8456	check media accessibility right away or not.
8457
8458	<h3>Hard disk types</h3>
8459
8460	There are three types of hard disk images (see <link to="MediumType" />):
8461	"normal", "immutable" and "writethrough", represented by the
8462	<link to="#type"/> attribute. The type of the hard disk defines how the
8463	hard disk is attached to a virtual machine and what happens when a
8464	<link to="ISnapshot">snapshot</link> of the virtual machine with the
8465	attached hard disk is taken.
8466
8467	All hard disks can be also divided in two groups: <i>base</i> hard
8468	disks and <i>differencing</i> hard disks. A base hard disk contains all
8469	sectors of the hard disk data in its own storage and therefore can be
8470	used independently. On the contrary, a differencing hard disk is a
8471	"delta" to some other disk and contains only those sectors which differ
8472	from that other disk, which is then called a <i>parent</i>. The differencing
8473	hard disk is said to be <i>linked to</i> that parent.
8474	The parent may be itself a differencing image, thus forming a chain of
8475	linked hard disks. The last element in that chain
8476	must always be a base medium. Note that several differencing
8477	hard disks may be linked to the same parent hard disk.
8478
8479	Differencing hard disks can be distinguished from base hard disks by
8480	querying the <link to="#parent"/> attribute: base hard disks do not have
8481	parents they would depend on, so the value of this attribute is always
8482	@c null for them. Using this attribute, it is possible to walk up
8483	the hard disk tree (from the child hard disk to its parent). It is also
8484	possible to walk down the tree using the <link to="#children"/>
8485	attribute.
8486
8487	Note that the type of all differencing hard disks is
8488	<link to="MediumType_Normal" />; all other values are
8489	meaningless for them. Base hard disks may be of any type.
8490
8491	<h3>Creating hard disks</h3>
8492
8493	New base hard disks are created using
8494	<link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
8495	opened using <link to="IVirtualBox::openHardDisk"/>. Differencing hard
8496	disks are usually implicitly created by VirtualBox when needed but may
8497	also be created explicitly using <link to="#createDiffStorage"/>.
8498
8499	After the hard disk is successfully created (including the storage unit)
8500	or opened, it becomes a known hard disk (remembered in the internal media
8501	registry). Known hard disks can be attached to a virtual machine, accessed
8502	through <link to="IVirtualBox::getHardDisk"/> and
8503	<link to="IVirtualBox::findHardDisk"/> methods or enumerated using the
8504	<link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
8505
8506	The following methods, besides <link to="IMedium::close"/>,
8507	automatically remove the hard disk from the media registry:
8508	<ul>
8509	<li><link to="#deleteStorage"/></li>
8510	<li><link to="#mergeTo"/></li>
8511	</ul>
8512
8513	If the storage unit of the hard disk is a regular file in the host's
8514	file system then the rules stated in the description of the
8515	<link to="IMedium::location"/> attribute apply when setting its value. In
8516	addition, a plain file name without any path may be given, in which case
8517	the <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
8518	folder</link> will be prepended to it.
8519
8520	<h4>Automatic composition of the file name part</h4>
8521
8522	Another extension to the <link to="IMedium::location"/> attribute is that
8523	there is a possibility to cause VirtualBox to compose a unique value for
8524	the file name part of the location using the UUID of the hard disk. This
8525	applies only to hard disks in <link to="MediumState_NotCreated"/> state,
8526	e.g. before the storage unit is created, and works as follows. You set the
8527	value of the <link to="IMedium::location"/> attribute to a location
8528	specification which only contains the path specification but not the file
8529	name part and ends with either a forward slash or a backslash character.
8530	In response, VirtualBox will generate a new UUID for the hard disk and
8531	compose the file name using the following pattern:
8532	<pre>
8533	<path>/{<uuid>}.<ext>
8534	</pre>
8535	where <tt><path></tt> is the supplied path specification,
8536	<tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
8537	is the default extension for the storage format of this hard disk. After
8538	that, you may call any of the methods that create a new hard disk storage
8539	unit and they will use the generated UUID and file name.
8540
8541	<h3>Attaching Hard Disks</h3>
8542
8543	Hard disks are attached to virtual machines using the
8544	<link to="IMachine::attachDevice"/> method and detached using the
8545	<link to="IMachine::detachDevice"/> method. Depending on their
8546	<link to="#type"/>, hard disks are attached either
8547	<i>directly</i> or <i>indirectly</i>.
8548
8549	When a hard disk is being attached directly, it is associated with the
8550	virtual machine and used for hard disk operations when the machine is
8551	running. When a hard disk is being attached indirectly, a new differencing
8552	hard disk linked to it is implicitly created and this differencing hard
8553	disk is associated with the machine and used for hard disk operations.
8554	This also means that if <link to="IMachine::attachDevice"/> performs
8555	a direct attachment then the same hard disk will be returned in response
8556	to the subsequent <link to="IMachine::getMedium"/> call; however if
8557	an indirect attachment is performed then
8558	<link to="IMachine::getMedium"/> will return the implicitly created
8559	differencing hard disk, not the original one passed to <link
8560	to="IMachine::attachDevice"/>. In detail:
8561
8562	<ul>
8563	<li><b>Normal base</b> hard disks that do not have children (i.e.
8564	differencing hard disks linked to them) and that are not already
8565	attached to virtual machines in snapshots are attached <b>directly</b>.
8566	Otherwise, they are attached <b>indirectly</b> because having
8567	dependent children or being part of the snapshot makes it impossible
8568	to modify hard disk contents without breaking the integrity of the
8569	dependent party. The <link to="#readOnly"/> attribute allows to
8570	quickly determine the kind of the attachment for the given hard
8571	disk. Note that if a normal base hard disk is to be indirectly
8572	attached to a virtual machine with snapshots then a special
8573	procedure called <i>smart attachment</i> is performed (see below).</li>
8574	<li><b>Normal differencing</b> hard disks are like normal base hard disks:
8575	they are attached <b>directly</b> if they do not have children and are
8576	not attached to virtual machines in snapshots, and <b>indirectly</b>
8577	otherwise. Note that the smart attachment procedure is never performed
8578	for differencing hard disks.</li>
8579	<li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
8580	they are designed to be non-writable. If an immutable hard disk is
8581	attached to a virtual machine with snapshots then a special
8582	procedure called smart attachment is performed (see below).</li>
8583	<li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
8584	also as designed. This also means that writethrough hard disks cannot
8585	have other hard disks linked to them at all.</li>
8586	</ul>
8587
8588	Note that the same hard disk, regardless of its type, may be attached to
8589	more than one virtual machine at a time. In this case, the machine that is
8590	started first gains exclusive access to the hard disk and attempts to
8591	start other machines having this hard disk attached will fail until the
8592	first machine is powered down.
8593
8594	Detaching hard disks is performed in a <i>deferred</i> fashion. This means
8595	that the given hard disk remains associated with the given machine after a
8596	successful <link to="IMachine::detachDevice"/> call until
8597	<link to="IMachine::saveSettings"/> is called to save all changes to
8598	machine settings to disk. This deferring is necessary to guarantee that
8599	the hard disk configuration may be restored at any time by a call to
8600	<link to="IMachine::discardSettings"/> before the settings
8601	are saved (committed).
8602
8603	Note that if <link to="IMachine::discardSettings"/> is called after
8604	indirectly attaching some hard disks to the machine but before a call to
8605	<link to="IMachine::saveSettings"/> is made, it will implicitly delete
8606	all differencing hard disks implicitly created by
8607	<link to="IMachine::attachDevice"/> for these indirect attachments.
8608	Such implicitly created hard disks will also be immediately deleted when
8609	detached explicitly using the <link to="IMachine::detachDevice"/>
8610	call if it is made before <link to="IMachine::saveSettings"/>. This
8611	implicit deletion is safe because newly created differencing hard
8612	disks do not contain any user data.
8613
8614	However, keep in mind that detaching differencing hard disks that were
8615	implicitly created by <link to="IMachine::attachDevice"/>
8616	before the last <link to="IMachine::saveSettings"/> call will
8617	<b>not</b> implicitly delete them as they may already contain some data
8618	(for example, as a result of virtual machine execution). If these hard
8619	disks are no more necessary, the caller can always delete them explicitly
8620	using <link to="#deleteStorage"/> after they are actually de-associated
8621	from this machine by the <link to="IMachine::saveSettings"/> call.
8622
8623	<h3>Smart Attachment</h3>
8624
8625	When normal base or immutable hard disks are indirectly attached to a
8626	virtual machine then some additional steps are performed to make sure the
8627	virtual machine will have the most recent "view" of the hard disk being
8628	attached. These steps include walking through the machine's snapshots
8629	starting from the current one and going through ancestors up to the first
8630	snapshot. Hard disks attached to the virtual machine in all
8631	of the encountered snapshots are checked whether they are descendants of
8632	the given normal base or immutable hard disk. The first found child (which
8633	is the differencing hard disk) will be used instead of the normal base or
8634	immutable hard disk as a parent for creating a new differencing hard disk
8635	that will be actually attached to the machine. And only if no descendants
8636	are found or if the virtual machine does not have any snapshots then the
8637	normal base or immutable hard disk will be used itself as a parent for
8638	this differencing hard disk.
8639
8640	It is easier to explain what smart attachment does using the
8641	following example:
8642	<pre>
8643	BEFORE attaching B.vdi: AFTER attaching B.vdi:
8644
8645	Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
8646	Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
8647	Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
8648	Snapshot 4 (none) Snapshot 4 (none)
8649	CurState (none) CurState (D3->D2.vdi)
8650
8651	NOT
8652	...
8653	CurState (D3->B.vdi)
8654	</pre>
8655	The first column is the virtual machine configuration before the base hard
8656	disk <tt>B.vdi</tt> is attached, the second column shows the machine after
8657	this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
8658	mean that the hard disk that is actually attached to the machine is a
8659	differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
8660	another hard disk, <tt>B.vdi</tt>.
8661
8662	As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
8663	from the machine before taking Snapshot 4. Later, after Snapshot 4 was
8664	taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
8665	dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
8666	it cannot be attached directly and needs an indirect attachment (i.e.
8667	implicit creation of a new differencing hard disk). Due to the smart
8668	attachment procedure, the new differencing hard disk
8669	(<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
8670	<tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
8671	<tt>B.vdi</tt> existing for this snapshot branch of the given virtual
8672	machine.
8673
8674	Note that if there is more than one descendant hard disk of the given base
8675	hard disk found in a snapshot, and there is an exact device, channel and
8676	bus match, then this exact match will be used. Otherwise, the youngest
8677	descendant will be picked up.
8678
8679	There is one more important aspect of the smart attachment procedure which
8680	is not related to snapshots at all. Before walking through the snapshots
8681	as described above, the backup copy of the current list of hard disk
8682	attachment is searched for descendants. This backup copy is created when
8683	the hard disk configuration is changed for the first time after the last
8684	<link to="IMachine::saveSettings"/> call and used by
8685	<link to="IMachine::discardSettings"/> to undo the recent hard disk
8686	changes. When such a descendant is found in this backup copy, it will be
8687	simply re-attached back, without creating a new differencing hard disk for
8688	it. This optimization is necessary to make it possible to re-attach the
8689	base or immutable hard disk to a different bus, channel or device slot
8690	without losing the contents of the differencing hard disk actually
8691	attached to the machine in place of it.
8692	</desc>
8693
8694	<attribute name="id" type="uuid" mod="string" readonly="yes">
8695	<desc>
8696	UUID of the medium. For a newly created medium, this value is a randomly
8697	generated UUID.
8698
8699	<note>
8700	For media in one of MediumState_NotCreated, MediumState_Creating or
8701	MediumState_Deleting states, the value of this property is undefined
8702	and will most likely be an empty UUID.
8703	</note>
8704	</desc>
8705	</attribute>
8706
8707	<attribute name="description" type="wstring">
8708	<desc>
8709	Optional description of the medium. For a newly created medium the value
8710	of this attribute is an empty string.
8711
8712	Medium types that don't support this attribute will return E_NOTIMPL in
8713	attempt to get or set this attribute's value.
8714
8715	<note>
8716	For some storage types, reading this attribute may return an outdated
8717	(last known) value when <link to="#state"/> is <link
8718	to="MediumState_Inaccessible"/> or <link
8719	to="MediumState_LockedWrite"/> because the value of this attribute is
8720	stored within the storage unit itself. Also note that changing the
8721	attribute value is not possible in such case, as well as when the
8722	medium is the <link to="MediumState_LockedRead"/> state.
8723	</note>
8724	</desc>
8725	</attribute>
8726
8727	<attribute name="state" type="MediumState" readonly="yes">
8728	<desc>
8729	Current medium state. Inspect <link to="MediumState"/> values for details.
8730
8731	Reading this attribute may take a long time because an accessibility
8732	check of the storage unit is performed each time the attribute is read.
8733	This check may cause a significant delay if the storage unit of the
8734	given medium is, for example, a file located on a network share which is
8735	not currently accessible due to connectivity problems -- the call will
8736	not return until a timeout interval defined by the host OS for this
8737	operation expires.
8738
8739	If the last known state of the medium is <link to="MediumState_Created"/>
8740	and the accessibility check fails then the state would be set to
8741	<link to="MediumState_Inaccessible"/> and <link to="#lastAccessError"/>
8742	may be used to get more details about the failure. If the state of the
8743	medium is <link to="MediumState_LockedRead"/> or
8744	<link to="MediumState_LockedWrite"/> then it remains the same, and a
8745	non-empty value of <link to="#lastAccessError"/> will indicate a failed
8746	accessibility check in this case.
8747
8748	Note that not all medium states are applicable to all medium types.
8749	</desc>
8750	</attribute>
8751
8752	<attribute name="location" type="wstring">
8753	<desc>
8754	Location of the storage unit holding medium data.
8755
8756	The format of the location string is medium type specific. For medium
8757	types using regular files in a host's file system, the location
8758	string is the full file name.
8759
8760	Some medium types may support changing the storage unit location by
8761	simply changing the value of this property. If this operation is not
8762	supported, the implementation will return E_NOTIMPL in attempt to set
8763	this attribute's value.
8764
8765	When setting a value of the location attribute which is a regular file
8766	in the host's file system, the given file name may be either relative to
8767	the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
8768	absolute. Note that if the given location specification does not contain
8769	the file extension part then a proper default extension will be
8770	automatically appended by the implementation depending on the medium type.
8771	</desc>
8772	</attribute>
8773
8774	<attribute name="name" type="wstring" readonly="yes">
8775	<desc>
8776	Name of the storage unit holding medium data.
8777
8778	The returned string is a short version of the <link to="#location"/>
8779	attribute that is suitable for representing the medium in situations
8780	where the full location specification is too long (such as lists
8781	and comboboxes in GUI frontends). This string is also used by frontends
8782	to sort the media list alphabetically when needed.
8783
8784	For example, for locations that are regular files in the host's file
8785	system, the value of this attribute is just the file name (+ extension),
8786	without the path specification.
8787
8788	Note that as opposed to the <link to="#location"/> attribute, the name
8789	attribute will not necessary be unique for a list of media of the
8790	given type and format.
8791	</desc>
8792	</attribute>
8793
8794	<attribute name="hostDrive" type="boolean" readonly="yes">
8795	<desc>True if this corresponds to a drive on the host.</desc>
8796	</attribute>
8797
8798	<attribute name="size" type="unsigned long long" readonly="yes">
8799	<desc>
8800	Physical size of the storage unit used to hold medium data (in bytes).
8801
8802	<note>
8803	For media whose <link to="#state"/> is <link
8804	to="MediumState_Inaccessible"/>, the value of this property is the
8805	last known size. For <link to="MediumState_NotCreated"/> media,
8806	the returned value is zero.
8807	</note>
8808	</desc>
8809	</attribute>
8810
8811	<attribute name="format" type="wstring" readonly="yes">
8812	<desc>
8813	Storage format of this medium.
8814
8815	The value of this attribute is a string that specifies a backend used to
8816	store hard disk data. The storage format is defined when you create a
8817	new hard disk or automatically detected when you open an existing hard
8818	disk medium, and cannot be changed later.
8819
8820	The list of all storage formats supported by this VirtualBox
8821	installation can be obtained using
8822	<link to="ISystemProperties::mediumFormats"/>.
8823	</desc>
8824	</attribute>
8825
8826	<attribute name="type" type="MediumType">
8827	<desc>
8828	Type (role) of this hard disk.
8829
8830	The following constraints apply when changing the value of this
8831	attribute:
8832	<ul>
8833	<li>If a hard disk is attached to a virtual machine (either in the
8834	current state or in one of the snapshots), its type cannot be
8835	changed.
8836	</li>
8837	<li>As long as the hard disk has children, its type cannot be set
8838	to <link to="MediumType_Writethrough"/>.
8839	</li>
8840	<li>The type of all differencing hard disks is
8841	<link to="MediumType_Normal"/> and cannot be changed.
8842	</li>
8843	</ul>
8844
8845	The type of a newly created or opened hard disk is set to
8846	<link to="MediumType_Normal"/>.
8847	</desc>
8848	</attribute>
8849
8850	<attribute name="parent" type="IMedium" readonly="yes">
8851	<desc>
8852	Parent of this hard disk (a hard disk this hard disk is directly based
8853	on).
8854
8855	Only differencing hard disks have parents. For base (non-differencing)
8856	hard disks, @c null is returned.
8857	</desc>
8858	</attribute>
8859
8860	<attribute name="children" type="IMedium" safearray="yes" readonly="yes">
8861	<desc>
8862	Children of this hard disk (all differencing hard disks directly based
8863	on this hard disk). A @c null array is returned if this hard disk
8864	does not have any children.
8865	</desc>
8866	</attribute>
8867
8868	<attribute name="base" type="IMedium" readonly="yes">
8869	<desc>
8870	Base medium of this medium.
8871
8872	If this is a differencing medium, its base hard disk is the medium
8873	the given hard disk branch starts from. For all other types of hard
8874	disks, this property returns the hard disk object itself (i.e. the same
8875	object this property is read on).
8876	</desc>
8877	</attribute>
8878
8879	<attribute name="readOnly" type="boolean" readonly="yes">
8880	<desc>
8881	Returns @c true if this hard disk is read-only and @c false otherwise.
8882
8883	A hard disk is considered to be read-only when its contents cannot be
8884	modified without breaking the integrity of other parties that depend on
8885	this hard disk such as its child hard disks or snapshots of virtual
8886	machines where this hard disk is attached to these machines. If there
8887	are no children and no such snapshots then there is no dependency and
8888	the hard disk is not read-only.
8889
8890	The value of this attribute can be used to determine the kind of the
8891	attachment that will take place when attaching this hard disk to a
8892	virtual machine. If the value is @c false then the hard disk will
8893	be attached directly. If the value is @c true then the hard disk
8894	will be attached indirectly by creating a new differencing child hard
8895	disk for that. See the interface description for more information.
8896
8897	Note that all <link to="MediumType_Immutable">Immutable</link> hard
8898	disks are always read-only while all
8899	<link to="MediumType_Writethrough">Writethrough</link> hard disks are
8900	always not.
8901
8902	<note>
8903	The read-only condition represented by this attribute is related to
8904	the hard disk type and usage, not to the current
8905	<link to="IMedium::state">medium state</link> and not to the read-only
8906	state of the storage unit.
8907	</note>
8908	</desc>
8909	</attribute>
8910
8911	<attribute name="logicalSize" type="unsigned long long" readonly="yes">
8912	<desc>
8913	Logical size of this hard disk (in megabytes), as reported to the
8914	guest OS running inside the virtual machine this disk is
8915	attached to. The logical size is defined when the hard disk is created
8916	and cannot be changed later.
8917
8918	<note>
8919	Reading this property on a differencing hard disk will return the size
8920	of its <link to="#base"/> medium.
8921	</note>
8922	<note>
8923	For hard disks whose state is <link to="#state"/> is <link
8924	to="MediumState_Inaccessible"/>, the value of this property is the
8925	last known logical size. For <link to="MediumaState_NotCreated"/> hard
8926	disks, the returned value is zero.
8927	</note>
8928	</desc>
8929	</attribute>
8930
8931	<attribute name="autoReset" type="boolean">
8932	<desc>
8933	Whether this differencing hard disk will be automatically reset each
8934	time a virtual machine it is attached to is powered up.
8935
8936	See <link to="#reset()"/> for more information about resetting
8937	differencing hard disks.
8938
8939	<note>
8940	Reading this property on a base (non-differencing) hard disk will
8941	always @c false. Changing the value of this property in this
8942	case is not supported.
8943	</note>
8944
8945	<result name="VBOX_E_NOT_SUPPORTED">
8946	This is not a differencing hard disk (when changing the attribute
8947	value).
8948	</result>
8949	</desc>
8950	</attribute>
8951
8952	<attribute name="lastAccessError" type="wstring" readonly="yes">
8953	<desc>
8954	Text message that represents the result of the last accessibility
8955	check.
8956
8957	Accessibility checks are performed each time the <link to="#state"/>
8958	attribute is read. An empty string is returned if the last
8959	accessibility check was successful. A non-empty string indicates a
8960	failure and should normally describe a reason of the failure (for
8961	example, a file read error).
8962	</desc>
8963	</attribute>
8964
8965	<attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
8966	<desc>
8967	Array of UUIDs of all machines this medium is attached to.
8968
8969	A @c null array is returned if this medium is not attached to any
8970	machine or to any machine's snapshot.
8971
8972	<note>
8973	The returned array will include a machine even if this medium is not
8974	attached to that machine in the current state but attached to it in
8975	one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
8976	details.
8977	</note>
8978	</desc>
8979	</attribute>
8980
8981	<method name="getSnapshotIds">
8982	<desc>
8983	Returns an array of UUIDs of all snapshots of the given machine where
8984	this medium is attached to.
8985
8986	If the medium is attached to the machine in the current state, then the
8987	first element in the array will always be the ID of the queried machine
8988	(i.e. the value equal to the @c machineId argument), followed by
8989	snapshot IDs (if any).
8990
8991	If the medium is not attached to the machine in the current state, then
8992	the array will contain only snapshot IDs.
8993
8994	The returned array may be @c null if this medium is not attached
8995	to the given machine at all, neither in the current state nor in one of
8996	the snapshots.
8997	</desc>
8998	<param name="machineId" type="uuid" mod="string" dir="in">
8999	<desc>
9000	UUID of the machine to query.
9001	</desc>
9002	</param>
9003	<param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
9004	<desc>
9005	Array of snapshot UUIDs of the given machine using this medium.
9006	</desc>
9007	</param>
9008	</method>
9009
9010	<method name="lockRead">
9011	<desc>
9012	Locks this medium for reading.
9013
9014	The read lock is shared: many clients can simultaneously lock the
9015	same medium for reading unless it is already locked for writing (see
9016	<link to="#lockWrite"/>) in which case an error is returned.
9017
9018	When the medium is locked for reading, it cannot be modified
9019	from within VirtualBox. This means that any method that changes
9020	the properties of this medium or contents of the storage unit
9021	will return an error (unless explicitly stated otherwise) and
9022	that an attempt to start a virtual machine that wants to modify
9023	the medium will also fail.
9024
9025	When the virtual machine is started up, it locks for reading all
9026	media it uses in read-only mode. If some medium cannot be locked
9027	for reading, the startup procedure will fail.
9028
9029	The medium locked for reading must be unlocked using the <link
9030	to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
9031	can be nested and must be followed by the same number of paired
9032	<link to="#unlockRead"/> calls.
9033
9034	This method sets the medium state to <link
9035	to="MediumState_LockedRead" /> on success. The state prior to
9036	this call must be <link to="MediumState_Created" />,
9037	<link to="MediumState_Inaccessible" /> or
9038	<link to="MediumState_LockedRead" />.
9039	As you can see, an inaccessible medium can be locked too. This is
9040	not an error; this method performs a logical lock that prevents
9041	modifications of this medium through the VirtualBox API, not a
9042	physical lock of the underlying storage unit.
9043
9044	This method returns the current state of the medium
9045	<b>before</b> the operation.
9046
9047	<result name="VBOX_E_INVALID_OBJECT_STATE">
9048	Invalid medium state (e.g. not created, locked, inaccessible,
9049	creating, deleting).
9050	</result>
9051
9052	</desc>
9053	<param name="state" type="MediumState" dir="return">
9054	<desc>
9055	State of the medium after the operation.
9056	</desc>
9057	</param>
9058	</method>
9059
9060	<method name="unlockRead">
9061	<desc>
9062	Cancels the read lock previously set by <link to="#lockRead"/>.
9063
9064	For both, success and failure, this method returns the current state
9065	of the medium <b>after</b> the operation.
9066
9067	See <link to="#lockRead"/> for more details.
9068
9069	<result name="VBOX_E_INVALID_OBJECT_STATE">
9070	Medium not locked for reading.
9071	</result>
9072
9073	</desc>
9074	<param name="state" type="MediumState" dir="return">
9075	<desc>
9076	State of the medium after the operation.
9077	</desc>
9078	</param>
9079	</method>
9080
9081	<method name="lockWrite">
9082	<desc>
9083	Locks this medium for writing.
9084
9085	The write lock, as opposed to <link to="#lockRead"/>, is
9086	exclusive: there may be only one client holding a write lock
9087	and there may be no read locks while the write lock is held.
9088
9089	When the medium is locked for writing, it cannot be modified
9090	from within VirtualBox and it is not guaranteed that the values
9091	of its properties are up-to-date. Any method that changes the
9092	properties of this medium or contents of the storage unit will
9093	return an error (unless explicitly stated otherwise) and an
9094	attempt to start a virtual machine wanting to modify or to
9095	read the medium will fail.
9096
9097	When the virtual machine is started up, it locks for writing all
9098	media it uses to write data to. If any medium could not be locked
9099	for writing, the startup procedure will fail.
9100
9101	The medium locked for writing must be unlocked using the <link
9102	to="#unlockWrite"/> method. Calls to <link to="#lockWrite"/>
9103	can <b>not</b> be nested and must be followed by a<link
9104	to="#unlockWrite"/> call before the next lockWrite call.
9105
9106	This method sets the medium state to <link to="MediumState_LockedWrite" />
9107	on success. The state prior to this call must be <link to="MediumState_Created"/>
9108	or <link to="MediumState_Inaccessible"/>. As you can see, an inaccessible
9109	medium can be locked too. This is not an error; this method
9110	performs a logical lock preventing modifications of this
9111	medium through the VirtualBox API, not a physical lock of the
9112	underlying storage unit.
9113
9114	For both, success and failure, this method returns the current
9115	state of the medium <b>before</b> the operation.
9116
9117	<result name="VBOX_E_INVALID_OBJECT_STATE">
9118	Invalid medium state (e.g. not created, locked, inaccessible,
9119	creating, deleting).
9120	</result>
9121
9122	</desc>
9123	<param name="state" type="MediumState" dir="return">
9124	<desc>
9125	State of the medium after the operation.
9126	</desc>
9127	</param>
9128	</method>
9129
9130	<method name="unlockWrite">
9131	<desc>
9132	Cancels the write lock previously set by <link to="#lockWrite"/>.
9133
9134	For both, success and failure, this method returns the current
9135	state of the medium <b>after</b> the operation.
9136
9137	See <link to="#lockWrite"/> for more details.
9138
9139	<result name="VBOX_E_INVALID_OBJECT_STATE">
9140	Medium not locked for writing.
9141	</result>
9142
9143	</desc>
9144	<param name="state" type="MediumState" dir="return">
9145	<desc>
9146	State of the medium after the operation.
9147	</desc>
9148	</param>
9149	</method>
9150
9151	<method name="close">
9152	<desc>
9153	Closes this medium.
9154
9155	The medium must not be attached to any known virtual machine
9156	and must not have any known child media, otherwise the
9157	operation will fail.
9158
9159	When the medium is successfully closed, it gets removed from
9160	the list of remembered media, but its storage unit is not
9161	deleted. In particular, this means that this medium can be
9162	later opened again using the <link
9163	to="IVirtualBox::openHardDisk"/> call.
9164
9165	Note that after this method successfully returns, the given medium
9166	object becomes uninitialized. This means that any attempt
9167	to call any of its methods or attributes will fail with the
9168	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
9169
9170	<result name="VBOX_E_INVALID_OBJECT_STATE">
9171	Invalid medium state (other than not created, created or
9172	inaccessible).
9173	</result>
9174	<result name="VBOX_E_OBJECT_IN_USE">
9175	Medium attached to virtual machine.
9176	</result>
9177	<result name="VBOX_E_FILE_ERROR">
9178	Settings file not accessible.
9179	</result>
9180	<result name="VBOX_E_XML_ERROR">
9181	Could not parse the settings file.
9182	</result>
9183
9184	</desc>
9185	</method>
9186
9187	<!-- storage methods -->
9188
9189	<method name="getProperty">
9190	<desc>
9191	Returns the value of the custom hard disk property with the given name.
9192
9193	The list of all properties supported by the given hard disk format can
9194	be obtained with <link to="IMediumFormat::describeProperties"/>.
9195
9196	Note that if this method returns an empty string in @a value, the
9197	requested property is supported but currently not assigned any value.
9198
9199	<result name="VBOX_E_OBJECT_NOT_FOUND">
9200	Requested property does not exist (not supported by the format).
9201	</result>
9202	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
9203	</desc>
9204	<param name="name" type="wstring" dir="in">
9205	<desc>Name of the property to get.</desc>
9206	</param>
9207	<param name="value" type="wstring" dir="return">
9208	<desc>Current property value.</desc>
9209	</param>
9210	</method>
9211
9212	<method name="setProperty">
9213	<desc>
9214	Sets the value of the custom hard disk property with the given name.
9215
9216	The list of all properties supported by the given hard disk format can
9217	be obtained with <link to="IMediumFormat::describeProperties"/>.
9218
9219	Note that setting the property value to @c null or an empty string is
9220	equivalent to deleting the existing value. A default value (if it is
9221	defined for this property) will be used by the format backend in this
9222	case.
9223
9224	<result name="VBOX_E_OBJECT_NOT_FOUND">
9225	Requested property does not exist (not supported by the format).
9226	</result>
9227	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
9228	</desc>
9229	<param name="name" type="wstring" dir="in">
9230	<desc>Name of the property to set.</desc>
9231	</param>
9232	<param name="value" type="wstring" dir="in">
9233	<desc>Property value to set.</desc>
9234	</param>
9235	</method>
9236
9237	<method name="getProperties">
9238	<desc>
9239	Returns values for a group of properties in one call.
9240
9241	The names of the properties to get are specified using the @a names
9242	argument which is a list of comma-separated property names or
9243	an empty string if all properties are to be returned. Note that currently
9244	the value of this argument is ignored and the method always returns all
9245	existing properties.
9246
9247	The list of all properties supported by the given hard disk format can
9248	be obtained with <link to="IMediumFormat::describeProperties"/>.
9249
9250	The method returns two arrays, the array of property names corresponding
9251	to the @a names argument and the current values of these properties.
9252	Both arrays have the same number of elements with each elemend at the
9253	given index in the first array corresponds to an element at the same
9254	index in the second array.
9255
9256	Note that for properties that do not have assigned values,
9257	an empty string is returned at the appropriate index in the
9258	@a returnValues array.
9259
9260	</desc>
9261	<param name="names" type="wstring" dir="in">
9262	<desc>
9263	Names of properties to get.
9264	</desc>
9265	</param>
9266	<param name="returnNames" type="wstring" safearray="yes" dir="out">
9267	<desc>Names of returned properties.</desc>
9268	</param>
9269	<param name="returnValues" type="wstring" safearray="yes" dir="return">
9270	<desc>Values of returned properties.</desc>
9271	</param>
9272	</method>
9273
9274	<method name="setProperties">
9275	<desc>
9276	Sets values for a group of properties in one call.
9277
9278	The names of the properties to set are passed in the @a names
9279	array along with the new values for them in the @a values array. Both
9280	arrays have the same number of elements with each elemend at the given
9281	index in the first array corresponding to an element at the same index
9282	in the second array.
9283
9284	If there is at least one property name in @a names that is not valid,
9285	the method will fail before changing the values of any other properties
9286	from the @a names array.
9287
9288	Using this method over <link to="#setProperty"/> is preferred if you
9289	need to set several properties at once since it will result into less
9290	IPC calls.
9291
9292	The list of all properties supported by the given hard disk format can
9293	be obtained with <link to="IMediumFormat::describeProperties"/>.
9294
9295	Note that setting the property value to @c null or an empty string is
9296	equivalent to deleting the existing value. A default value (if it is
9297	defined for this property) will be used by the format backend in this
9298	case.
9299	</desc>
9300	<param name="names" type="wstring" safearray="yes" dir="in">
9301	<desc>Names of properties to set.</desc>
9302	</param>
9303	<param name="values" type="wstring" safearray="yes" dir="in">
9304	<desc>Values of properties to set.</desc>
9305	</param>
9306	</method>
9307
9308	<!-- storage methods -->
9309
9310	<method name="createBaseStorage">
9311	<desc>
9312	Starts creating a hard disk storage unit (fixed/dynamic, according
9313	to the variant flags) in in the background. The previous storage unit
9314	created for this object, if any, must first be deleted using
9315	<link to="#deleteStorage"/>, otherwise the operation will fail.
9316
9317	Before the operation starts, the hard disk is placed in
9318	<link to="MediumState_Creating"/> state. If the create operation
9319	fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
9320	state.
9321
9322	After the returned progress object reports that the operation has
9323	successfully completed, the medium state will be set to <link
9324	to="MediumState_Created"/>, the hard disk will be remembered by this
9325	VirtualBox installation and may be attached to virtual machines.
9326
9327	<result name="VBOX_E_NOT_SUPPORTED">
9328	The variant of storage creation operation is not supported. See <link
9329	to="IMediumFormat::capabilities"/>.
9330	</result>
9331	</desc>
9332	<param name="logicalSize" type="unsigned long long" dir="in">
9333	<desc>Maximum logical size of the hard disk in megabytes.</desc>
9334	</param>
9335	<param name="variant" type="MediumVariant" dir="in">
9336	<desc>Exact image variant which should be created.</desc>
9337	</param>
9338	<param name="progress" type="IProgress" dir="return">
9339	<desc>Progress object to track the operation completion.</desc>
9340	</param>
9341	</method>
9342
9343	<method name="deleteStorage">
9344	<desc>
9345	Starts deleting the storage unit of this hard disk.
9346
9347	The hard disk must not be attached to any known virtual machine and must
9348	not have any known child hard disks, otherwise the operation will fail.
9349	It will also fail if there is no storage unit to delete or if deletion
9350	is already in progress, or if the hard disk is being in use (locked for
9351	read or for write) or inaccessible. Therefore, the only valid state for
9352	this operation to succeed is <link to="MediumState_Created"/>.
9353
9354	Before the operation starts, the hard disk is placed to
9355	<link to="MediumState_Deleting"/> state and gets removed from the list
9356	of remembered hard disks (media registry). If the delete operation
9357	fails, the medium will be remembered again and placed back to
9358	<link to="MediumState_Created"/> state.
9359
9360	After the returned progress object reports that the operation is
9361	complete, the medium state will be set to
9362	<link to="MediumState_NotCreated"/> and you will be able to use one of
9363	the storage creation methods to create it again.
9364
9365	<see>#close()</see>
9366
9367	<result name="VBOX_E_OBJECT_IN_USE">
9368	Hard disk is attached to a virtual machine.
9369	</result>
9370	<result name="VBOX_E_NOT_SUPPORTED">
9371	Storage deletion is not allowed because neither of storage creation
9372	operations are supported. See
9373	<link to="IMediumFormat::capabilities"/>.
9374	</result>
9375
9376	<note>
9377	If the deletion operation fails, it is not guaranteed that the storage
9378	unit still exists. You may check the <link to="IMedium::state"/> value
9379	to answer this question.
9380	</note>
9381	</desc>
9382	<param name="progress" type="IProgress" dir="return">
9383	<desc>Progress object to track the operation completion.</desc>
9384	</param>
9385	</method>
9386
9387	<!-- diff methods -->
9388
9389	<method name="createDiffStorage">
9390	<desc>
9391	Starts creating an empty differencing storage unit based on this hard
9392	disk in the format and at the location defined by the @a target
9393	argument.
9394
9395	The target hard disk must be in <link to="MediumState_NotCreated"/>
9396	state (i.e. must not have an existing storage unit). Upon successful
9397	completion, this operation will set the type of the target hard disk to
9398	<link to="MediumType_Normal"/> and create a storage unit necessary to
9399	represent the differencing hard disk data in the given format (according
9400	to the storage format of the target object).
9401
9402	After the returned progress object reports that the operation is
9403	successfully complete, the target hard disk gets remembered by this
9404	VirtualBox installation and may be attached to virtual machines.
9405
9406	<note>
9407	The hard disk will be set to <link to="MediumState_LockedRead"/>
9408	state for the duration of this operation.
9409	</note>
9410	<result name="VBOX_E_OBJECT_IN_USE">
9411	Hard disk not in @c NotCreated state.
9412	</result>
9413	</desc>
9414	<param name="target" type="IMedium" dir="in">
9415	<desc>Target hard disk.</desc>
9416	</param>
9417	<param name="variant" type="MediumVariant" dir="in">
9418	<desc>Exact image variant which should be created.</desc>
9419	</param>
9420	<param name="progress" type="IProgress" dir="return">
9421	<desc>Progress object to track the operation completion.</desc>
9422	</param>
9423	</method>
9424
9425	<method name="mergeTo">
9426	<desc>
9427	Starts merging the contents of this hard disk and all intermediate
9428	differencing hard disks in the chain to the given target hard disk.
9429
9430	The target hard disk must be either a descendant of this hard disk or
9431	its ancestor (otherwise this method will immediately return a failure).
9432	It follows that there are two logical directions of the merge operation:
9433	from ancestor to descendant (<i>forward merge</i>) and from descendant to
9434	ancestor (<i>backward merge</i>). Let us consider the following hard disk
9435	chain:
9436
9437	<pre>Base <- Diff_1 <- Diff_2</pre>
9438
9439	Here, calling this method on the <tt>Base</tt> hard disk object with
9440	<tt>Diff_2</tt> as an argument will be a forward merge; calling it on
9441	<tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
9442	merge. Note that in both cases the contents of the resulting hard disk
9443	will be the same, the only difference is the hard disk object that takes
9444	the result of the merge operation. In case of the forward merge in the
9445	above example, the result will be written to <tt>Diff_2</tt>; in case of
9446	the backward merge, the result will be written to <tt>Base</tt>. In
9447	other words, the result of the operation is always stored in the target
9448	hard disk.
9449
9450	Upon successful operation completion, the storage units of all hard
9451	disks in the chain between this (source) hard disk and the target hard
9452	disk, including the source hard disk itself, will be automatically
9453	deleted and the relevant hard disk objects (including this hard disk)
9454	will become uninitialized. This means that any attempt to call any of
9455	their methods or attributes will fail with the
9456	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
9457	example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
9458	delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> hard
9459	disks. Note that <tt>Diff_2</tt> in this case will become a base hard
9460	disk itself since it will no longer be based on any other hard disk.
9461
9462	Considering the above, all of the following conditions must be met in
9463	order for the merge operation to succeed:
9464	<ul>
9465	<li>
9466	Neither this (source) hard disk nor any intermediate
9467	differencing hard disk in the chain between it and the target
9468	hard disk is attached to any virtual machine.
9469	</li>
9470	<li>
9471	Neither the source hard disk nor the target hard disk is an
9472	<link to="MediumType_Immutable"/> hard disk.
9473	</li>
9474	<li>
9475	The part of the hard disk tree from the source hard disk to the
9476	target hard disk is a linear chain, i.e. all hard disks in this
9477	chain have exactly one child which is the next hard disk in this
9478	chain. The only exception from this rule is the target hard disk in
9479	the forward merge operation; it is allowed to have any number of
9480	child hard disks because the merge operation will hot change its
9481	logical contents (as it is seen by the guest OS or by children).
9482	</li>
9483	<li>
9484	None of the involved hard disks are in
9485	<link to="MediumState_LockedRead"/> or
9486	<link to="MediumState_LockedWrite"/> state.
9487	</li>
9488	</ul>
9489
9490	<note>
9491	This (source) hard disk and all intermediates will be placed to <link
9492	to="MediumState_Deleting"/> state and the target hard disk will be
9493	placed to <link to="MediumState_LockedWrite"/> state and for the
9494	duration of this operation.
9495	</note>
9496	</desc>
9497	<param name="targetId" type="uuid" mod="string" dir="in">
9498	<desc>UUID of the target ancestor or descendant hard disk.</desc>
9499	</param>
9500	<param name="progress" type="IProgress" dir="return">
9501	<desc>Progress object to track the operation completion.</desc>
9502	</param>
9503	</method>
9504
9505	<!-- clone method -->
9506
9507	<method name="cloneTo">
9508	<desc>
9509	Starts creating a clone of this hard disk in the format and at the
9510	location defined by the @a target argument.
9511
9512	The target hard disk must be either in <link to="MediumState_NotCreated"/>
9513	state (i.e. must not have an existing storage unit) or in
9514	<link to="MediumState_Created"/> state (i.e. created and not locked, and
9515	big enough to hold the data or else the copy will be partial). Upon
9516	successful completion, the cloned hard disk will contain exactly the
9517	same sector data as the hard disk being cloned, except that in the
9518	first case a new UUID for the clone will be randomly generated, and in
9519	the second case the UUID will remain unchanged.
9520
9521	The @a parent argument defines which hard disk will be the parent
9522	of the clone. Passing a @c null reference indicates that the clone will
9523	be a base image, i.e. completely independent. It is possible to specify
9524	an arbitrary hard disk for this parameter, including the parent of the
9525	hard disk which is being cloned. Even cloning to a child of the source
9526	hard disk is possible. Note that when cloning to an existing image, the
9527	@a parent irgument is ignored.
9528
9529	After the returned progress object reports that the operation is
9530	successfully complete, the target hard disk gets remembered by this
9531	VirtualBox installation and may be attached to virtual machines.
9532
9533	<note>
9534	This hard disk will be placed to <link to="MediumState_LockedRead"/>
9535	state for the duration of this operation.
9536	</note>
9537	<result name="E_NOTIMPL">
9538	The specified cloning variant is not supported at the moment.
9539	</result>
9540	</desc>
9541	<param name="target" type="IMedium" dir="in">
9542	<desc>Target hard disk.</desc>
9543	</param>
9544	<param name="variant" type="MediumVariant" dir="in">
9545	<desc>Exact image variant which should be created.</desc>
9546	</param>
9547	<param name="parent" type="IMedium" dir="in">
9548	<desc>Parent of the cloned hard disk.</desc>
9549	</param>
9550	<param name="progress" type="IProgress" dir="return">
9551	<desc>Progress object to track the operation completion.</desc>
9552	</param>
9553	</method>
9554
9555	<!-- other methods -->
9556
9557	<method name="compact">
9558	<desc>
9559	Starts compacting of this hard disk. This means that the disk is
9560	transformed into a possibly more compact storage representation.
9561	This potentially creates temporary images, which can require a
9562	substantial amount of additional disk space.
9563
9564	This hard disk will be placed to <link to="MediumState_LockedWrite"/>
9565	state and all its parent hard disks (if any) will be placed to
9566	<link to="MediumState_LockedRead"/> state for the duration of this
9567	operation.
9568
9569	Please note that the results can be either returned straight away,
9570	or later as the result of the background operation via the object
9571	returned via the @a progress parameter.
9572
9573	<result name="VBOX_E_NOT_SUPPORTED">
9574	Hard disk format does not support compacting (but potentially
9575	needs it).
9576	</result>
9577	</desc>
9578	<param name="progress" type="IProgress" dir="return">
9579	<desc>Progress object to track the operation completion.</desc>
9580	</param>
9581	</method>
9582
9583	<method name="reset">
9584	<desc>
9585	Starts erasing the contents of this differencing hard disk.
9586
9587	This operation will reset the differencing hard disk to its initial
9588	state when it does not contain any sector data and any read operation is
9589	redirected to its parent hard disk.
9590
9591	This hard disk will be placed to <link to="MediumState_LockedWrite"/>
9592	for the duration of this operation.
9593
9594	<result name="VBOX_E_NOT_SUPPORTED">
9595	This is not a differencing hard disk.
9596	</result>
9597	<result name="VBOX_E_INVALID_OBJECT_STATE">
9598	Hard disk is not in <link to="MediumState_Created"/> or
9599	<link to="MediumState_Inaccessible"/> state.
9600	</result>
9601	</desc>
9602	<param name="progress" type="IProgress" dir="return">
9603	<desc>Progress object to track the operation completion.</desc>
9604	</param>
9605	</method>
9606
9607	</interface>
9608
9609
9610	<!--
9611	// IMediumFormat
9612	/////////////////////////////////////////////////////////////////////////
9613	-->
9614
9615	<enum
9616	name="DataType"
9617	uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
9618	>
9619	<const name="Int32" value="0"/>
9620	<const name="Int8" value="1"/>
9621	<const name="String" value="2"/>
9622	</enum>
9623
9624	<enum
9625	name="DataFlags"
9626	uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
9627	>
9628	<const name="None" value="0x00"/>
9629	<const name="Mandatory" value="0x01"/>
9630	<const name="Expert" value="0x02"/>
9631	<const name="Array" value="0x04"/>
9632	<const name="FlagMask" value="0x07"/>
9633	</enum>
9634
9635	<enum
9636	name="MediumFormatCapabilities"
9637	uuid="70fcf810-99e8-4edc-aee4-7f51d489e657"
9638	>
9639	<desc>
9640	Hard disk format capability flags.
9641	</desc>
9642
9643	<const name="Uuid" value="0x01">
9644	<desc>
9645	Supports UUIDs as expected by VirtualBox code.
9646	</desc>
9647	</const>
9648
9649	<const name="CreateFixed" value="0x02">
9650	<desc>
9651	Supports creating fixed size images, allocating all space instantly.
9652	</desc>
9653	</const>
9654
9655	<const name="CreateDynamic" value="0x04">
9656	<desc>
9657	Supports creating dynamically growing images, allocating space on
9658	demand.
9659	</desc>
9660	</const>
9661
9662	<const name="CreateSplit2G" value="0x08">
9663	<desc>
9664	Supports creating images split in chunks of a bit less than 2 GBytes.
9665	</desc>
9666	</const>
9667
9668	<const name="Differencing" value="0x10">
9669	<desc>
9670	Supports being used as a format for differencing media (see <link
9671	to="IMedium::createDiffStorage"/>).
9672	</desc>
9673	</const>
9674
9675	<const name="Asynchronous" value="0x20">
9676	<desc>
9677	Supports asynchronous I/O operations for at least some configurations.
9678	</desc>
9679	</const>
9680
9681	<const name="File" value="0x40">
9682	<desc>
9683	The format backend operates on files (the <link to="IMedium::location"/>
9684	attribute of the medium specifies a file used to store medium
9685	data; for a list of supported file extensions see
9686	<link to="IMediumFormat::fileExtensions"/>).
9687	</desc>
9688	</const>
9689
9690	<const name="Properties" value="0x80">
9691	<desc>
9692	The format backend uses the property interface to configure the storage
9693	location and properties (the <link to="IMediumFormat::describeProperties"/>
9694	method is used to get access to properties supported by the given medium format).
9695	</desc>
9696	</const>
9697
9698	<const name="CapabilityMask" value="0xFF"/>
9699	</enum>
9700
9701	<interface
9702	name="IMediumFormat" extends="$unknown"
9703	uuid="89f52554-d469-4799-9fad-1705e86a08b1"
9704	wsmap="managed"
9705	>
9706	<desc>
9707	The IMediumFormat interface represents a medium format.
9708
9709	Each medium format has an associated backend which is used to handle
9710	media stored in this format. This interface provides information
9711	about the properties of the associated backend.
9712
9713	Each medium format is identified by a string represented by the
9714	<link to="#id"/> attribute. This string is used in calls like
9715	<link to="IVirtualBox::createHardDisk"/> to specify the desired
9716	format.
9717
9718	The list of all supported medium formats can be obtained using
9719	<link to="ISystemProperties::mediaFormats"/>.
9720
9721	<see>IMedium</see>
9722	</desc>
9723
9724	<attribute name="id" type="wstring" readonly="yes">
9725	<desc>
9726	Identifier of this format.
9727
9728	The format identifier is a non-@c null non-empty ASCII string. Note that
9729	this string is case-insensitive. This means that, for example, all of
9730	the following strings:
9731	<pre>
9732	"VDI"
9733	"vdi"
9734	"VdI"</pre>
9735	refer to the same medium format.
9736
9737	This string is used in methods of other interfaces where it is necessary
9738	to specify a medium format, such as
9739	<link to="IVirtualBox::createHardDisk"/>.
9740	</desc>
9741	</attribute>
9742
9743	<attribute name="name" type="wstring" readonly="yes">
9744	<desc>
9745	Human readable description of this format.
9746
9747	Mainly for use in file open dialogs.
9748	</desc>
9749	</attribute>
9750
9751	<attribute name="fileExtensions" type="wstring" safearray="yes" readonly="yes">
9752	<desc>
9753	Array of strings containing the supported file extensions.
9754
9755	The first extension in the array is the extension preferred by the
9756	backend. It is recommended to use this extension when specifying a
9757	location of the storage unit for a new medium.
9758
9759	Note that some backends do not work on files, so this array may be
9760	empty.
9761
9762	<see>IMediumFormat::capabilities</see>
9763	</desc>
9764	</attribute>
9765
9766	<attribute name="capabilities" type="unsigned long" readonly="yes">
9767	<desc>
9768	Capabilities of the format as a set of bit flags.
9769
9770	For the meaning of individual capability flags see
9771	<link to="MediumFormatCapabilities"/>.
9772	</desc>
9773	</attribute>
9774
9775	<method name="describeProperties">
9776	<desc>
9777	Returns several arrays describing the properties supported by this
9778	format.
9779
9780	An element with the given index in each array describes one
9781	property. Thus, the number of elements in each returned array is the
9782	same and corresponds to the number of supported properties.
9783
9784	The returned arrays are filled in only if the
9785	<link to="MediumFormatCapabilities_Properties"/> flag is set.
9786	All arguments must be non-@c null.
9787
9788	<see>DataType</see>
9789	<see>DataFlags</see>
9790	</desc>
9791
9792	<param name="names" type="wstring" safearray="yes" dir="out">
9793	<desc>Array of property names.</desc>
9794	</param>
9795	<param name="description" type="wstring" safearray="yes" dir="out">
9796	<desc>Array of property descriptions.</desc>
9797	</param>
9798	<param name="types" type="DataType" safearray="yes" dir="out">
9799	<desc>Array of property types.</desc>
9800	</param>
9801	<param name="flags" type="unsigned long" safearray="yes" dir="out">
9802	<desc>Array of property flags.</desc>
9803	</param>
9804	<param name="defaults" type="wstring" safearray="yes" dir="out">
9805	<desc>Array of default property values.</desc>
9806	</param>
9807	</method>
9808
9809	</interface>
9810
9811
9812	<!--
9813	// IKeyboard
9814	/////////////////////////////////////////////////////////////////////////
9815	-->
9816
9817	<interface
9818	name="IKeyboard" extends="$unknown"
9819	uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
9820	wsmap="managed"
9821	>
9822	<desc>
9823	The IKeyboard interface represents the virtual machine's keyboard. Used
9824	in <link to="IConsole::keyboard"/>.
9825
9826	Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
9827	to the virtual machine.
9828
9829	</desc>
9830	<method name="putScancode">
9831	<desc>Sends a scancode to the keyboard.
9832
9833	<result name="VBOX_E_IPRT_ERROR">
9834	Could not send scan code to virtual keyboard.
9835	</result>
9836
9837	</desc>
9838	<param name="scancode" type="long" dir="in"/>
9839	</method>
9840
9841	<method name="putScancodes">
9842	<desc>Sends an array of scancodes to the keyboard.
9843
9844	<result name="VBOX_E_IPRT_ERROR">
9845	Could not send all scan codes to virtual keyboard.
9846	</result>
9847
9848	</desc>
9849	<param name="scancodes" type="long" dir="in" safearray="yes"/>
9850	<param name="codesStored" type="unsigned long" dir="return"/>
9851	</method>
9852
9853	<method name="putCAD">
9854	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
9855	function is nothing special, it is just a convenience function
9856	calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
9857
9858	<result name="VBOX_E_IPRT_ERROR">
9859	Could not send all scan codes to virtual keyboard.
9860	</result>
9861
9862	</desc>
9863	</method>
9864
9865	</interface>
9866
9867
9868	<!--
9869	// IMouse
9870	/////////////////////////////////////////////////////////////////////////
9871	-->
9872
9873	<enum
9874	name="MouseButtonState"
9875	uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
9876	>
9877	<desc>
9878	Mouse button state.
9879	</desc>
9880
9881	<const name="LeftButton" value="0x01"/>
9882	<const name="RightButton" value="0x02"/>
9883	<const name="MiddleButton" value="0x04"/>
9884	<const name="WheelUp" value="0x08"/>
9885	<const name="WheelDown" value="0x10"/>
9886	<const name="XButton1" value="0x20"/>
9887	<const name="XButton2" value="0x40"/>
9888	<const name="MouseStateMask" value="0x7F"/>
9889	</enum>
9890
9891	<interface
9892	name="IMouse" extends="$unknown"
9893	uuid="7c0f2eae-f92d-498c-b802-e1a3763774dc"
9894	wsmap="managed"
9895	>
9896	<desc>
9897	The IMouse interface represents the virtual machine's mouse. Used in
9898	<link to="IConsole::mouse"/>.
9899
9900	Through this interface, the virtual machine's virtual mouse can be
9901	controlled.
9902	</desc>
9903
9904	<attribute name="absoluteSupported" type="boolean" readonly="yes">
9905	<desc>
9906	Whether the guest OS supports absolute mouse pointer positioning
9907	or not.
9908	<note>
9909	VirtualBox Guest Tools need to be installed to the guest OS
9910	in order to enable absolute mouse positioning support.
9911	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
9912	callback to be instantly informed about changes of this attribute
9913	during virtual machine execution.
9914	</note>
9915	<see><link to="#putMouseEventAbsolute"/></see>
9916	</desc>
9917	</attribute>
9918
9919	<method name="putMouseEvent">
9920	<desc>
9921	Initiates a mouse event using relative pointer movements
9922	along x and y axis.
9923
9924	<result name="E_ACCESSDENIED">
9925	Console not powered up.
9926	</result>
9927	<result name="VBOX_E_IPRT_ERROR">
9928	Could not send mouse event to virtual mouse.
9929	</result>
9930
9931	</desc>
9932
9933	<param name="dx" type="long" dir="in">
9934	<desc>
9935	Amount of pixels the mouse should move to the right.
9936	Negative values move the mouse to the left.
9937	</desc>
9938	</param>
9939	<param name="dy" type="long" dir="in">
9940	<desc>
9941	Amount of pixels the mouse should move downwards.
9942	Negative values move the mouse upwards.
9943	</desc>
9944	</param>
9945	<param name="dz" type="long" dir="in">
9946	<desc>
9947	Amount of mouse wheel moves.
9948	Positive values describe clockwise wheel rotations,
9949	negative values describe counterclockwise rotations.
9950	</desc>
9951	</param>
9952	<param name="dw" type="long" dir="in">
9953	<desc>
9954	Amount of horizontal mouse wheel moves.
9955	Positive values describe a movement to the left,
9956	negative values describe a movement to the right.
9957	</desc>
9958	</param>
9959	<param name="buttonState" type="long" dir="in">
9960	<desc>
9961	The current state of mouse buttons. Every bit represents
9962	a mouse button as follows:
9963	<table>
9964	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
9965	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
9966	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
9967	</table>
9968	A value of <tt>1</tt> means the corresponding button is pressed.
9969	otherwise it is released.
9970	</desc>
9971	</param>
9972	</method>
9973
9974	<method name="putMouseEventAbsolute">
9975	<desc>
9976	Positions the mouse pointer using absolute x and y coordinates.
9977	These coordinates are expressed in pixels and
9978	start from <tt>[1,1]</tt> which corresponds to the top left
9979	corner of the virtual display.
9980
9981	<result name="E_ACCESSDENIED">
9982	Console not powered up.
9983	</result>
9984	<result name="VBOX_E_IPRT_ERROR">
9985	Could not send mouse event to virtual mouse.
9986	</result>
9987
9988	<note>
9989	This method will have effect only if absolute mouse
9990	positioning is supported by the guest OS.
9991	</note>
9992
9993	<see><link to="#absoluteSupported"/></see>
9994	</desc>
9995
9996	<param name="x" type="long" dir="in">
9997	<desc>
9998	X coordinate of the pointer in pixels, starting from @c 1.
9999	</desc>
10000	</param>
10001	<param name="y" type="long" dir="in">
10002	<desc>
10003	Y coordinate of the pointer in pixels, starting from @c 1.
10004	</desc>
10005	</param>
10006	<param name="dz" type="long" dir="in">
10007	<desc>
10008	Amount of mouse wheel moves.
10009	Positive values describe clockwise wheel rotations,
10010	negative values describe counterclockwise rotations.
10011	</desc>
10012	</param>
10013	<param name="dw" type="long" dir="in">
10014	<desc>
10015	Amount of horizontal mouse wheel moves.
10016	Positive values describe a movement to the left,
10017	negative values describe a movement to the right.
10018	</desc>
10019	</param>
10020	<param name="buttonState" type="long" dir="in">
10021	<desc>
10022	The current state of mouse buttons. Every bit represents
10023	a mouse button as follows:
10024	<table>
10025	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
10026	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
10027	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
10028	</table>
10029	A value of @c 1 means the corresponding button is pressed.
10030	otherwise it is released.
10031	</desc>
10032	</param>
10033	</method>
10034
10035	</interface>
10036
10037	<!--
10038	// IDisplay
10039	/////////////////////////////////////////////////////////////////////////
10040	-->
10041
10042	<enum
10043	name="FramebufferPixelFormat"
10044	uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
10045	>
10046	<desc>
10047	Format of the video memory buffer. Constants represented by this enum can
10048	be used to test for particular values of <link
10049	to="IFramebuffer::pixelFormat"/>. See also <link
10050	to="IFramebuffer::requestResize"/>.
10051
10052	See also www.fourcc.org for more information about FOURCC pixel formats.
10053	</desc>
10054
10055	<const name="Opaque" value="0">
10056	<desc>
10057	Unknown buffer format (the user may not assume any particular format of
10058	the buffer).
10059	</desc>
10060	</const>
10061	<const name="FOURCC_RGB" value="0x32424752">
10062	<desc>
10063	Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
10064	bit layout).
10065	</desc>
10066	</const>
10067	</enum>
10068
10069	<interface
10070	name="IFramebuffer" extends="$unknown"
10071	uuid="b7ed347a-5765-40a0-ae1c-f543eb4ddeaf"
10072	wsmap="suppress"
10073	>
10074	<attribute name="address" type="octet" mod="ptr" readonly="yes">
10075	<desc>Address of the start byte of the frame buffer.</desc>
10076	</attribute>
10077
10078	<attribute name="width" type="unsigned long" readonly="yes">
10079	<desc>Frame buffer width, in pixels.</desc>
10080	</attribute>
10081
10082	<attribute name="height" type="unsigned long" readonly="yes">
10083	<desc>Frame buffer height, in pixels.</desc>
10084	</attribute>
10085
10086	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
10087	<desc>
10088	Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
10089	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
10090	are: 8, 15, 16, 24 and 32.
10091	</desc>
10092	</attribute>
10093
10094	<attribute name="bytesPerLine" type="unsigned long" readonly="yes">
10095	<desc>
10096	Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
10097	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
10098	size of the scan line must be aligned to 32 bits.
10099	</desc>
10100	</attribute>
10101
10102	<attribute name="pixelFormat" type="unsigned long" readonly="yes">
10103	<desc>
10104	Frame buffer pixel format. It's either one of the values defined by <link
10105	to="FramebufferPixelFormat"/> or a raw FOURCC code.
10106	<note>
10107	This attribute must never return <link
10108	to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
10109	<link to="#address"/> points to must be always known.
10110	</note>
10111	</desc>
10112	</attribute>
10113
10114	<attribute name="usesGuestVRAM" type="boolean" readonly="yes">
10115	<desc>
10116	Defines whether this frame buffer uses the virtual video card's memory
10117	buffer (guest VRAM) directly or not. See <link
10118	to="IFramebuffer::requestResize"/> for more information.
10119	</desc>
10120	</attribute>
10121
10122	<attribute name="heightReduction" type="unsigned long" readonly="yes">
10123	<desc>
10124	Hint from the frame buffer about how much of the standard
10125	screen height it wants to use for itself. This information is
10126	exposed to the guest through the VESA BIOS and VMMDev interface
10127	so that it can use it for determining its video mode table. It
10128	is not guaranteed that the guest respects the value.
10129	</desc>
10130	</attribute>
10131
10132	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
10133	<desc>
10134	An alpha-blended overlay which is superposed over the frame buffer.
10135	The initial purpose is to allow the display of icons providing
10136	information about the VM state, including disk activity, in front
10137	ends which do not have other means of doing that. The overlay is
10138	designed to controlled exclusively by IDisplay. It has no locking
10139	of its own, and any changes made to it are not guaranteed to be
10140	visible until the affected portion of IFramebuffer is updated. The
10141	overlay can be created lazily the first time it is requested. This
10142	attribute can also return @c null to signal that the overlay is not
10143	implemented.
10144	</desc>
10145	</attribute>
10146
10147	<attribute name="winId" type="unsigned long long" readonly="yes">
10148	<desc>
10149	Platform-dependent identifier of the window where context of this
10150	frame buffer is drawn, or zero if there's no such window.
10151	</desc>
10152	</attribute>
10153
10154	<method name="lock">
10155	<desc>
10156	Locks the frame buffer.
10157	Gets called by the IDisplay object where this frame buffer is
10158	bound to.
10159	</desc>
10160	</method>
10161
10162	<method name="unlock">
10163	<desc>
10164	Unlocks the frame buffer.
10165	Gets called by the IDisplay object where this frame buffer is
10166	bound to.
10167	</desc>
10168	</method>
10169
10170	<method name="notifyUpdate">
10171	<desc>
10172	Informs about an update.
10173	Gets called by the display object where this buffer is
10174	registered.
10175	</desc>
10176	<param name="x" type="unsigned long" dir="in"/>
10177	<param name="y" type="unsigned long" dir="in"/>
10178	<param name="width" type="unsigned long" dir="in"/>
10179	<param name="height" type="unsigned long" dir="in"/>
10180	</method>
10181
10182	<method name="requestResize">
10183	<desc>
10184	Requests a size and pixel format change.
10185
10186	There are two modes of working with the video buffer of the virtual
10187	machine. The <i>indirect</i> mode implies that the IFramebuffer
10188	implementation allocates a memory buffer for the requested display mode
10189	and provides it to the virtual machine. In <i>direct</i> mode, the
10190	IFramebuffer implementation uses the memory buffer allocated and owned
10191	by the virtual machine. This buffer represents the video memory of the
10192	emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
10193	usually faster because the implementation gets a raw pointer to the
10194	guest VRAM buffer which it can directly use for visualizing the contents
10195	of the virtual display, as opposed to the indirect mode where the
10196	contents of guest VRAM are copied to the memory buffer provided by
10197	the implementation every time a display update occurs.
10198
10199	It is important to note that the direct mode is really fast only when
10200	the implementation uses the given guest VRAM buffer directly, for
10201	example, by blitting it to the window representing the virtual machine's
10202	display, which saves at least one copy operation comparing to the
10203	indirect mode. However, using the guest VRAM buffer directly is not
10204	always possible: the format and the color depth of this buffer may be
10205	not supported by the target window, or it may be unknown (opaque) as in
10206	case of text or non-linear multi-plane VGA video modes. In this case,
10207	the indirect mode (that is always available) should be used as a
10208	fallback: when the guest VRAM contents are copied to the
10209	implementation-provided memory buffer, color and format conversion is
10210	done automatically by the underlying code.
10211
10212	The @a pixelFormat parameter defines whether the direct mode is
10213	available or not. If @a pixelFormat is <link
10214	to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
10215	VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
10216	@a bytesPerLine parameters must be ignored and the implementation must use
10217	the indirect mode (where it provides its own buffer in one of the
10218	supported formats). In all other cases, @a pixelFormat together with
10219	@a bitsPerPixel and @a bytesPerLine define the format of the video memory
10220	buffer pointed to by the @a VRAM parameter and the implementation is
10221	free to choose which mode to use. To indicate that this frame buffer uses
10222	the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
10223	attribute must return @c true and <link to="#address"/> must
10224	return exactly the same address that is passed in the @a VRAM parameter
10225	of this method; otherwise it is assumed that the indirect strategy is
10226	chosen.
10227
10228	The @a width and @a height parameters represent the size of the
10229	requested display mode in both modes. In case of indirect mode, the
10230	provided memory buffer should be big enough to store data of the given
10231	display mode. In case of direct mode, it is guaranteed that the given
10232	@a VRAM buffer contains enough space to represent the display mode of the
10233	given size. Note that this frame buffer's <link to="#width"/> and <link
10234	to="#height"/> attributes must return exactly the same values as
10235	passed to this method after the resize is completed (see below).
10236
10237	The @a finished output parameter determines if the implementation has
10238	finished resizing the frame buffer or not. If, for some reason, the
10239	resize cannot be finished immediately during this call, @a finished
10240	must be set to @c false, and the implementation must call
10241	<link to="IDisplay::resizeCompleted"/> after it has returned from
10242	this method as soon as possible. If @a finished is @c false, the
10243	machine will not call any frame buffer methods until
10244	<link to="IDisplay::resizeCompleted"/> is called.
10245
10246	Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
10247	<link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
10248	this frame buffer must return exactly the same values as specified in the
10249	parameters of this method, after the resize is completed. If the
10250	indirect mode is chosen, these attributes must return values describing
10251	the format of the implementation's own memory buffer <link
10252	to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
10253	value must always correlate with <link to="#pixelFormat"/>. Note that
10254	the <link to="#pixelFormat"/> attribute must never return <link
10255	to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
10256
10257	<note>
10258	This method is called by the IDisplay object under the
10259	<link to="#lock"/> provided by this IFramebuffer
10260	implementation. If this method returns @c false in @a finished, then
10261	this lock is not released until
10262	<link to="IDisplay::resizeCompleted"/> is called.
10263	</note>
10264	</desc>
10265	<param name="screenId" type="unsigned long" dir="in">
10266	<desc>
10267	Logical screen number. Must be used in the corresponding call to
10268	<link to="IDisplay::resizeCompleted"/> if this call is made.
10269	</desc>
10270	</param>
10271	<param name="pixelFormat" type="unsigned long" dir="in">
10272	<desc>
10273	Pixel format of the memory buffer pointed to by @a VRAM.
10274	See also <link to="FramebufferPixelFormat"/>.
10275	</desc>
10276	</param>
10277	<param name="VRAM" type="octet" mod="ptr" dir="in">
10278	<desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
10279	</param>
10280	<param name="bitsPerPixel" type="unsigned long" dir="in">
10281	<desc>Color depth, bits per pixel.</desc>
10282	</param>
10283	<param name="bytesPerLine" type="unsigned long" dir="in">
10284	<desc>Size of one scan line, in bytes.</desc>
10285	</param>
10286	<param name="width" type="unsigned long" dir="in">
10287	<desc>Width of the guest display, in pixels.</desc>
10288	</param>
10289	<param name="height" type="unsigned long" dir="in">
10290	<desc>Height of the guest display, in pixels.</desc>
10291	</param>
10292	<param name="finished" type="boolean" dir="return">
10293	<desc>
10294	Can the VM start using the new frame buffer immediately
10295	after this method returns or it should wait for
10296	<link to="IDisplay::resizeCompleted"/>.
10297	</desc>
10298	</param>
10299	</method>
10300
10301	<method name="videoModeSupported">
10302	<desc>
10303	Returns whether the frame buffer implementation is willing to
10304	support a given video mode. In case it is not able to render
10305	the video mode (or for some reason not willing), it should
10306	return @c false. Usually this method is called when the guest
10307	asks the VMM device whether a given video mode is supported
10308	so the information returned is directly exposed to the guest.
10309	It is important that this method returns very quickly.
10310	</desc>
10311	<param name="width" type="unsigned long" dir="in"/>
10312	<param name="height" type="unsigned long" dir="in"/>
10313	<param name="bpp" type="unsigned long" dir="in"/>
10314	<param name="supported" type="boolean" dir="return"/>
10315	</method>
10316
10317	<method name="getVisibleRegion">
10318	<desc>
10319	Returns the visible region of this frame buffer.
10320
10321	If the @a rectangles parameter is @c null then the value of the
10322	@a count parameter is ignored and the number of elements necessary to
10323	describe the current visible region is returned in @a countCopied.
10324
10325	If @a rectangles is not @c null but @a count is less
10326	than the required number of elements to store region data, the method
10327	will report a failure. If @a count is equal or greater than the
10328	required number of elements, then the actual number of elements copied
10329	to the provided array will be returned in @a countCopied.
10330
10331	<note>
10332	The address of the provided array must be in the process space of
10333	this IFramebuffer object.
10334	</note>
10335	<note>
10336	Method not yet implemented.
10337	</note>
10338	</desc>
10339	<param name="rectangles" type="octet" mod="ptr" dir="in">
10340	<desc>Pointer to the @c RTRECT array to receive region data.</desc>
10341	</param>
10342	<param name="count" type="unsigned long" dir="in">
10343	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
10344	</param>
10345	<param name="countCopied" type="unsigned long" dir="return">
10346	<desc>Number of elements copied to the @a rectangles array.</desc>
10347	</param>
10348	</method>
10349
10350	<method name="setVisibleRegion">
10351	<desc>
10352	Suggests a new visible region to this frame buffer. This region
10353	represents the area of the VM display which is a union of regions of
10354	all top-level windows of the guest operating system running inside the
10355	VM (if the Guest Additions for this system support this
10356	functionality). This information may be used by the frontends to
10357	implement the seamless desktop integration feature.
10358
10359	<note>
10360	The address of the provided array must be in the process space of
10361	this IFramebuffer object.
10362	</note>
10363	<note>
10364	The IFramebuffer implementation must make a copy of the provided
10365	array of rectangles.
10366	</note>
10367	<note>
10368	Method not yet implemented.
10369	</note>
10370	</desc>
10371	<param name="rectangles" type="octet" mod="ptr" dir="in">
10372	<desc>Pointer to the @c RTRECT array.</desc>
10373	</param>
10374	<param name="count" type="unsigned long" dir="in">
10375	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
10376	</param>
10377	</method>
10378
10379	<method name="processVHWACommand">
10380	<desc>
10381	Posts a Video HW Acceleration Command to the frame buffer for processing.
10382	The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color covnersion, overlaying, etc.)
10383	are posted from quest to the host to be processed by the host hardware.
10384
10385	<note>
10386	The address of the provided command must be in the process space of
10387	this IFramebuffer object.
10388	</note>
10389	</desc>
10390
10391	<param name="command" type="octet" mod="ptr" dir="in">
10392	<desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
10393	</param>
10394	</method>
10395
10396	</interface>
10397
10398	<interface
10399	name="IFramebufferOverlay" extends="IFramebuffer"
10400	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
10401	wsmap="suppress"
10402	>
10403	<desc>
10404	The IFramebufferOverlay interface represents an alpha blended overlay
10405	for displaying status icons above an IFramebuffer. It is always created
10406	not visible, so that it must be explicitly shown. It only covers a
10407	portion of the IFramebuffer, determined by its width, height and
10408	co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
10409	that order) format, and may be written to directly. Do re-read the
10410	width though, after setting it, as it may be adjusted (increased) to
10411	make it more suitable for the front end.
10412	</desc>
10413	<attribute name="x" type="unsigned long" readonly="yes">
10414	<desc>X position of the overlay, relative to the frame buffer.</desc>
10415	</attribute>
10416
10417	<attribute name="y" type="unsigned long" readonly="yes">
10418	<desc>Y position of the overlay, relative to the frame buffer.</desc>
10419	</attribute>
10420
10421	<attribute name="visible" type="boolean" readonly="no">
10422	<desc>
10423	Whether the overlay is currently visible.
10424	</desc>
10425	</attribute>
10426
10427	<attribute name="alpha" type="unsigned long" readonly="no">
10428	<desc>
10429	The global alpha value for the overlay. This may or may not be
10430	supported by a given front end.
10431	</desc>
10432	</attribute>
10433
10434	<method name="move">
10435	<desc>
10436	Changes the overlay's position relative to the IFramebuffer.
10437	</desc>
10438	<param name="x" type="unsigned long" dir="in"/>
10439	<param name="y" type="unsigned long" dir="in"/>
10440	</method>
10441
10442	</interface>
10443
10444	<interface
10445	name="IDisplay" extends="$unknown"
10446	uuid="e2a38ebc-d854-4a3e-bc2e-fdf5ac4a0000"
10447	wsmap="managed"
10448	>
10449	<desc>
10450	The IDisplay interface represents the virtual machine's display.
10451
10452	The object implementing this interface is contained in each
10453	<link to="IConsole::display"/> attribute and represents the visual
10454	output of the virtual machine.
10455
10456	The virtual display supports pluggable output targets represented by the
10457	IFramebuffer interface. Examples of the output target are a window on
10458	the host computer or an RDP session's display on a remote computer.
10459	</desc>
10460	<attribute name="width" type="unsigned long" readonly="yes">
10461	<desc>Current display width.</desc>
10462	</attribute>
10463
10464	<attribute name="height" type="unsigned long" readonly="yes">
10465	<desc>Current display height.</desc>
10466	</attribute>
10467
10468	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
10469	<desc>
10470	Current guest display color depth. Note that this may differ
10471	from <link to="IFramebuffer::bitsPerPixel"/>.
10472	</desc>
10473	</attribute>
10474
10475	<method name="setFramebuffer">
10476	<desc>
10477	Sets the framebuffer for given screen.
10478	</desc>
10479	<param name="screenId" type="unsigned long" dir="in"/>
10480	<param name="framebuffer" type="IFramebuffer" dir="in"/>
10481	</method>
10482
10483	<method name="getFramebuffer">
10484	<desc>
10485	Queries the framebuffer for given screen.
10486	</desc>
10487	<param name="screenId" type="unsigned long" dir="in"/>
10488	<param name="framebuffer" type="IFramebuffer" dir="out"/>
10489	<param name="xOrigin" type="long" dir="out"/>
10490	<param name="yOrigin" type="long" dir="out"/>
10491	</method>
10492
10493	<method name="setVideoModeHint">
10494	<desc>
10495	Asks VirtualBox to request the given video mode from
10496	the guest. This is just a hint and it cannot be guaranteed
10497	that the requested resolution will be used. Guest Additions
10498	are required for the request to be seen by guests. The caller
10499	should issue the request and wait for a resolution change and
10500	after a timeout retry.
10501
10502	Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
10503	parameters means that the corresponding values should be taken from the
10504	current video mode (i.e. left unchanged).
10505
10506	If the guest OS supports multi-monitor configuration then the @a display
10507	parameter specifies the number of the guest display to send the hint to:
10508	@c 0 is the primary display, @c 1 is the first secondary and
10509	so on. If the multi-monitor configuration is not supported, @a display
10510	must be @c 0.
10511
10512	<result name="E_INVALIDARG">
10513	The @a display is not associated with any monitor.
10514	</result>
10515
10516	</desc>
10517	<param name="width" type="unsigned long" dir="in"/>
10518	<param name="height" type="unsigned long" dir="in"/>
10519	<param name="bitsPerPixel" type="unsigned long" dir="in"/>
10520	<param name="display" type="unsigned long" dir="in"/>
10521	</method>
10522
10523	<method name="setSeamlessMode">
10524	<desc>
10525	Enables or disables seamless guest display rendering (seamless desktop
10526	integration) mode.
10527	<note>
10528	Calling this method has no effect if <link
10529	to="IGuest::supportsSeamless"/> returns @c false.
10530	</note>
10531	</desc>
10532	<param name="enabled" type="boolean" dir="in"/>
10533	</method>
10534
10535	<method name="takeScreenShot">
10536	<desc>
10537	Takes a screen shot of the requested size and copies it to the
10538	32-bpp buffer allocated by the caller and pointed to by @a address.
10539
10540	<note>This API can be used only by the COM/XPCOM C++ API as it
10541	requires pointer support. Use <link to="#takeScreenShotSlow" />
10542	with other language bindings.
10543	</note>
10544
10545	<result name="E_NOTIMPL">
10546	Feature not implemented.
10547	</result>
10548	<result name="VBOX_E_IPRT_ERROR">
10549	Could not take a screenshot.
10550	</result>
10551
10552	</desc>
10553	<param name="address" type="octet" mod="ptr" dir="in"/>
10554	<param name="width" type="unsigned long" dir="in"/>
10555	<param name="height" type="unsigned long" dir="in"/>
10556	</method>
10557
10558	<method name="takeScreenShotSlow">
10559	<desc>
10560	Takes a guest screen shot of the requested size and returns it as
10561	an array of bytes in uncompressed 32-bit ARGB format.
10562	This API is slow, but could be the only option to get guest screenshot
10563	for scriptable languages not allowed to manipulate with addresses
10564	directly.
10565
10566	<result name="E_NOTIMPL">
10567	Feature not implemented.
10568	</result>
10569	<result name="VBOX_E_IPRT_ERROR">
10570	Could not take a screenshot.
10571	</result>
10572	</desc>
10573	<param name="width" type="unsigned long" dir="in">
10574	<desc>
10575	Desired image width.
10576	</desc>
10577	</param>
10578	<param name="height" type="unsigned long" dir="in">
10579	<desc>
10580	Desired image height.
10581	</desc>
10582	</param>
10583	<param name="screenData" type="octet" dir="return" safearray="yes">
10584	<desc>
10585	Array with resulting screen data.
10586	</desc>
10587	</param>
10588	</method>
10589
10590	<method name="drawToScreen">
10591	<desc>
10592	Draws a 32-bpp image of the specified size from the given buffer
10593	to the given point on the VM display.
10594
10595	<result name="E_NOTIMPL">
10596	Feature not implemented.
10597	</result>
10598	<result name="VBOX_E_IPRT_ERROR">
10599	Could not draw to screen.
10600	</result>
10601
10602	</desc>
10603	<param name="address" type="octet" mod="ptr" dir="in"/>
10604	<param name="x" type="unsigned long" dir="in"/>
10605	<param name="y" type="unsigned long" dir="in"/>
10606	<param name="width" type="unsigned long" dir="in"/>
10607	<param name="height" type="unsigned long" dir="in"/>
10608	</method>
10609
10610	<method name="invalidateAndUpdate">
10611	<desc>
10612	Does a full invalidation of the VM display and instructs the VM
10613	to update it.
10614
10615	<result name="VBOX_E_IPRT_ERROR">
10616	Could not invalidate and update screen.
10617	</result>
10618
10619	</desc>
10620	</method>
10621
10622	<method name="resizeCompleted">
10623	<desc>
10624	Signals that a framebuffer has completed the resize operation.
10625
10626	<result name="VBOX_E_NOT_SUPPORTED">
10627	Operation only valid for external frame buffers.
10628	</result>
10629
10630	</desc>
10631	<param name="screenId" type="unsigned long" dir="in"/>
10632	</method>
10633
10634	<method name="updateCompleted">
10635	<desc>
10636	Signals that a framebuffer has completed the update operation.
10637
10638	<result name="VBOX_E_NOT_SUPPORTED">
10639	Operation only valid for external frame buffers.
10640	</result>
10641
10642	</desc>
10643	</method>
10644
10645	<method name="completeVHWACommand">
10646	<desc>
10647	Signals that the Video HW Acceleration command has completed.
10648	</desc>
10649
10650	<param name="command" type="octet" mod="ptr" dir="in">
10651	<desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
10652	</param>
10653	</method>
10654
10655	</interface>
10656
10657	<!--
10658	// INetworkAdapter
10659	/////////////////////////////////////////////////////////////////////////
10660	-->
10661
10662	<enum
10663	name="NetworkAttachmentType"
10664	uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
10665	>
10666	<desc>
10667	Network attachment type.
10668	</desc>
10669
10670	<const name="Null" value="0">
10671	<desc>Null value, also means "not attached".</desc>
10672	</const>
10673	<const name="NAT" value="1"/>
10674	<const name="Bridged" value="2"/>
10675	<const name="Internal" value="3"/>
10676	<const name="HostOnly" value="4"/>
10677	</enum>
10678
10679	<enum
10680	name="NetworkAdapterType"
10681	uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
10682	>
10683	<desc>
10684	Network adapter type.
10685	</desc>
10686
10687	<const name="Null" value="0">
10688	<desc>Null value (never used by the API).</desc>
10689	</const>
10690	<const name="Am79C970A" value="1">
10691	<desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
10692	</const>
10693	<const name="Am79C973" value="2">
10694	<desc>AMD PCNet-FAST III network card (Am79C973).</desc>
10695	</const>
10696	<const name="I82540EM" value="3">
10697	<desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
10698	</const>
10699	<const name="I82543GC" value="4">
10700	<desc>Intel PRO/1000 T Server network card (82543GC).</desc>
10701	</const>
10702	<const name="I82545EM" value="5">
10703	<desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
10704	</const>
10705	<const name="Virtio" value="6">
10706	<desc>Virtio network device.</desc>
10707	</const>
10708	</enum>
10709
10710	<interface
10711	name="INetworkAdapter" extends="$unknown"
10712	uuid="65607a27-2b73-4d43-b4cc-0ba2c817fbde"
10713	wsmap="managed"
10714	>
10715	<desc>
10716	Represents a virtual network adapter that is attached to a virtual machine.
10717	Each virtual machine has a fixed number of network adapter slots with one
10718	instance of this attached to each of them. Call
10719	<link to="IMachine::getNetworkAdapter" /> to get the network adapter that
10720	is attached to a given slot in a given machine.
10721
10722	Each network adapter can be in one of five attachment modes, which are
10723	represented by the <link to="NetworkAttachmentType" /> enumeration;
10724	see the <link to="#attachmentType" /> attribute.
10725	</desc>
10726
10727	<attribute name="adapterType" type="NetworkAdapterType">
10728	<desc>
10729	Type of the virtual network adapter. Depending on this value,
10730	VirtualBox will provide a different virtual network hardware
10731	to the guest.
10732	</desc>
10733	</attribute>
10734
10735	<attribute name="slot" type="unsigned long" readonly="yes">
10736	<desc>
10737	Slot number this adapter is plugged into. Corresponds to
10738	the value you pass to <link to="IMachine::getNetworkAdapter"/>
10739	to obtain this instance.
10740	</desc>
10741	</attribute>
10742
10743	<attribute name="enabled" type="boolean">
10744	<desc>
10745	Flag whether the network adapter is present in the
10746	guest system. If disabled, the virtual guest hardware will
10747	not contain this network adapter. Can only be changed when
10748	the VM is not running.
10749	</desc>
10750	</attribute>
10751
10752	<attribute name="MACAddress" type="wstring">
10753	<desc>
10754	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
10755	it to @c null or an empty string, VirtualBox will generate a unique MAC address.
10756	</desc>
10757	</attribute>
10758
10759	<attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
10760
10761	<attribute name="hostInterface" type="wstring">
10762	<desc>
10763	Name of the host network interface the VM is attached to.
10764	</desc>
10765	</attribute>
10766
10767	<attribute name="internalNetwork" type="wstring">
10768	<desc>
10769	Name of the internal network the VM is attached to.
10770	</desc>
10771	</attribute>
10772
10773	<attribute name="NATNetwork" type="wstring">
10774	<desc>
10775	Name of the NAT network the VM is attached to.
10776	</desc>
10777	</attribute>
10778
10779	<attribute name="cableConnected" type="boolean">
10780	<desc>
10781	Flag whether the adapter reports the cable as connected or not.
10782	It can be used to report offline situations to a VM.
10783	</desc>
10784	</attribute>
10785
10786	<attribute name="lineSpeed" type="unsigned long">
10787	<desc>
10788	Line speed reported by custom drivers, in units of 1 kbps.
10789	</desc>
10790	</attribute>
10791
10792	<attribute name="traceEnabled" type="boolean">
10793	<desc>
10794	Flag whether network traffic from/to the network card should be traced.
10795	Can only be toggled when the VM is turned off.
10796	</desc>
10797	</attribute>
10798
10799	<attribute name="traceFile" type="wstring">
10800	<desc>
10801	Filename where a network trace will be stored. If not set, VBox-pid.pcap
10802	will be used.
10803	</desc>
10804	</attribute>
10805
10806	<method name="attachToNAT">
10807	<desc>
10808	Attach the network adapter to the Network Address Translation (NAT) interface.
10809	</desc>
10810	</method>
10811
10812	<method name="attachToBridgedInterface">
10813	<desc>
10814	Attach the network adapter to a bridged host interface.
10815	</desc>
10816	</method>
10817
10818	<method name="attachToInternalNetwork">
10819	<desc>
10820	Attach the network adapter to an internal network.
10821	</desc>
10822	</method>
10823
10824	<method name="attachToHostOnlyInterface">
10825	<desc>
10826	Attach the network adapter to the host-only network.
10827	</desc>
10828	</method>
10829
10830	<method name="detach">
10831	<desc>
10832	Detach the network adapter
10833	</desc>
10834	</method>
10835	</interface>
10836
10837
10838	<!--
10839	// ISerialPort
10840	/////////////////////////////////////////////////////////////////////////
10841	-->
10842
10843	<enum
10844	name="PortMode"
10845	uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
10846	>
10847	<desc>
10848	The PortMode enumeration represents possible communication modes for
10849	the virtual serial port device.
10850	</desc>
10851
10852	<const name="Disconnected" value="0">
10853	<desc>Virtual device is not attached to any real host device.</desc>
10854	</const>
10855	<const name="HostPipe" value="1">
10856	<desc>Virtual device is attached to a host pipe.</desc>
10857	</const>
10858	<const name="HostDevice" value="2">
10859	<desc>Virtual device is attached to a host device.</desc>
10860	</const>
10861	<const name="RawFile" value="3">
10862	<desc>Virtual device is attached to a raw file.</desc>
10863	</const>
10864	</enum>
10865
10866	<interface
10867	name="ISerialPort" extends="$unknown"
10868	uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
10869	wsmap="managed"
10870	>
10871
10872	<desc>
10873	The ISerialPort interface represents the virtual serial port device.
10874
10875	The virtual serial port device acts like an ordinary serial port
10876	inside the virtual machine. This device communicates to the real
10877	serial port hardware in one of two modes: host pipe or host device.
10878
10879	In host pipe mode, the #path attribute specifies the path to the pipe on
10880	the host computer that represents a serial port. The #server attribute
10881	determines if this pipe is created by the virtual machine process at
10882	machine startup or it must already exist before starting machine
10883	execution.
10884
10885	In host device mode, the #path attribute specifies the name of the
10886	serial port device on the host computer.
10887
10888	There is also a third communication mode: the disconnected mode. In this
10889	mode, the guest OS running inside the virtual machine will be able to
10890	detect the serial port, but all port write operations will be discarded
10891	and all port read operations will return no data.
10892
10893	<see>IMachine::getSerialPort</see>
10894	</desc>
10895
10896	<attribute name="slot" type="unsigned long" readonly="yes">
10897	<desc>
10898	Slot number this serial port is plugged into. Corresponds to
10899	the value you pass to <link to="IMachine::getSerialPort"/>
10900	to obtain this instance.
10901	</desc>
10902	</attribute>
10903
10904	<attribute name="enabled" type="boolean">
10905	<desc>
10906	Flag whether the serial port is enabled. If disabled,
10907	the serial port will not be reported to the guest OS.
10908	</desc>
10909	</attribute>
10910
10911	<attribute name="IOBase" type="unsigned long">
10912	<desc>Base I/O address of the serial port.</desc>
10913	</attribute>
10914
10915	<attribute name="IRQ" type="unsigned long">
10916	<desc>IRQ number of the serial port.</desc>
10917	</attribute>
10918
10919	<attribute name="hostMode" type="PortMode">
10920	<desc>
10921	How is this port connected to the host.
10922	<note>
10923	Changing this attribute may fail if the conditions for
10924	<link to="#path"/> are not met.
10925	</note>
10926	</desc>
10927	</attribute>
10928
10929	<attribute name="server" type="boolean">
10930	<desc>
10931	Flag whether this serial port acts as a server (creates a new pipe on
10932	the host) or as a client (uses the existing pipe). This attribute is
10933	used only when <link to="#hostMode"/> is PortMode_HostPipe.
10934	</desc>
10935	</attribute>
10936
10937	<attribute name="path" type="wstring">
10938	<desc>
10939	Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
10940	PortMode_HostPipe, or the host serial device name when
10941	<link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
10942	cases, setting a @c null or empty string as the attribute's value
10943	is an error. Otherwise, the value of this property is ignored.
10944	</desc>
10945	</attribute>
10946
10947	</interface>
10948
10949	<!--
10950	// IParallelPort
10951	/////////////////////////////////////////////////////////////////////////
10952	-->
10953
10954	<interface
10955	name="IParallelPort" extends="$unknown"
10956	uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
10957	wsmap="managed"
10958	>
10959
10960	<desc>
10961	The IParallelPort interface represents the virtual parallel port device.
10962
10963	The virtual parallel port device acts like an ordinary parallel port
10964	inside the virtual machine. This device communicates to the real
10965	parallel port hardware using the name of the parallel device on the host
10966	computer specified in the #path attribute.
10967
10968	Each virtual parallel port device is assigned a base I/O address and an
10969	IRQ number that will be reported to the guest operating system and used
10970	to operate the given parallel port from within the virtual machine.
10971
10972	<see>IMachine::getParallelPort</see>
10973	</desc>
10974
10975	<attribute name="slot" type="unsigned long" readonly="yes">
10976	<desc>
10977	Slot number this parallel port is plugged into. Corresponds to
10978	the value you pass to <link to="IMachine::getParallelPort"/>
10979	to obtain this instance.
10980	</desc>
10981	</attribute>
10982
10983	<attribute name="enabled" type="boolean">
10984	<desc>
10985	Flag whether the parallel port is enabled. If disabled,
10986	the parallel port will not be reported to the guest OS.
10987	</desc>
10988	</attribute>
10989
10990	<attribute name="IOBase" type="unsigned long">
10991	<desc>Base I/O address of the parallel port.</desc>
10992	</attribute>
10993
10994	<attribute name="IRQ" type="unsigned long">
10995	<desc>IRQ number of the parallel port.</desc>
10996	</attribute>
10997
10998	<attribute name="path" type="wstring">
10999	<desc>
11000	Host parallel device name. If this parallel port is enabled, setting a
11001	@c null or an empty string as this attribute's value will result into
11002	an error.
11003	</desc>
11004	</attribute>
11005
11006	</interface>
11007
11008
11009	<!--
11010	// IMachineDebugger
11011	/////////////////////////////////////////////////////////////////////////
11012	-->
11013
11014	<interface
11015	name="IMachineDebugger" extends="$unknown"
11016	uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
11017	wsmap="suppress"
11018	>
11019	<method name="resetStats">
11020	<desc>
11021	Reset VM statistics.
11022	</desc>
11023	<param name="pattern" type="wstring" dir="in">
11024	<desc>The selection pattern. A bit similar to filename globbing.</desc>
11025	</param>
11026	</method>
11027
11028	<method name="dumpStats">
11029	<desc>
11030	Dumps VM statistics.
11031	</desc>
11032	<param name="pattern" type="wstring" dir="in">
11033	<desc>The selection pattern. A bit similar to filename globbing.</desc>
11034	</param>
11035	</method>
11036
11037	<method name="getStats">
11038	<desc>
11039	Get the VM statistics in a XMLish format.
11040	</desc>
11041	<param name="pattern" type="wstring" dir="in">
11042	<desc>The selection pattern. A bit similar to filename globbing.</desc>
11043	</param>
11044	<param name="withDescriptions" type="boolean" dir="in">
11045	<desc>Whether to include the descriptions.</desc>
11046	</param>
11047	<param name="stats" type="wstring" dir="out">
11048	<desc>The XML document containing the statistics.</desc>
11049	</param>
11050	</method>
11051
11052	<method name="injectNMI">
11053	<desc>
11054	Inject an NMI into a running VT-x/AMD-V VM.
11055	</desc>
11056	</method>
11057
11058	<attribute name="singlestep" type="boolean">
11059	<desc>Switch for enabling singlestepping.</desc>
11060	</attribute>
11061
11062	<attribute name="recompileUser" type="boolean">
11063	<desc>Switch for forcing code recompilation for user mode code.</desc>
11064	</attribute>
11065
11066	<attribute name="recompileSupervisor" type="boolean">
11067	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
11068	</attribute>
11069
11070	<attribute name="PATMEnabled" type="boolean">
11071	<desc>Switch for enabling and disabling the PATM component.</desc>
11072	</attribute>
11073
11074	<attribute name="CSAMEnabled" type="boolean">
11075	<desc>Switch for enabling and disabling the CSAM component.</desc>
11076	</attribute>
11077
11078	<attribute name="logEnabled" type="boolean">
11079	<desc>Switch for enabling and disabling logging.</desc>
11080	</attribute>
11081
11082	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
11083	<desc>
11084	Flag indicating whether the VM is currently making use of CPU hardware
11085	virtualization extensions.
11086	</desc>
11087	</attribute>
11088
11089	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
11090	<desc>
11091	Flag indicating whether the VM is currently making use of the nested paging
11092	CPU hardware virtualization extension.
11093	</desc>
11094	</attribute>
11095
11096	<attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
11097	<desc>
11098	Flag indicating whether the VM is currently making use of the VPID
11099	VT-x extension.
11100	</desc>
11101	</attribute>
11102
11103	<attribute name="PAEEnabled" type="boolean" readonly="yes">
11104	<desc>
11105	Flag indicating whether the VM is currently making use of the Physical
11106	Address Extension CPU feature.
11107	</desc>
11108	</attribute>
11109
11110	<attribute name="virtualTimeRate" type="unsigned long">
11111	<desc>
11112	The rate at which the virtual time runs expressed as a percentage.
11113	The accepted range is 2% to 20000%.
11114	</desc>
11115	</attribute>
11116
11117	<!-- @todo method for setting log flags, groups and destination! -->
11118
11119	<attribute name="VM" type="unsigned long long" readonly="yes">
11120	<desc>
11121	Gets the VM handle. This is only for internal use while
11122	we carve the details of this interface.
11123	</desc>
11124	</attribute>
11125
11126	</interface>
11127
11128	<!--
11129	// IUSBController
11130	/////////////////////////////////////////////////////////////////////////
11131	-->
11132
11133	<interface
11134	name="IUSBController" extends="$unknown"
11135	uuid="238540fa-4b73-435a-a38e-4e1d9eab5c17"
11136	wsmap="managed"
11137	>
11138	<attribute name="enabled" type="boolean">
11139	<desc>
11140	Flag whether the USB controller is present in the
11141	guest system. If disabled, the virtual guest hardware will
11142	not contain any USB controller. Can only be changed when
11143	the VM is powered off.
11144	</desc>
11145	</attribute>
11146
11147	<attribute name="enabledEhci" type="boolean">
11148	<desc>
11149	Flag whether the USB EHCI controller is present in the
11150	guest system. If disabled, the virtual guest hardware will
11151	not contain a USB EHCI controller. Can only be changed when
11152	the VM is powered off.
11153	</desc>
11154	</attribute>
11155
11156	<attribute name="USBStandard" type="unsigned short" readonly="yes">
11157	<desc>
11158	USB standard version which the controller implements.
11159	This is a BCD which means that the major version is in the
11160	high byte and minor version is in the low byte.
11161	</desc>
11162	</attribute>
11163
11164	<attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
11165	<desc>
11166	List of USB device filters associated with the machine.
11167
11168	If the machine is currently running, these filters are activated
11169	every time a new (supported) USB device is attached to the host
11170	computer that was not ignored by global filters
11171	(<link to="IHost::USBDeviceFilters"/>).
11172
11173	These filters are also activated when the machine is powered up.
11174	They are run against a list of all currently available USB
11175	devices (in states
11176	<link to="USBDeviceState_Available"/>,
11177	<link to="USBDeviceState_Busy"/>,
11178	<link to="USBDeviceState_Held"/>) that were not previously
11179	ignored by global filters.
11180
11181	If at least one filter matches the USB device in question, this
11182	device is automatically captured (attached to) the virtual USB
11183	controller of this machine.
11184
11185	<see>IUSBDeviceFilter, ::IUSBController</see>
11186	</desc>
11187	</attribute>
11188
11189	<method name="createDeviceFilter">
11190	<desc>
11191	Creates a new USB device filter. All attributes except
11192	the filter name are set to empty (any match),
11193	<i>active</i> is @c false (the filter is not active).
11194
11195	The created filter can then be added to the list of filters using
11196	<link to="#insertDeviceFilter"/>.
11197
11198	<result name="VBOX_E_INVALID_VM_STATE">
11199	The virtual machine is not mutable.
11200	</result>
11201
11202	<see>#deviceFilters</see>
11203	</desc>
11204	<param name="name" type="wstring" dir="in">
11205	<desc>
11206	Filter name. See <link to="IUSBDeviceFilter::name"/>
11207	for more info.
11208	</desc>
11209	</param>
11210	<param name="filter" type="IUSBDeviceFilter" dir="return">
11211	<desc>Created filter object.</desc>
11212	</param>
11213	</method>
11214
11215	<method name="insertDeviceFilter">
11216	<desc>
11217	Inserts the given USB device to the specified position
11218	in the list of filters.
11219
11220	Positions are numbered starting from <tt>0</tt>. If the specified
11221	position is equal to or greater than the number of elements in
11222	the list, the filter is added to the end of the collection.
11223
11224	<note>
11225	Duplicates are not allowed, so an attempt to insert a
11226	filter that is already in the collection, will return an
11227	error.
11228	</note>
11229
11230	<result name="VBOX_E_INVALID_VM_STATE">
11231	Virtual machine is not mutable.
11232	</result>
11233	<result name="E_INVALIDARG">
11234	USB device filter not created within this VirtualBox instance.
11235	</result>
11236	<result name="VBOX_E_INVALID_OBJECT_STATE">
11237	USB device filter already in list.
11238	</result>
11239
11240	<see>#deviceFilters</see>
11241	</desc>
11242	<param name="position" type="unsigned long" dir="in">
11243	<desc>Position to insert the filter to.</desc>
11244	</param>
11245	<param name="filter" type="IUSBDeviceFilter" dir="in">
11246	<desc>USB device filter to insert.</desc>
11247	</param>
11248	</method>
11249
11250	<method name="removeDeviceFilter">
11251	<desc>
11252	Removes a USB device filter from the specified position in the
11253	list of filters.
11254
11255	Positions are numbered starting from <tt>0</tt>. Specifying a
11256	position equal to or greater than the number of elements in
11257	the list will produce an error.
11258
11259	<see>#deviceFilters</see>
11260
11261	<result name="VBOX_E_INVALID_VM_STATE">
11262	Virtual machine is not mutable.
11263	</result>
11264	<result name="E_INVALIDARG">
11265	USB device filter list empty or invalid @a position.
11266	</result>
11267
11268	</desc>
11269	<param name="position" type="unsigned long" dir="in">
11270	<desc>Position to remove the filter from.</desc>
11271	</param>
11272	<param name="filter" type="IUSBDeviceFilter" dir="return">
11273	<desc>Removed USB device filter.</desc>
11274	</param>
11275	</method>
11276
11277	</interface>
11278
11279
11280	<!--
11281	// IUSBDevice
11282	/////////////////////////////////////////////////////////////////////////
11283	-->
11284
11285	<interface
11286	name="IUSBDevice" extends="$unknown"
11287	uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
11288	wsmap="managed"
11289	>
11290	<desc>
11291	The IUSBDevice interface represents a virtual USB device attached to the
11292	virtual machine.
11293
11294	A collection of objects implementing this interface is stored in the
11295	<link to="IConsole::USBDevices"/> attribute which lists all USB devices
11296	attached to a running virtual machine's USB controller.
11297	</desc>
11298
11299	<attribute name="id" type="uuid" mod="string" readonly="yes">
11300	<desc>
11301	Unique USB device ID. This ID is built from #vendorId,
11302	#productId, #revision and #serialNumber.
11303	</desc>
11304	</attribute>
11305
11306	<attribute name="vendorId" type="unsigned short" readonly="yes">
11307	<desc>Vendor ID.</desc>
11308	</attribute>
11309
11310	<attribute name="productId" type="unsigned short" readonly="yes">
11311	<desc>Product ID.</desc>
11312	</attribute>
11313
11314	<attribute name="revision" type="unsigned short" readonly="yes">
11315	<desc>
11316	Product revision number. This is a packed BCD represented as
11317	unsigned short. The high byte is the integer part and the low
11318	byte is the decimal.
11319	</desc>
11320	</attribute>
11321
11322	<attribute name="manufacturer" type="wstring" readonly="yes">
11323	<desc>Manufacturer string.</desc>
11324	</attribute>
11325
11326	<attribute name="product" type="wstring" readonly="yes">
11327	<desc>Product string.</desc>
11328	</attribute>
11329
11330	<attribute name="serialNumber" type="wstring" readonly="yes">
11331	<desc>Serial number string.</desc>
11332	</attribute>
11333
11334	<attribute name="address" type="wstring" readonly="yes">
11335	<desc>Host specific address of the device.</desc>
11336	</attribute>
11337
11338	<attribute name="port" type="unsigned short" readonly="yes">
11339	<desc>
11340	Host USB port number the device is physically
11341	connected to.
11342	</desc>
11343	</attribute>
11344
11345	<attribute name="version" type="unsigned short" readonly="yes">
11346	<desc>
11347	The major USB version of the device - 1 or 2.
11348	</desc>
11349	</attribute>
11350
11351	<attribute name="portVersion" type="unsigned short" readonly="yes">
11352	<desc>
11353	The major USB version of the host USB port the device is
11354	physically connected to - 1 or 2. For devices not connected to
11355	anything this will have the same value as the version attribute.
11356	</desc>
11357	</attribute>
11358
11359	<attribute name="remote" type="boolean" readonly="yes">
11360	<desc>
11361	Whether the device is physically connected to a remote VRDP
11362	client or to a local host machine.
11363	</desc>
11364	</attribute>
11365
11366	</interface>
11367
11368
11369	<!--
11370	// IUSBDeviceFilter
11371	/////////////////////////////////////////////////////////////////////////
11372	-->
11373
11374	<interface
11375	name="IUSBDeviceFilter" extends="$unknown"
11376	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
11377	wsmap="managed"
11378	>
11379	<desc>
11380	The IUSBDeviceFilter interface represents an USB device filter used
11381	to perform actions on a group of USB devices.
11382
11383	This type of filters is used by running virtual machines to
11384	automatically capture selected USB devices once they are physically
11385	attached to the host computer.
11386
11387	A USB device is matched to the given device filter if and only if all
11388	attributes of the device match the corresponding attributes of the
11389	filter (that is, attributes are joined together using the logical AND
11390	operation). On the other hand, all together, filters in the list of
11391	filters carry the semantics of the logical OR operation. So if it is
11392	desirable to create a match like "this vendor id OR this product id",
11393	one needs to create two filters and specify "any match" (see below)
11394	for unused attributes.
11395
11396	All filter attributes used for matching are strings. Each string
11397	is an expression representing a set of values of the corresponding
11398	device attribute, that will match the given filter. Currently, the
11399	following filtering expressions are supported:
11400
11401	<ul>
11402	<li><i>Interval filters</i>. Used to specify valid intervals for
11403	integer device attributes (Vendor ID, Product ID and Revision).
11404	The format of the string is:
11405
11406	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
11407
11408	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
11409	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
11410	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
11411	is omitted before a dash (<tt>-</tt>), the minimum possible integer
11412	is assumed; if <tt>n</tt> is omitted after a dash, the maximum
11413	possible integer is assumed.
11414	</li>
11415	<li><i>Boolean filters</i>. Used to specify acceptable values for
11416	boolean device attributes. The format of the string is:
11417
11418	<tt>true\|false\|yes\|no\|0\|1</tt>
11419
11420	</li>
11421	<li><i>Exact match</i>. Used to specify a single value for the given
11422	device attribute. Any string that doesn't start with <tt>int:</tt>
11423	represents the exact match. String device attributes are compared to
11424	this string including case of symbols. Integer attributes are first
11425	converted to a string (see individual filter attributes) and then
11426	compared ignoring case.
11427
11428	</li>
11429	<li><i>Any match</i>. Any value of the corresponding device attribute
11430	will match the given filter. An empty or @c null string is
11431	used to construct this type of filtering expressions.
11432
11433	</li>
11434	</ul>
11435
11436	<note>
11437	On the Windows host platform, interval filters are not currently
11438	available. Also all string filter attributes
11439	(<link to="#manufacturer"/>, <link to="#product"/>,
11440	<link to="#serialNumber"/>) are ignored, so they behave as
11441	<i>any match</i> no matter what string expression is specified.
11442	</note>
11443
11444	<see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
11445	</desc>
11446
11447	<attribute name="name" type="wstring">
11448	<desc>
11449	Visible name for this filter.
11450	This name is used to visually distinguish one filter from another,
11451	so it can neither be @c null nor an empty string.
11452	</desc>
11453	</attribute>
11454
11455	<attribute name="active" type="boolean">
11456	<desc>Whether this filter active or has been temporarily disabled.</desc>
11457	</attribute>
11458
11459	<attribute name="vendorId" type="wstring">
11460	<desc>
11461	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
11462	The string representation for the <i>exact matching</i>
11463	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
11464	(including leading zeroes).
11465	</desc>
11466	</attribute>
11467
11468	<attribute name="productId" type="wstring">
11469	<desc>
11470	<link to="IUSBDevice::productId">Product ID</link> filter.
11471	The string representation for the <i>exact matching</i>
11472	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
11473	(including leading zeroes).
11474	</desc>
11475	</attribute>
11476
11477	<attribute name="revision" type="wstring">
11478	<desc>
11479	<link to="IUSBDevice::productId">Product revision number</link>
11480	filter. The string representation for the <i>exact matching</i>
11481	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
11482	of the integer part of the revision, and <tt>F</tt> is the
11483	decimal digit of its fractional part (including leading and
11484	trailing zeros).
11485	Note that for interval filters, it's best to use the hexadecimal
11486	form, because the revision is stored as a 16 bit packed BCD value;
11487	so the expression <tt>int:0x0100-0x0199</tt> will match any
11488	revision from <tt>1.0</tt> to <tt>1.99</tt>.
11489	</desc>
11490	</attribute>
11491
11492	<attribute name="manufacturer" type="wstring">
11493	<desc>
11494	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
11495	</desc>
11496	</attribute>
11497
11498	<attribute name="product" type="wstring">
11499	<desc>
11500	<link to="IUSBDevice::product">Product</link> filter.
11501	</desc>
11502	</attribute>
11503
11504	<attribute name="serialNumber" type="wstring">
11505	<desc>
11506	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
11507	</desc>
11508	</attribute>
11509
11510	<attribute name="port" type="wstring">
11511	<desc>
11512	<link to="IUSBDevice::port">Host USB port</link> filter.
11513	</desc>
11514	</attribute>
11515
11516	<attribute name="remote" type="wstring">
11517	<desc>
11518	<link to="IUSBDevice::remote">Remote state</link> filter.
11519	<note>
11520	This filter makes sense only for machine USB filters,
11521	i.e. it is ignored by IHostUSBDeviceFilter objects.
11522	</note>
11523	</desc>
11524	</attribute>
11525
11526	<attribute name="maskedInterfaces" type="unsigned long">
11527	<desc>
11528	This is an advanced option for hiding one or more USB interfaces
11529	from the guest. The value is a bit mask where the bits that are set
11530	means the corresponding USB interface should be hidden, masked off
11531	if you like.
11532	This feature only works on Linux hosts.
11533	</desc>
11534	</attribute>
11535
11536	</interface>
11537
11538
11539	<!--
11540	// IHostUSBDevice
11541	/////////////////////////////////////////////////////////////////////////
11542	-->
11543
11544	<enum
11545	name="USBDeviceState"
11546	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
11547	>
11548	<desc>
11549	USB device state. This enumeration represents all possible states
11550	of the USB device physically attached to the host computer regarding
11551	its state on the host computer and availability to guest computers
11552	(all currently running virtual machines).
11553
11554	Once a supported USB device is attached to the host, global USB
11555	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
11556	either ignore the device, or put it to USBDeviceState_Held state, or do
11557	nothing. Unless the device is ignored by global filters, filters of all
11558	currently running guests (<link to="IUSBController::deviceFilters"/>) are
11559	activated that can put it to USBDeviceState_Captured state.
11560
11561	If the device was ignored by global filters, or didn't match
11562	any filters at all (including guest ones), it is handled by the host
11563	in a normal way. In this case, the device state is determined by
11564	the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
11565	or USBDeviceState_Available, depending on the current device usage.
11566
11567	Besides auto-capturing based on filters, the device can be manually
11568	captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
11569	state is USBDeviceState_Busy, USBDeviceState_Available or
11570	USBDeviceState_Held.
11571
11572	<note>
11573	Due to differences in USB stack implementations in Linux and Win32,
11574	states USBDeviceState_Busy and USBDeviceState_vailable are applicable
11575	only to the Linux version of the product. This also means that (<link
11576	to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
11577	device state is USBDeviceState_Held.
11578	</note>
11579
11580	<see>IHostUSBDevice, IHostUSBDeviceFilter</see>
11581	</desc>
11582
11583	<const name="NotSupported" value="0">
11584	<desc>
11585	Not supported by the VirtualBox server, not available to guests.
11586	</desc>
11587	</const>
11588	<const name="Unavailable" value="1">
11589	<desc>
11590	Being used by the host computer exclusively,
11591	not available to guests.
11592	</desc>
11593	</const>
11594	<const name="Busy" value="2">
11595	<desc>
11596	Being used by the host computer, potentially available to guests.
11597	</desc>
11598	</const>
11599	<const name="Available" value="3">
11600	<desc>
11601	Not used by the host computer, available to guests (the host computer
11602	can also start using the device at any time).
11603	</desc>
11604	</const>
11605	<const name="Held" value="4">
11606	<desc>
11607	Held by the VirtualBox server (ignored by the host computer),
11608	available to guests.
11609	</desc>
11610	</const>
11611	<const name="Captured" value="5">
11612	<desc>
11613	Captured by one of the guest computers, not available
11614	to anybody else.
11615	</desc>
11616	</const>
11617	</enum>
11618
11619	<interface
11620	name="IHostUSBDevice" extends="IUSBDevice"
11621	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
11622	wsmap="managed"
11623	>
11624	<desc>
11625	The IHostUSBDevice interface represents a physical USB device attached
11626	to the host computer.
11627
11628	Besides properties inherited from IUSBDevice, this interface adds the
11629	<link to="#state"/> property that holds the current state of the USB
11630	device.
11631
11632	<see>IHost::USBDevices, IHost::USBDeviceFilters</see>
11633	</desc>
11634
11635	<attribute name="state" type="USBDeviceState" readonly="yes">
11636	<desc>
11637	Current state of the device.
11638	</desc>
11639	</attribute>
11640
11641	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
11642
11643	</interface>
11644
11645
11646	<!--
11647	// IHostUSBDeviceFilter
11648	/////////////////////////////////////////////////////////////////////////
11649	-->
11650
11651	<enum
11652	name="USBDeviceFilterAction"
11653	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
11654	>
11655	<desc>
11656	Actions for host USB device filters.
11657	<see>IHostUSBDeviceFilter, USBDeviceState</see>
11658	</desc>
11659
11660	<const name="Null" value="0">
11661	<desc>Null value (never used by the API).</desc>
11662	</const>
11663	<const name="Ignore" value="1">
11664	<desc>Ignore the matched USB device.</desc>
11665	</const>
11666	<const name="Hold" value="2">
11667	<desc>Hold the matched USB device.</desc>
11668	</const>
11669	</enum>
11670
11671	<interface
11672	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
11673	uuid="4cc70246-d74a-400f-8222-3900489c0374"
11674	wsmap="managed"
11675	>
11676	<desc>
11677	The IHostUSBDeviceFilter interface represents a global filter for a
11678	physical USB device used by the host computer. Used indirectly in
11679	<link to="IHost::USBDeviceFilters"/>.
11680
11681	Using filters of this type, the host computer determines the initial
11682	state of the USB device after it is physically attached to the
11683	host's USB controller.
11684
11685	<note>
11686	The <link to="#remote"/> attribute is ignored by this type of
11687	filters, because it makes sense only for
11688	<link to="IUSBController::deviceFilters">machine USB filters</link>.
11689	</note>
11690
11691	<see>IHost::USBDeviceFilters</see>
11692	</desc>
11693
11694	<attribute name="action" type="USBDeviceFilterAction">
11695	<desc>
11696	Action performed by the host when an attached USB device
11697	matches this filter.
11698	</desc>
11699	</attribute>
11700
11701	</interface>
11702
11703	<!--
11704	// IAudioAdapter
11705	/////////////////////////////////////////////////////////////////////////
11706	-->
11707
11708	<enum
11709	name="AudioDriverType"
11710	uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
11711	>
11712	<desc>
11713	Host audio driver type.
11714	</desc>
11715
11716	<const name="Null" value="0">
11717	<desc>Null value, also means "dummy audio driver".</desc>
11718	</const>
11719	<const name="WinMM" value="1">
11720	<desc>Windows multimedia (Windows hosts only).</desc>
11721	</const>
11722	<const name="OSS" value="2">
11723	<desc>Open Sound System (Linux hosts only).</desc>
11724	</const>
11725	<const name="ALSA" value="3">
11726	<desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
11727	</const>
11728	<const name="DirectSound" value="4">
11729	<desc>DirectSound (Windows hosts only).</desc>
11730	</const>
11731	<const name="CoreAudio" value="5">
11732	<desc>CoreAudio (Mac hosts only).</desc>
11733	</const>
11734	<const name="MMPM" value="6">
11735	<desc>Reserved for historical reasons.</desc>
11736	</const>
11737	<const name="Pulse" value="7">
11738	<desc>PulseAudio (Linux hosts only).</desc>
11739	</const>
11740	<const name="SolAudio" value="8">
11741	<desc>Solaris audio (Solaris hosts only).</desc>
11742	</const>
11743	</enum>
11744
11745	<enum
11746	name="AudioControllerType"
11747	uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
11748	>
11749	<desc>
11750	Virtual audio controller type.
11751	</desc>
11752
11753	<const name="AC97" value="0"/>
11754	<const name="SB16" value="1"/>
11755	</enum>
11756
11757	<interface
11758	name="IAudioAdapter" extends="$unknown"
11759	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
11760	wsmap="managed"
11761	>
11762	<desc>
11763	The IAudioAdapter interface represents the virtual audio adapter of
11764	the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
11765	</desc>
11766	<attribute name="enabled" type="boolean">
11767	<desc>
11768	Flag whether the audio adapter is present in the
11769	guest system. If disabled, the virtual guest hardware will
11770	not contain any audio adapter. Can only be changed when
11771	the VM is not running.
11772	</desc>
11773	</attribute>
11774	<attribute name="audioController" type="AudioControllerType">
11775	<desc>
11776	The audio hardware we emulate.
11777	</desc>
11778	</attribute>
11779	<attribute name="audioDriver" type="AudioDriverType">
11780	<desc>
11781	Audio driver the adapter is connected to. This setting
11782	can only be changed when the VM is not running.
11783	</desc>
11784	</attribute>
11785	</interface>
11786
11787	<!--
11788	// IVRDPServer
11789	/////////////////////////////////////////////////////////////////////////
11790	-->
11791
11792	<enum
11793	name="VRDPAuthType"
11794	uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
11795	>
11796	<desc>
11797	VRDP authentication type.
11798	</desc>
11799
11800	<const name="Null" value="0">
11801	<desc>Null value, also means "no authentication".</desc>
11802	</const>
11803	<const name="External" value="1"/>
11804	<const name="Guest" value="2"/>
11805	</enum>
11806
11807	<interface
11808	name="IVRDPServer" extends="$unknown"
11809	uuid="72e671bc-1712-4052-ad6b-e45e76d9d3e4"
11810	wsmap="managed"
11811	>
11812	<attribute name="enabled" type="boolean">
11813	<desc>VRDP server status.</desc>
11814	</attribute>
11815
11816	<attribute name="ports" type="wstring">
11817	<desc>
11818	VRDP server port numbers.
11819	<note>
11820	This is a string of comma separated TCP port numbers or port number ranges.
11821	The server will try to bind to one of ports from the list. Example
11822	<tt>3000,3010-3012,3015</tt>
11823	</note>
11824	</desc>
11825	</attribute>
11826
11827	<attribute name="netAddress" type="wstring">
11828	<desc>VRDP server address.</desc>
11829	</attribute>
11830
11831	<attribute name="authType" type="VRDPAuthType">
11832	<desc>VRDP authentication method.</desc>
11833	</attribute>
11834
11835	<attribute name="authTimeout" type="unsigned long">
11836	<desc>Timeout for guest authentication. Milliseconds.</desc>
11837	</attribute>
11838
11839	<attribute name="allowMultiConnection" type="boolean">
11840	<desc>
11841	Flag whether multiple simultaneous connections to the VM are permitted.
11842	Note that this will be replaced by a more powerful mechanism in the future.
11843	</desc>
11844	</attribute>
11845
11846	<attribute name="reuseSingleConnection" type="boolean">
11847	<desc>
11848	Flag whether the existing connection must be dropped and a new connection
11849	must be established by the VRDP server, when a new client connects in single
11850	connection mode.
11851	</desc>
11852	</attribute>
11853
11854	</interface>
11855
11856
11857	<!--
11858	// ISharedFolder
11859	/////////////////////////////////////////////////////////////////////////
11860	-->
11861
11862	<interface
11863	name="ISharedFolder" extends="$unknown"
11864	uuid="64637bb2-9e17-471c-b8f3-f8968dd9884e"
11865	wsmap="struct"
11866	>
11867	<desc>
11868	The ISharedFolder interface represents a folder in the host computer's
11869	file system accessible from the guest OS running inside a virtual
11870	machine using an associated logical name.
11871
11872	There are three types of shared folders:
11873	<ul>
11874	<li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
11875	folders available to all virtual machines.</li>
11876	<li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
11877	VM-specific shared folders available to the given virtual machine at
11878	startup.</li>
11879	<li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
11880	VM-specific shared folders created in the session context (for
11881	example, when the virtual machine is running) and automatically
11882	discarded when the session is closed (the VM is powered off).</li>
11883	</ul>
11884
11885	Logical names of shared folders must be unique within the given scope
11886	(global, permanent or transient). However, they do not need to be unique
11887	across scopes. In this case, the definition of the shared folder in a
11888	more specific scope takes precedence over definitions in all other
11889	scopes. The order of precedence is (more specific to more general):
11890	<ol>
11891	<li>Transient definitions</li>
11892	<li>Permanent definitions</li>
11893	<li>Global definitions</li>
11894	</ol>
11895
11896	For example, if MyMachine has a shared folder named
11897	<tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
11898	transient shared folder named <tt>C_DRIVE</tt> (that points
11899	to <tt>C:\\\\WINDOWS</tt>) will change the definition
11900	of <tt>C_DRIVE</tt> in the guest OS so
11901	that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
11902	to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
11903	PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
11904	the previous (permanent) definition of <tt>C_DRIVE</tt> that points
11905	to <tt>C:\\</tt> if it still exists.
11906
11907	Note that permanent and transient shared folders of different machines
11908	are in different name spaces, so they don't overlap and don't need to
11909	have unique logical names.
11910
11911	<note>
11912	Global shared folders are not implemented in the current version of the
11913	product.
11914	</note>
11915	</desc>
11916
11917	<attribute name="name" type="wstring" readonly="yes">
11918	<desc>Logical name of the shared folder.</desc>
11919	</attribute>
11920
11921	<attribute name="hostPath" type="wstring" readonly="yes">
11922	<desc>Full path to the shared folder in the host file system.</desc>
11923	</attribute>
11924
11925	<attribute name="accessible" type="boolean" readonly="yes">
11926	<desc>
11927	Whether the folder defined by the host path is currently
11928	accessible or not.
11929	For example, the folder can be unaccessible if it is placed
11930	on the network share that is not available by the time
11931	this property is read.
11932	</desc>
11933	</attribute>
11934
11935	<attribute name="writable" type="boolean" readonly="yes">
11936	<desc>
11937	Whether the folder defined by the host path is writable or
11938	not.
11939	</desc>
11940	</attribute>
11941
11942	<attribute name="lastAccessError" type="wstring" readonly="yes">
11943	<desc>
11944	Text message that represents the result of the last accessibility
11945	check.
11946
11947	Accessibility checks are performed each time the <link to="#accessible"/>
11948	attribute is read. An empty string is returned if the last
11949	accessibility check was successful. A non-empty string indicates a
11950	failure and should normally describe a reason of the failure (for
11951	example, a file read error).
11952	</desc>
11953	</attribute>
11954
11955	</interface>
11956
11957	<!--
11958	// ISession
11959	/////////////////////////////////////////////////////////////////////////
11960	-->
11961
11962	<interface
11963	name="IInternalSessionControl" extends="$unknown"
11964	uuid="989e2c33-8dfa-437a-9a15-5ad441d50dbf"
11965	internal="yes"
11966	wsmap="suppress"
11967	>
11968	<method name="getPID">
11969	<desc>PID of the process that has created this Session object.
11970	</desc>
11971	<param name="pid" type="unsigned long" dir="return"/>
11972	</method>
11973
11974	<method name="getRemoteConsole">
11975	<desc>
11976	Returns the console object suitable for remote control.
11977
11978	<result name="VBOX_E_INVALID_VM_STATE">
11979	Session state prevents operation.
11980	</result>
11981	<result name="VBOX_E_INVALID_OBJECT_STATE">
11982	Session type prevents operation.
11983	</result>
11984
11985	</desc>
11986	<param name="console" type="IConsole" dir="return"/>
11987	</method>
11988
11989	<method name="assignMachine">
11990	<desc>
11991	Assigns the machine object associated with this direct-type
11992	session or informs the session that it will be a remote one
11993	(if @a machine == @c null).
11994
11995	<result name="VBOX_E_INVALID_VM_STATE">
11996	Session state prevents operation.
11997	</result>
11998	<result name="VBOX_E_INVALID_OBJECT_STATE">
11999	Session type prevents operation.
12000	</result>
12001
12002	</desc>
12003	<param name="machine" type="IMachine" dir="in"/>
12004	</method>
12005
12006	<method name="assignRemoteMachine">
12007	<desc>
12008	Assigns the machine and the (remote) console object associated with
12009	this remote-type session.
12010
12011	<result name="VBOX_E_INVALID_VM_STATE">
12012	Session state prevents operation.
12013	</result>
12014
12015	</desc>
12016	<param name="machine" type="IMachine" dir="in"/>
12017	<param name="console" type="IConsole" dir="in"/>
12018	</method>
12019
12020	<method name="updateMachineState">
12021	<desc>
12022	Updates the machine state in the VM process.
12023	Must be called only in certain cases
12024	(see the method implementation).
12025
12026	<result name="VBOX_E_INVALID_VM_STATE">
12027	Session state prevents operation.
12028	</result>
12029	<result name="VBOX_E_INVALID_OBJECT_STATE">
12030	Session type prevents operation.
12031	</result>
12032
12033	</desc>
12034	<param name="aMachineState" type="MachineState" dir="in"/>
12035	</method>
12036
12037	<method name="uninitialize">
12038	<desc>
12039	Uninitializes (closes) this session. Used by VirtualBox to close
12040	the corresponding remote session when the direct session dies
12041	or gets closed.
12042
12043	<result name="VBOX_E_INVALID_VM_STATE">
12044	Session state prevents operation.
12045	</result>
12046
12047	</desc>
12048	</method>
12049
12050	<method name="onNetworkAdapterChange">
12051	<desc>
12052	Triggered when settings of a network adapter of the
12053	associated virtual machine have changed.
12054
12055	<result name="VBOX_E_INVALID_VM_STATE">
12056	Session state prevents operation.
12057	</result>
12058	<result name="VBOX_E_INVALID_OBJECT_STATE">
12059	Session type prevents operation.
12060	</result>
12061
12062	</desc>
12063	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
12064	<param name="changeAdapter" type="boolean" dir="in"/>
12065	</method>
12066
12067	<method name="onSerialPortChange">
12068	<desc>
12069	Triggered when settings of a serial port of the
12070	associated virtual machine have changed.
12071
12072	<result name="VBOX_E_INVALID_VM_STATE">
12073	Session state prevents operation.
12074	</result>
12075	<result name="VBOX_E_INVALID_OBJECT_STATE">
12076	Session type prevents operation.
12077	</result>
12078
12079	</desc>
12080	<param name="serialPort" type="ISerialPort" dir="in"/>
12081	</method>
12082
12083	<method name="onParallelPortChange">
12084	<desc>
12085	Triggered when settings of a parallel port of the
12086	associated virtual machine have changed.
12087
12088	<result name="VBOX_E_INVALID_VM_STATE">
12089	Session state prevents operation.
12090	</result>
12091	<result name="VBOX_E_INVALID_OBJECT_STATE">
12092	Session type prevents operation.
12093	</result>
12094
12095	</desc>
12096	<param name="parallelPort" type="IParallelPort" dir="in"/>
12097	</method>
12098
12099	<method name="onStorageControllerChange">
12100	<desc>
12101	Triggered when settings of a storage controller of the
12102	associated virtual machine have changed.
12103
12104	<result name="VBOX_E_INVALID_VM_STATE">
12105	Session state prevents operation.
12106	</result>
12107	<result name="VBOX_E_INVALID_OBJECT_STATE">
12108	Session type prevents operation.
12109	</result>
12110
12111	</desc>
12112	</method>
12113
12114	<method name="onMediumChange">
12115	<desc>
12116	Triggered when attached media of the
12117	associated virtual machine have changed.
12118
12119	<result name="VBOX_E_INVALID_VM_STATE">
12120	Session state prevents operation.
12121	</result>
12122	<result name="VBOX_E_INVALID_OBJECT_STATE">
12123	Session type prevents operation.
12124	</result>
12125
12126	</desc>
12127
12128	<param name="mediumAttachment" type="IMediumAttachment" dir="in"/>
12129	</method>
12130
12131	<method name="onVRDPServerChange">
12132	<desc>
12133	Triggered when settings of the VRDP server object of the
12134	associated virtual machine have changed.
12135
12136	<result name="VBOX_E_INVALID_VM_STATE">
12137	Session state prevents operation.
12138	</result>
12139	<result name="VBOX_E_INVALID_OBJECT_STATE">
12140	Session type prevents operation.
12141	</result>
12142
12143	</desc>
12144	</method>
12145
12146	<method name="onUSBControllerChange">
12147	<desc>
12148	Triggered when settings of the USB controller object of the
12149	associated virtual machine have changed.
12150
12151	<result name="VBOX_E_INVALID_VM_STATE">
12152	Session state prevents operation.
12153	</result>
12154	<result name="VBOX_E_INVALID_OBJECT_STATE">
12155	Session type prevents operation.
12156	</result>
12157
12158	</desc>
12159	</method>
12160
12161	<method name="onSharedFolderChange">
12162	<desc>
12163	Triggered when a permanent (global or machine) shared folder has been
12164	created or removed.
12165	<note>
12166	We don't pass shared folder parameters in this notification because
12167	the order in which parallel notifications are delivered is not defined,
12168	therefore it could happen that these parameters were outdated by the
12169	time of processing this notification.
12170	</note>
12171
12172	<result name="VBOX_E_INVALID_VM_STATE">
12173	Session state prevents operation.
12174	</result>
12175	<result name="VBOX_E_INVALID_OBJECT_STATE">
12176	Session type prevents operation.
12177	</result>
12178
12179	</desc>
12180	<param name="global" type="boolean" dir="in"/>
12181	</method>
12182
12183	<method name="onUSBDeviceAttach">
12184	<desc>
12185	Triggered when a request to capture a USB device (as a result
12186	of matched USB filters or direct call to
12187	<link to="IConsole::attachUSBDevice"/>) has completed.
12188	A @c null @a error object means success, otherwise it
12189	describes a failure.
12190
12191	<result name="VBOX_E_INVALID_VM_STATE">
12192	Session state prevents operation.
12193	</result>
12194	<result name="VBOX_E_INVALID_OBJECT_STATE">
12195	Session type prevents operation.
12196	</result>
12197
12198	</desc>
12199	<param name="device" type="IUSBDevice" dir="in"/>
12200	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
12201	<param name="maskedInterfaces" type="unsigned long" dir="in"/>
12202	</method>
12203
12204	<method name="onUSBDeviceDetach">
12205	<desc>
12206	Triggered when a request to release the USB device (as a result
12207	of machine termination or direct call to
12208	<link to="IConsole::detachUSBDevice"/>) has completed.
12209	A @c null @a error object means success, otherwise it
12210	describes a failure.
12211
12212	<result name="VBOX_E_INVALID_VM_STATE">
12213	Session state prevents operation.
12214	</result>
12215	<result name="VBOX_E_INVALID_OBJECT_STATE">
12216	Session type prevents operation.
12217	</result>
12218
12219	</desc>
12220	<param name="id" type="uuid" mod="string" dir="in"/>
12221	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
12222	</method>
12223
12224	<method name="onShowWindow">
12225	<desc>
12226	Called by <link to="IMachine::canShowConsoleWindow"/> and by
12227	<link to="IMachine::showConsoleWindow"/> in order to notify
12228	console callbacks
12229	<link to="IConsoleCallback::onCanShowWindow"/>
12230	and <link to="IConsoleCallback::onShowWindow"/>.
12231
12232	<result name="VBOX_E_INVALID_OBJECT_STATE">
12233	Session type prevents operation.
12234	</result>
12235
12236	</desc>
12237	<param name="check" type="boolean" dir="in"/>
12238	<param name="canShow" type="boolean" dir="out"/>
12239	<param name="winId" type="unsigned long long" dir="out"/>
12240	</method>
12241
12242	<method name="accessGuestProperty">
12243	<desc>
12244	Called by <link to="IMachine::getGuestProperty"/> and by
12245	<link to="IMachine::setGuestProperty"/> in order to read and
12246	modify guest properties.
12247
12248	<result name="VBOX_E_INVALID_VM_STATE">
12249	Machine session is not open.
12250	</result>
12251	<result name="VBOX_E_INVALID_OBJECT_STATE">
12252	Session type is not direct.
12253	</result>
12254
12255	</desc>
12256	<param name="name" type="wstring" dir="in"/>
12257	<param name="value" type="wstring" dir="in"/>
12258	<param name="flags" type="wstring" dir="in"/>
12259	<param name="isSetter" type="boolean" dir="in"/>
12260	<param name="retValue" type="wstring" dir="out"/>
12261	<param name="retTimestamp" type="unsigned long long" dir="out"/>
12262	<param name="retFlags" type="wstring" dir="out"/>
12263	</method>
12264
12265	<method name="enumerateGuestProperties">
12266	<desc>
12267	Return a list of the guest properties matching a set of patterns along
12268	with their values, time stamps and flags.
12269
12270	<result name="VBOX_E_INVALID_VM_STATE">
12271	Machine session is not open.
12272	</result>
12273	<result name="VBOX_E_INVALID_OBJECT_STATE">
12274	Session type is not direct.
12275	</result>
12276
12277	</desc>
12278	<param name="patterns" type="wstring" dir="in">
12279	<desc>
12280	The patterns to match the properties against as a comma-separated
12281	string. If this is empty, all properties currently set will be
12282	returned.
12283	</desc>
12284	</param>
12285	<param name="key" type="wstring" dir="out" safearray="yes">
12286	<desc>
12287	The key names of the properties returned.
12288	</desc>
12289	</param>
12290	<param name="value" type="wstring" dir="out" safearray="yes">
12291	<desc>
12292	The values of the properties returned. The array entries match the
12293	corresponding entries in the @a key array.
12294	</desc>
12295	</param>
12296	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
12297	<desc>
12298	The time stamps of the properties returned. The array entries match
12299	the corresponding entries in the @a key array.
12300	</desc>
12301	</param>
12302	<param name="flags" type="wstring" dir="out" safearray="yes">
12303	<desc>
12304	The flags of the properties returned. The array entries match the
12305	corresponding entries in the @a key array.
12306	</desc>
12307	</param>
12308	</method>
12309
12310	</interface>
12311
12312	<interface
12313	name="ISession" extends="$dispatched"
12314	uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
12315	wsmap="managed"
12316	>
12317	<desc>
12318	The ISession interface represents a serialization primitive for virtual
12319	machines.
12320
12321	With VirtualBox, every time one wishes to manipulate a virtual machine
12322	(e.g. change its settings or start execution), a session object is
12323	required. Such an object must be passed to one of the session methods
12324	that open the given session, which then initiates the machine manipulation.
12325
12326	A session serves several purposes: it identifies to the inter-process VirtualBox
12327	code which process is currently working with the virtual machine, and it ensures
12328	that there are no incompatible requests from several processes for the
12329	same virtual machine. Session objects can therefore be thought of as mutex
12330	semaphores that lock virtual machines to prevent conflicting accesses from
12331	several processes.
12332
12333	How sessions objects are used depends on whether you use the Main API
12334	via COM or via the webservice:
12335
12336	<ul>
12337	<li>When using the COM API directly, an object of the Session class from the
12338	VirtualBox type library needs to be created. In regular COM C++ client code,
12339	this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
12340	This object will then act as a local session object in further calls to open
12341	a session.
12342	</li>
12343
12344	<li>In the webservice, the session manager (IWebsessionManager) instead creates
12345	one session object automatically when <link to="IWebsessionManager::logon" />
12346	is called. A managed object reference to that session object can be retrieved by
12347	calling <link to="IWebsessionManager::getSessionObject" />. This session object
12348	reference can then be used to open sessions.
12349	</li>
12350	</ul>
12351
12352	Sessions are mainly used in two variations:
12353
12354	<ul>
12355	<li>
12356	To start a virtual machine in a separate process, one would call
12357	<link to="IVirtualBox::openRemoteSession"/>, which requires a session
12358	object as its first parameter. This session then identifies the caller
12359	and lets him control the started machine (for example, pause machine
12360	execution or power it down) as well as be notified about machine
12361	execution state changes.
12362	</li>
12363
12364	<li>To alter machine settings, or to start machine execution within the
12365	current process, one needs to open a direct session for the machine first by
12366	calling <link to="IVirtualBox::openSession"/>. While a direct session
12367	is open within one process, no any other process may open another direct
12368	session for the same machine. This prevents the machine from being changed
12369	by other processes while it is running or while the machine is being configured.
12370	</li>
12371	</ul>
12372
12373	One also can attach to an existing direct session already opened by
12374	another process (for example, in order to send a control request to the
12375	virtual machine such as the pause or the reset request). This is done by
12376	calling <link to="IVirtualBox::openExistingSession"/>.
12377
12378	<note>
12379	Unless you are trying to write a new VirtualBox front-end that
12380	performs direct machine execution (like the VirtualBox or VBoxSDL
12381	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
12382	session opened by <link to="IVirtualBox::openSession"/> and use this
12383	session only to change virtual machine settings. If you simply want to
12384	start virtual machine execution using one of the existing front-ends
12385	(for example the VirtualBox GUI or headless server), simply use
12386	<link to="IVirtualBox::openRemoteSession"/>; these front-ends
12387	will power up the machine automatically for you.
12388	</note>
12389	</desc>
12390
12391	<attribute name="state" type="SessionState" readonly="yes">
12392	<desc>Current state of this session.</desc>
12393	</attribute>
12394
12395	<attribute name="type" type="SessionType" readonly="yes">
12396	<desc>
12397	Type of this session. The value of this attribute is valid only
12398	if the session is currently open (i.e. its #state is
12399	SessionType_SessionOpen), otherwise an error will be returned.
12400	</desc>
12401	</attribute>
12402
12403	<attribute name="machine" type="IMachine" readonly="yes">
12404	<desc>Machine object associated with this session.</desc>
12405	</attribute>
12406
12407	<attribute name="console" type="IConsole" readonly="yes">
12408	<desc>Console object associated with this session.</desc>
12409	</attribute>
12410
12411	<method name="close">
12412	<desc>
12413	Closes a session that was previously opened.
12414
12415	It is recommended that every time an "open session" method (such as
12416	<link to="IVirtualBox::openRemoteSession" /> or
12417	<link to="IVirtualBox::openSession" />) has been called to
12418	manipulate a virtual machine, the caller invoke
12419	ISession::close() when it's done doing so. Since sessions are
12420	serialization primitives much like ordinary mutexes, they are
12421	best used the same way: for each "open" call, there should be
12422	a matching "close" call, even when errors occur.
12423
12424	Otherwise, if a direct session for a machine opened with
12425	<link to="IVirtualBox::openSession"/> is not explicitly closed
12426	when the application terminates, the state of the machine will
12427	be set to <link to="MachineState_Aborted" /> on the server.
12428
12429	Generally, it is recommended to close all open sessions explicitly
12430	before terminating the application (regardless of the reason for
12431	the termination).
12432
12433	<note>
12434	Do not expect the session state (<link to="ISession::state" />
12435	to return to "Closed" immediately after you invoke
12436	ISession::close(), particularly if you have started a remote
12437	session to execute the VM in a new process. The session state will
12438	automatically return to "Closed" once the VM is no longer executing,
12439	which can of course take a very long time.
12440	</note>
12441
12442	<result name="E_UNEXPECTED">
12443	Session is not open.
12444	</result>
12445
12446	</desc>
12447	</method>
12448
12449	</interface>
12450
12451	<!--
12452	// IStorageController
12453	/////////////////////////////////////////////////////////////////////////
12454	-->
12455
12456	<enum
12457	name="StorageBus"
12458	uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
12459	>
12460	<desc>
12461	The bus type of the storage controller (IDE, SATA, SCSI or Floppy);
12462	see <link to="IStorageController::bus" />.
12463	</desc>
12464	<const name="Null" value="0">
12465	<desc>@c null value. Never used by the API.</desc>
12466	</const>
12467	<const name="IDE" value="1"/>
12468	<const name="SATA" value="2"/>
12469	<const name="SCSI" value="3"/>
12470	<const name="Floppy" value="4"/>
12471	</enum>
12472
12473	<enum
12474	name="StorageControllerType"
12475	uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
12476	>
12477	<desc>
12478	The exact variant of storage controller hardware presented
12479	to the guest; see <link to="IStorageController::controllerType" />.
12480	</desc>
12481
12482	<const name="Null" value="0">
12483	<desc>@c null value. Never used by the API.</desc>
12484	</const>
12485	<const name="LsiLogic" value="1">
12486	<desc>A SCSI controller of the LsiLogic variant.</desc>
12487	</const>
12488	<const name="BusLogic" value="2">
12489	<desc>A SCSI controller of the BusLogic variant.</desc>
12490	</const>
12491	<const name="IntelAhci" value="3">
12492	<desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
12493	</const>
12494	<const name="PIIX3" value="4">
12495	<desc>An IDE controller of the PIIX3 variant.</desc>
12496	</const>
12497	<const name="PIIX4" value="5">
12498	<desc>An IDE controller of the PIIX4 variant.</desc>
12499	</const>
12500	<const name="ICH6" value="6">
12501	<desc>An IDE controller of the ICH6 variant.</desc>
12502	</const>
12503	<const name="I82078" value="7">
12504	<desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
12505	</const>
12506	</enum>
12507
12508	<interface
12509	name="IStorageController" extends="$unknown"
12510	uuid="6bf8335b-d14a-44a5-9b45-ddc49ce7d5b2"
12511	wsmap="managed"
12512	>
12513	<desc>
12514	Represents a storage controller that is attached to a virtual machine
12515	(<link to="IMachine" />). Just as disks (hard disks, DVDs, FDs) are
12516	attached to storage controllers in a real computer, virtual media
12517	(represented by <link to="IMedium" />) are attached to virtual
12518	storage controllers, represented by this interface.
12519
12520	As opposed to physical hardware, VirtualBox has a very generic concept
12521	of a storage controller, and for purposes of the Main API, all virtual
12522	storage is attached to virtual machines via instances of this interface.
12523	There are four types of such virtual storage controllers: IDE, SCSI, SATA
12524	and Floppy (see <link to="#bus" />). Depending on which of these four is
12525	used, certain sub-types may be available and can be selected in
12526	<link to="#controllerType" />.
12527
12528	Depending on these settings, the guest operating system might see
12529	significantly different virtual hardware.
12530	</desc>
12531
12532	<attribute name="name" type="wstring" readonly="yes">
12533	<desc>
12534	Name of the storage controller, as originally specified with
12535	<link to="IMachine::addStorageController" />. This then uniquely
12536	identifies this controller with other method calls such as
12537	<link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
12538	</desc>
12539	</attribute>
12540
12541	<attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
12542	<desc>
12543	Maximum number of devices which can be attached to one port.
12544	</desc>
12545	</attribute>
12546
12547	<attribute name="minPortCount" type="unsigned long" readonly="yes">
12548	<desc>
12549	Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
12550	</desc>
12551	</attribute>
12552
12553	<attribute name="maxPortCount" type="unsigned long" readonly="yes">
12554	<desc>
12555	Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
12556	</desc>
12557	</attribute>
12558
12559	<attribute name="instance" type="unsigned long">
12560	<desc>
12561	The instance number of the device in the running VM.
12562	</desc>
12563	</attribute>
12564
12565	<attribute name="portCount" type="unsigned long">
12566	<desc>
12567	The number of currently usable ports on the controller.
12568	The minimum and maximum number of ports for one controller are
12569	stored in <link to="IStorageController::minPortCount"/>
12570	and <link to="IStorageController::maxPortCount"/>.
12571	</desc>
12572	</attribute>
12573
12574	<attribute name="bus" type="StorageBus" readonly="yes">
12575	<desc>
12576	The bus type of the storage controller (IDE, SATA, SCSI or Floppy).
12577	</desc>
12578	</attribute>
12579
12580	<attribute name="controllerType" type="StorageControllerType">
12581	<desc>
12582	The exact variant of storage controller hardware presented
12583	to the guest.
12584	Depending on this value, VirtualBox will provide a different
12585	virtual storage controller hardware to the guest.
12586	For SATA and floppy controllers, only one variant is available,
12587	but for IDE and SCSI, there are several.
12588
12589	For SCSI controllers, the default type is LsiLogic.
12590	</desc>
12591	</attribute>
12592
12593	<method name="GetIDEEmulationPort">
12594	<desc>
12595	Gets the corresponding port number which is emulated as an IDE device.
12596	Works only with SATA controllers.
12597
12598	<result name="E_INVALIDARG">
12599	The @a devicePosition is not in the range 0 to 3.
12600	</result>
12601	<result name="E_NOTIMPL">
12602	The storage controller type is not SATAIntelAhci.
12603	</result>
12604
12605	</desc>
12606	<param name="devicePosition" type="long" dir="in"/>
12607	<param name="portNumber" type="long" dir="return"/>
12608	</method>
12609
12610	<method name="SetIDEEmulationPort">
12611	<desc>
12612	Sets the port number which is emulated as an IDE device.
12613	Works only with SATA controllers.
12614
12615	<result name="E_INVALIDARG">
12616	The @a devicePosition is not in the range 0 to 3 or the
12617	@a portNumber is not in the range 0 to 29.
12618	</result>
12619	<result name="E_NOTIMPL">
12620	The storage controller type is not SATAIntelAhci.
12621	</result>
12622
12623	</desc>
12624	<param name="devicePosition" type="long" dir="in"/>
12625	<param name="portNumber" type="long" dir="in"/>
12626	</method>
12627
12628	</interface>
12629
12630	<if target="wsdl">
12631
12632	<!--
12633	// IManagedObjectRef
12634	/////////////////////////////////////////////////////////////////////////
12635	-->
12636
12637	<interface
12638	name="IManagedObjectRef" extends="$unknown"
12639	uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
12640	internal="yes"
12641	wsmap="managed"
12642	wscpp="hardcoded"
12643	>
12644	<desc>
12645	Managed object reference.
12646
12647	Only within the webservice, a managed object reference (which is really
12648	an opaque number) allows a webservice client to address an object
12649	that lives in the address space of the webservice server.
12650
12651	Behind each managed object reference, there is a COM object that lives
12652	in the webservice server's address space. The COM object is not freed
12653	until the managed object reference is released, either by an explicit
12654	call to <link to="IManagedObjectRef::release" /> or by logging off from
12655	the webservice (<link to="IWebsessionManager::logoff" />), which releases
12656	all objects created during the webservice session.
12657
12658	Whenever a method call of the VirtualBox API returns a COM object, the
12659	webservice representation of that method will instead return a
12660	managed object reference, which can then be used to invoke methods
12661	on that object.
12662	</desc>
12663
12664	<method name="getInterfaceName">
12665	<desc>
12666	Returns the name of the interface that this managed object represents,
12667	for example, "IMachine", as a string.
12668	</desc>
12669	<param name="return" type="wstring" dir="return"/>
12670	</method>
12671
12672	<method name="release">
12673	<desc>
12674	Releases this managed object reference and frees the resources that
12675	were allocated for it in the webservice server process. After calling
12676	this method, the identifier of the reference can no longer be used.
12677	</desc>
12678	</method>
12679
12680	</interface>
12681
12682	<!--
12683	// IWebsessionManager
12684	/////////////////////////////////////////////////////////////////////////
12685	-->
12686
12687	<interface
12688	name="IWebsessionManager" extends="$unknown"
12689	uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
12690	internal="yes"
12691	wsmap="global"
12692	wscpp="hardcoded"
12693	>
12694	<desc>
12695	Websession manager. This provides essential services
12696	to webservice clients.
12697	</desc>
12698	<method name="logon">
12699	<desc>
12700	Logs a new client onto the webservice and returns a managed object reference to
12701	the IVirtualBox instance, which the client can then use as a basis to further
12702	queries, since all calls to the VirtualBox API are based on the IVirtualBox
12703	interface, in one way or the other.
12704	</desc>
12705	<param name="username" type="wstring" dir="in"/>
12706	<param name="password" type="wstring" dir="in"/>
12707	<param name="return" type="IVirtualBox" dir="return"/>
12708	</method>
12709
12710	<method name="getSessionObject">
12711	<desc>
12712	Returns a managed object reference to the internal ISession object that was created
12713	for this web service session when the client logged on.
12714
12715	<see>ISession</see>
12716	</desc>
12717	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
12718	<param name="return" type="ISession" dir="return"/>
12719	</method>
12720
12721	<method name="logoff">
12722	<desc>
12723	Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
12724	and destroys all resources associated with the session (most importantly, all
12725	managed objects created in the server while the session was active).
12726	</desc>
12727	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
12728	</method>
12729
12730	</interface>
12731
12732	</if>
12733
12734	<!--
12735	// IPerformanceCollector & friends
12736	/////////////////////////////////////////////////////////////////////////
12737	-->
12738
12739	<interface
12740	name="IPerformanceMetric" extends="$unknown"
12741	uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
12742	>
12743	<desc>
12744	The IPerformanceMetric interface represents parameters of the given
12745	performance metric.
12746	</desc>
12747
12748	<attribute name="metricName" type="wstring" readonly="yes">
12749	<desc>
12750	Name of the metric.
12751	</desc>
12752	</attribute>
12753
12754	<attribute name="object" type="$unknown" readonly="yes">
12755	<desc>
12756	Object this metric belongs to.
12757	</desc>
12758	</attribute>
12759
12760	<attribute name="description" type="wstring" readonly="yes">
12761	<desc>
12762	Textual description of the metric.
12763	</desc>
12764	</attribute>
12765
12766	<attribute name="period" type="unsigned long" readonly="yes">
12767	<desc>
12768	Time interval between samples, measured in seconds.
12769	</desc>
12770	</attribute>
12771
12772	<attribute name="count" type="unsigned long" readonly="yes">
12773	<desc>
12774	Number of recent samples retained by the performance collector for this
12775	metric.
12776
12777	When the collected sample count exceeds this number, older samples
12778	are discarded.
12779	</desc>
12780	</attribute>
12781
12782	<attribute name="unit" type="wstring" readonly="yes">
12783	<desc>
12784	Unit of measurement.
12785	</desc>
12786	</attribute>
12787
12788	<attribute name="minimumValue" type="long" readonly="yes">
12789	<desc>
12790	Minimum possible value of this metric.
12791	</desc>
12792	</attribute>
12793
12794	<attribute name="maximumValue" type="long" readonly="yes">
12795	<desc>
12796	Maximum possible value of this metric.
12797	</desc>
12798	</attribute>
12799	</interface>
12800
12801	<interface
12802	name="IPerformanceCollector" extends="$unknown"
12803	uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
12804	wsmap="managed"
12805	>
12806	<desc>
12807	The IPerformanceCollector interface represents a service that collects and
12808	stores performance metrics data.
12809
12810	Performance metrics are associated with objects of interfaces like IHost and
12811	IMachine. Each object has a distinct set of performance metrics.
12812	The set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
12813
12814	Metric data is collected at the specified intervals and is retained
12815	internally. The interval and the number of retained samples can be set
12816	with <link to="IPerformanceCollector::setupMetrics" />.
12817
12818	Metrics are organized hierarchically, with each level separated by a
12819	slash (/) character. Generally, the scheme for metric names is like this:
12820
12821	<tt>Category/Metric[/SubMetric][:aggregation]</tt>
12822
12823	"Category/Metric" together form the base metric name. A base metric is the
12824	smallest unit for which a sampling interval and the number of retained
12825	samples can be set. Only base metrics can be enabled and disabled. All
12826	sub-metrics are collected when their base metric is collected.
12827	Collected values for any set of sub-metrics can be queried with
12828	<link to="IPerformanceCollector::queryMetricsData" />.
12829
12830	For example "CPU/Load/User:avg"
12831	metric name stands for the "CPU" category, "Load" metric, "User" submetric,
12832	"average" aggregate. An aggregate function is computed over all retained
12833	data. Valid aggregate functions are:
12834
12835	<ul>
12836	<li>avg -- average</li>
12837	<li>min -- minimum</li>
12838	<li>max -- maximum</li>
12839	</ul>
12840
12841	When setting up
12842	metric parameters, querying metric data, enabling or disabling metrics
12843	wildcards can be used in metric names to specify a subset of metrics. For
12844	example, to select all CPU-related metrics use <tt>CPU/*</tt>, all
12845	averages can be queried using <tt>*:avg</tt> and so on. To query metric
12846	values without aggregates <tt>*:</tt> can be used.
12847
12848	The valid names for base metrics are:
12849
12850	<ul>
12851	<li>CPU/Load</li>
12852	<li>CPU/MHz</li>
12853	<li>RAM/Usage</li>
12854	</ul>
12855
12856	The general sequence for collecting and retrieving the metrics is:
12857	<ul>
12858	<li>
12859	Obtain an instance of IPerformanceCollector with
12860	<link to="IVirtualBox::performanceCollector" />
12861	</li>
12862	<li>
12863	Allocate and populate an array with references to objects the metrics
12864	will be collected for. Use references to IHost and IMachine objects.
12865	</li>
12866	<li>
12867	Allocate and populate an array with base metric names the data will be
12868	collected for.
12869	</li>
12870	<li>
12871	Call <link to="IPerformanceCollector::setupMetrics" />. From now on the
12872	metric data will be collected and stored.
12873	</li>
12874	<li>
12875	Wait for the data to get collected.
12876	</li>
12877	<li>
12878	Allocate and populate an array with references to objects the metric
12879	values will be queried for. You can re-use the object array used for
12880	setting base metrics.
12881	</li>
12882	<li>
12883	Allocate and populate an array with metric names the data will be
12884	collected for. Note that metric names differ from base metric names.
12885	</li>
12886	<li>
12887	Call <link to="IPerformanceCollector::queryMetricsData" />. The data that
12888	have been collected so far are returned. Note that the values are still
12889	retained internally and data collection continues.
12890	</li>
12891	</ul>
12892
12893	For an example of usage refer to the following files in VirtualBox SDK:
12894	<ul>
12895	<li>
12896	Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
12897	</li>
12898	<li>
12899	Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
12900	</li>
12901	</ul>
12902	</desc>
12903
12904	<attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
12905	<desc>
12906	Array of unique names of metrics.
12907
12908	This array represents all metrics supported by the performance
12909	collector. Individual objects do not necessarily support all of them.
12910	<link to="IPerformanceCollector::getMetrics"/> can be used to get the
12911	list of supported metrics for a particular object.
12912	</desc>
12913	</attribute>
12914
12915	<method name="getMetrics">
12916	<desc>
12917	Returns parameters of specified metrics for a set of objects.
12918	<note>
12919	@c Null metrics array means all metrics. @c Null object array means
12920	all existing objects.
12921	</note>
12922	</desc>
12923	<param name="metricNames" type="wstring" dir="in" safearray="yes">
12924	<desc>
12925	Metric name filter. Currently, only a comma-separated list of metrics
12926	is supported.
12927	</desc>
12928	</param>
12929	<param name="objects" type="$unknown" dir="in" safearray="yes">
12930	<desc>
12931	Set of objects to return metric parameters for.
12932	</desc>
12933	</param>
12934	<param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
12935	<desc>
12936	Array of returned metric parameters.
12937	</desc>
12938	</param>
12939	</method>
12940
12941	<method name="setupMetrics">
12942	<desc>
12943	Sets parameters of specified base metrics for a set of objects. Returns
12944	an array of <link to="IPerformanceMetric" /> describing the metrics have
12945	been affected.
12946	<note>
12947	@c Null or empty metric name array means all metrics. @c Null or empty
12948	object array means all existing objects. If metric name array contains
12949	a single element and object array contains many, the single metric
12950	name array element is applied to each object array element to form
12951	metric/object pairs.
12952	</note>
12953	</desc>
12954	<param name="metricNames" type="wstring" dir="in" safearray="yes">
12955	<desc>
12956	Metric name filter. Comma-separated list of metrics with wildcard
12957	support.
12958	</desc>
12959	</param>
12960	<param name="objects" type="$unknown" dir="in" safearray="yes">
12961	<desc>
12962	Set of objects to setup metric parameters for.
12963	</desc>
12964	</param>
12965	<param name="period" type="unsigned long" dir="in">
12966	<desc>
12967	Time interval in seconds between two consecutive samples of performance
12968	data.
12969	</desc>
12970	</param>
12971	<param name="count" type="unsigned long" dir="in">
12972	<desc>
12973	Number of samples to retain in performance data history. Older samples
12974	get discarded.
12975	</desc>
12976	</param>
12977	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
12978	<desc>
12979	Array of metrics that have been modified by the call to this method.
12980	</desc>
12981	</param>
12982	</method>
12983
12984	<method name="enableMetrics">
12985	<desc>
12986	Turns on collecting specified base metrics. Returns an array of
12987	<link to="IPerformanceMetric" /> describing the metrics have been
12988	affected.
12989	<note>
12990	@c Null or empty metric name array means all metrics. @c Null or empty
12991	object array means all existing objects. If metric name array contains
12992	a single element and object array contains many, the single metric
12993	name array element is applied to each object array element to form
12994	metric/object pairs.
12995	</note>
12996	</desc>
12997	<param name="metricNames" type="wstring" dir="in" safearray="yes">
12998	<desc>
12999	Metric name filter. Comma-separated list of metrics with wildcard
13000	support.
13001	</desc>
13002	</param>
13003	<param name="objects" type="$unknown" dir="in" safearray="yes">
13004	<desc>
13005	Set of objects to enable metrics for.
13006	</desc>
13007	</param>
13008	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13009	<desc>
13010	Array of metrics that have been modified by the call to this method.
13011	</desc>
13012	</param>
13013	</method>
13014
13015	<method name="disableMetrics">
13016	<desc>
13017	Turns off collecting specified base metrics. Returns an array of
13018	<link to="IPerformanceMetric" /> describing the metrics have been
13019	affected.
13020	<note>
13021	@c Null or empty metric name array means all metrics. @c Null or empty
13022	object array means all existing objects. If metric name array contains
13023	a single element and object array contains many, the single metric
13024	name array element is applied to each object array element to form
13025	metric/object pairs.
13026	</note>
13027	</desc>
13028	<param name="metricNames" type="wstring" dir="in" safearray="yes">
13029	<desc>
13030	Metric name filter. Comma-separated list of metrics with wildcard
13031	support.
13032	</desc>
13033	</param>
13034	<param name="objects" type="$unknown" dir="in" safearray="yes">
13035	<desc>
13036	Set of objects to disable metrics for.
13037	</desc>
13038	</param>
13039	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13040	<desc>
13041	Array of metrics that have been modified by the call to this method.
13042	</desc>
13043	</param>
13044	</method>
13045
13046	<method name="queryMetricsData">
13047	<desc>
13048	Queries collected metrics data for a set of objects.
13049
13050	The data itself and related metric information are returned in seven
13051	parallel and one flattened array of arrays. Elements of
13052	<tt>returnMetricNames, returnObjects, returnUnits, returnScales,
13053	returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
13054	the same index describe one set of values corresponding to a single
13055	metric.
13056
13057	The <tt>returnData</tt> parameter is a flattened array of arrays. Each
13058	start and length of a sub-array is indicated by
13059	<tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
13060	value for metric <tt>metricNames[i]</tt> is at
13061	<tt>returnData[returnIndices[i]]</tt>.
13062
13063	<note>
13064	@c Null or empty metric name array means all metrics. @c Null or empty
13065	object array means all existing objects. If metric name array contains
13066	a single element and object array contains many, the single metric
13067	name array element is applied to each object array element to form
13068	metric/object pairs.
13069	</note>
13070	<note>
13071	Data collection continues behind the scenes after call to
13072	@c queryMetricsData. The return data can be seen as the snapshot of
13073	the current state at the time of @c queryMetricsData call. The
13074	internally kept metric values are not cleared by the call. This makes
13075	possible querying different subsets of metrics or aggregates with
13076	subsequent calls. If periodic querying is needed it is highly
13077	suggested to query the values with @c interval*count period to avoid
13078	confusion. This way a completely new set of data values will be
13079	provided by each query.
13080	</note>
13081	</desc>
13082	<param name="metricNames" type="wstring" dir="in" safearray="yes">
13083	<desc>
13084	Metric name filter. Comma-separated list of metrics with wildcard
13085	support.
13086	</desc>
13087	</param>
13088	<param name="objects" type="$unknown" dir="in" safearray="yes">
13089	<desc>
13090	Set of objects to query metrics for.
13091	</desc>
13092	</param>
13093	<param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
13094	<desc>
13095	Names of metrics returned in @c returnData.
13096	</desc>
13097	</param>
13098	<param name="returnObjects" type="$unknown" dir="out" safearray="yes">
13099	<desc>
13100	Objects associated with metrics returned in @c returnData.
13101	</desc>
13102	</param>
13103	<param name="returnUnits" type="wstring" dir="out" safearray="yes">
13104	<desc>
13105	Units of measurement for each returned metric.
13106	</desc>
13107	</param>
13108	<param name="returnScales" type="unsigned long" dir="out" safearray="yes">
13109	<desc>
13110	Divisor that should be applied to return values in order to get
13111	floating point values. For example:
13112	<tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
13113	will retrieve the floating point value of i-th sample of the first
13114	metric.
13115	</desc>
13116	</param>
13117	<param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
13118	<desc>
13119	Sequence numbers of the first elements of value sequences of particular metrics
13120	returned in @c returnData. For aggregate metrics it is the sequence number of
13121	the sample the aggregate started calculation from.
13122	</desc>
13123	</param>
13124	<param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
13125	<desc>
13126	Indices of the first elements of value sequences of particular metrics
13127	returned in @c returnData.
13128	</desc>
13129	</param>
13130	<param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
13131	<desc>
13132	Lengths of value sequences of particular metrics.
13133	</desc>
13134	</param>
13135	<param name="returnData" type="long" dir="return" safearray="yes">
13136	<desc>
13137	Flattened array of all metric data containing sequences of values for
13138	each metric.
13139	</desc>
13140	</param>
13141	</method>
13142
13143	</interface>
13144
13145	<module name="VBoxSVC" context="LocalServer">
13146	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
13147	namespace="virtualbox.org">
13148	<interface name="IVirtualBox" default="yes"/>
13149	</class>
13150	</module>
13151
13152	<module name="VBoxC" context="InprocServer" threadingModel="Free">
13153	<class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
13154	namespace="virtualbox.org">
13155	<interface name="ISession" default="yes"/>
13156	</class>
13157	<class name="CallbackWrapper" uuid="49EE8561-5563-4715-B18C-A4B1A490DAFE"
13158	namespace="virtualbox.org">
13159	<interface name="ILocalOwner" default="yes"/>
13160	<interface name="IVirtualBoxCallback"/>
13161	<interface name="IConsoleCallback"/>
13162	</class>
13163	</module>
13164
13165	</library>
13166
13167	</idl>
13168
13169	<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->

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

Download in other formats:

Original Format