VirtualBox.xidl@ 31586

Last change on this file since 31586 was 31577, checked in by vboxsync, 15 years ago
Main, docs: <see> behavior isn't nice, also added IMediumRegisteredEvent description (never triggered).
Property svn:eol-style set to `native`
File size: 556.6 KB

Line
1	<?xml version="1.0" ?>
2
3	<!--
4
5	Copyright (C) 2006-2010 Oracle Corporation
6
7	This file is part of VirtualBox Open Source Edition (OSE), as
8	available from http://www.virtualbox.org. This file is free software;
9	you can redistribute it and/or modify it under the terms of the GNU
10	General Public License (GPL) as published by the Free Software
11	Foundation, in version 2 as it comes in the "COPYING" file of the
12	VirtualBox OSE distribution. VirtualBox OSE is distributed in the
13	hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
14	-->
15
16	<!--
17	This is the master declaration for VirtualBox's Main API,
18	represented by COM/XPCOM and web service interfaces.
19
20	From this document, the build system generates several files
21	via XSLT that are then used during the build process.
22
23	Below is the list of XSL templates that operate on this file and
24	output files they generate. These XSL templates must be updated
25	whenever the schema of this file changes:
26
27	1. src/VBox/Main/idl/midl.xsl =>
28	out/<platform>/bin/sdk/idl/VirtualBox.idl
29	(MS COM interface definition file for Main API)
30
31	2. src/VBox/Main/idl/xpidl.xsl =>
32	out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
33	(XPCOM interface definition file for Main API)
34
35	3. src/VBox/Main/idl/doxygen.xsl =>
36	out/<platform>/obj/src/VBox/Main/VirtualBox.idl
37	(pseudo-IDL for Doxygen to generate the official Main API
38	documentation)
39
40	4. src/VBox/Main/webservice/*.xsl =>
41	a bunch of WSDL and C++ files
42	(VirtualBox web service sources and SOAP mappers;
43	see src/VBox/Main/webservice/Makefile.kmk for details)
44
45	5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
46	out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
47	(smart Qt-based C++ wrapper classes for COM interfaces
48	of the Main API)
49
50	6. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
51	out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
52	(Main API TypeLib block for the WiX installer)
53
54	7. src/VBox/Runtime/common/err/errmsgvboxcom.xsl =>
55	out/<platform>/obj/Runtime/errmsgvboxcomdata.h
56	(<result> extraction for the %Rhrc format specifier)
57	-->
58
59	<idl>
60
61	<desc>
62	Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
63	describes the so-called <i>VirtualBox Main API</i> which comprises all public
64	COM interfaces and components provided by the VirtualBox server and by the
65	VirtualBox client library.
66
67	VirtualBox employs a client-server design, meaning that whenever any part of
68	VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
69	interface or any virtual machine --, a dedicated server process named
70	VBoxSVC runs in the background. This allows multiple processes working with
71	VirtualBox to cooperate without conflicts. These processes communicate to each
72	other using inter-process communication facilities provided by the COM
73	implementation of the host computer.
74
75	On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
76	implementation. On all other platforms, Mozilla XPCOM, an open-source COM
77	implementation, is used.
78
79	All the parts that a typical VirtualBox user interacts with (the Qt GUI,
80	the VBoxManage command-line interface and the VBoxVRDP server) are technically
81	front-ends to the Main API and only use the interfaces that are documented
82	in this Main API documentation. This ensures that, with any given release
83	version of VirtualBox, all capabilities of the product that could be useful
84	to an external client program are always exposed by way of this API.
85
86	The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
87	contains two public component classes:
88	<tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
89	implement IVirtualBox and ISession interfaces respectively. These two classes
90	are of supreme importance and will be needed in order for any front-end
91	program to do anything useful. It is recommended to read the documentation of
92	the mentioned interfaces first.
93
94	The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
95	there can be only one object of this class on the local machine at any given
96	time. This object is a parent of many other objects in the VirtualBox COM
97	library and lives in the VBoxSVC process. In fact, when you create an instance
98	of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
99	process is already running, starts it if not, and returns you a reference to
100	the <tt>VirtualBox</tt> object created in this process. When the last reference
101	to this object is released, the VBoxSVC process ends (with a 5 second delay to
102	protect from too frequent restarts).
103
104	The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
105	as many <tt>Session</tt> objects as you need but all of them will live in a
106	process which issues the object instantiation call. <tt>Session</tt> objects
107	represent virtual machine sessions which are used to configure virtual
108	machines and control their execution.
109	</desc>
110
111	<if target="midl">
112	<cpp line="enum {"/>
113	<cpp line=" kTypeLibraryMajorVersion = 1,"/>
114	<cpp line=" kTypeLibraryMinorVersion = 0"/>
115	<cpp line="};"/>
116	</if>
117
118	<if target="xpidl">
119	<!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
120	<cpp>
121	/* currently, nsISupportsImpl.h lacks the below-like macros */
122
123	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
124	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
125	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI
126	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI NS_IMPL_QUERY_INTERFACE4_CI
127
128
129	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
130	# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
131	NS_IMPL_THREADSAFE_ADDREF(_class) \
132	NS_IMPL_THREADSAFE_RELEASE(_class) \
133	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
134	NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
135	#endif
136
137	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
138	# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
139	NS_IMPL_THREADSAFE_ADDREF(_class) \
140	NS_IMPL_THREADSAFE_RELEASE(_class) \
141	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
142	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
143	#endif
144
145	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI
146	# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \
147	NS_IMPL_THREADSAFE_ADDREF(_class) \
148	NS_IMPL_THREADSAFE_RELEASE(_class) \
149	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \
150	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
151	#endif
152
153	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS4_CI
154	# define NS_IMPL_THREADSAFE_ISUPPORTS4_CI(_class, _i1, _i2, _i3, _i4) \
155	NS_IMPL_THREADSAFE_ADDREF(_class) \
156	NS_IMPL_THREADSAFE_RELEASE(_class) \
157	NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI(_class, _i1, _i2, _i3, _i4) \
158	NS_IMPL_CI_INTERFACE_GETTER4(_class, _i1, _i2, _i3, _i4)
159	#endif
160
161	#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
162	# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
163	NS_INTERFACE_MAP_BEGIN(_class) \
164	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
165	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
166	NS_IMPL_QUERY_CLASSINFO(_class) \
167	NS_INTERFACE_MAP_END
168	#endif
169
170	#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
171	# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
172	_i2, _ic2) \
173	NS_INTERFACE_MAP_BEGIN(_class) \
174	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
175	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
176	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
177	NS_IMPL_QUERY_CLASSINFO(_class) \
178	NS_INTERFACE_MAP_END
179	#endif
180
181	#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
182	# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
183	_i2, _ic2, _i3, _ic3) \
184	NS_INTERFACE_MAP_BEGIN(_class) \
185	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
186	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
187	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \
188	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
189	NS_IMPL_QUERY_CLASSINFO(_class) \
190	NS_INTERFACE_MAP_END
191	#endif
192
193	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
194	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
195	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
196
197	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
198	# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
199	NS_IMPL_THREADSAFE_ADDREF(_class) \
200	NS_IMPL_THREADSAFE_RELEASE(_class) \
201	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
202	NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
203	#endif
204
205	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
206	# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
207	_i2, _ic2) \
208	NS_IMPL_THREADSAFE_ADDREF(_class) \
209	NS_IMPL_THREADSAFE_RELEASE(_class) \
210	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
211	_i2, _ic2) \
212	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
213	#endif
214
215	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI
216	# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \
217	_i2, _ic2, _i3, _ic3) \
218	NS_IMPL_THREADSAFE_ADDREF(_class) \
219	NS_IMPL_THREADSAFE_RELEASE(_class) \
220	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
221	_i2, _ic2, _i3, _ic3) \
222	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
223	#endif
224
225	</cpp>
226	</if>
227
228	<library
229	name="VirtualBox"
230	uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
231	version="1.3"
232	desc="VirtualBox Type Library"
233	appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
234	supportsErrorInfo="yes"
235	>
236
237
238	<!--
239	// COM result codes for VirtualBox
240	/////////////////////////////////////////////////////////////////////////
241	-->
242
243	<descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
244	<desc>
245	This section describes all VirtualBox-specific COM result codes that may
246	be returned by methods of VirtualBox COM interfaces in addition to
247	standard COM result codes.
248
249	Note that along with the result code, every VirtualBox method returns
250	extended error information through the IVirtualBoxErrorInfo interface on
251	failure. This interface is a preferred way to present the error to the end
252	user because it contains a human readable description of the error. Raw
253	result codes, both standard and described in this section, are intended to
254	be used by programs to analyze the reason of a failure and select an
255	appropriate course of action without involving the end user (for example,
256	retry the operation later or make a different call).
257
258	The standard COM result codes that may originate from our methods include:
259
260	<table>
261	<tr><td>E_INVALIDARG</td>
262	<td>
263	Returned when the value of the method's argument is not within the range
264	of valid values. This should not be confused with situations when the
265	value is within the range but simply doesn't suit the current object
266	state and there is a possibility that it will be accepted later (in such
267	cases VirtualBox-specific codes are returned, for example,
268	<link to="VBOX_E_OBJECT_NOT_FOUND"/>).
269	</td>
270	</tr>
271	<tr><td>E_POINTER</td>
272	<td>
273	Returned if a memory pointer for the output argument is invalid (for
274	example, @c null). Note that when pointers representing input
275	arguments (such as strings) are invalid, E_INVALIDARG is returned.
276	</td>
277	</tr>
278	<tr><td>E_ACCESSDENIED</td>
279	<td>
280	Returned when the called object is not ready. Since the lifetime of a
281	public COM object cannot be fully controlled by the implementation,
282	VirtualBox maintains the readiness state for all objects it creates and
283	returns this code in response to any method call on the object that was
284	deactivated by VirtualBox and is not functioning any more.
285	</td>
286	</tr>
287	<tr><td>E_OUTOFMEMORY</td>
288	<td>
289	Returned when a memory allocation operation fails.
290	</td>
291	</tr>
292	</table>
293	</desc>
294	</descGroup>
295
296	<!--
297	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
298	everything in <result>/<desc> after (and including) the first dot, so express
299	the matter of the error code in the first sentence and keep it short.
300	-->
301
302	<result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
303	<desc>
304	Object corresponding to the supplied arguments does not exist.
305	</desc>
306	</result>
307
308	<result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
309	<desc>
310	Current virtual machine state prevents the operation.
311	</desc>
312	</result>
313
314	<result name="VBOX_E_VM_ERROR" value="0x80BB0003">
315	<desc>
316	Virtual machine error occurred attempting the operation.
317	</desc>
318	</result>
319
320	<result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
321	<desc>
322	File not accessible or erroneous file contents.
323	</desc>
324	</result>
325
326	<result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
327	<desc>
328	Runtime subsystem error.
329	</desc>
330	</result>
331
332	<result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
333	<desc>
334	Pluggable Device Manager error.
335	</desc>
336	</result>
337
338	<result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
339	<desc>
340	Current object state prohibits operation.
341	</desc>
342	</result>
343
344	<result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
345	<desc>
346	Host operating system related error.
347	</desc>
348	</result>
349
350	<result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
351	<desc>
352	Requested operation is not supported.
353	</desc>
354	</result>
355
356	<result name="VBOX_E_XML_ERROR" value="0x80BB000A">
357	<desc>
358	Invalid XML found.
359	</desc>
360	</result>
361
362	<result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
363	<desc>
364	Current session state prohibits operation.
365	</desc>
366	</result>
367
368	<result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
369	<desc>
370	Object being in use prohibits operation.
371	</desc>
372	</result>
373
374	<!--
375	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
376	everything in <result>/<desc> after (and including) the first dot, so express
377	the matter of the error code in the first sentence and keep it short.
378	-->
379
380	<descGroup/>
381
382	<!--
383	// all common enums
384	/////////////////////////////////////////////////////////////////////////
385	-->
386
387	<enum name="SettingsVersion"
388	uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f"
389	>
390	<desc>Settings version of VirtualBox settings files. This is written to
391	the "version" attribute of the root "VirtualBox" element in the settings
392	file XML and indicates which VirtualBox version wrote the file.
393	</desc>
394
395	<const name="Null" value="0">
396	<desc>Null value, indicates invalid version.</desc>
397	</const>
398	<const name="v1_0" value="1">
399	<desc>Legacy settings version, not currently supported.</desc>
400	</const>
401	<const name="v1_1" value="2">
402	<desc>Legacy settings version, not currently supported.</desc>
403	</const>
404	<const name="v1_2" value="3">
405	<desc>Legacy settings version, not currently supported.</desc>
406	</const>
407	<const name="v1_3pre" value="4">
408	<desc>Legacy settings version, not currently supported.</desc>
409	</const>
410	<const name="v1_3" value="5">
411	<desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>
412	<!--
413	Machine XML: Capitalization of Uart, Lpt elements and many attributes changed.
414	-->
415	</const>
416	<const name="v1_4" value="6">
417	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
418	<!--
419	VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged
420	(was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk)
421	-->
422	</const>
423	<const name="v1_5" value="7">
424	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
425	<!-- 2008-09-04: 2.0.0 released
426	2008-11-20: settings version 1.5 introduced
427	2008-12-17: 2.1.0 released
428	Machine changes:
429	guest OS identifiers changed;
430	Machine/Hardware/Display/MonitorCount renamed to monitorCount;
431	Machine/Hardware/Display/Accelerate3D renamed to accelerate3D;
432	Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count
433	-->
434	</const>
435	<const name="v1_6" value="8">
436	<desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>
437	<!-- 2008-12-17: 2.1.0 released
438	2008-12-19: settings version 1.6 introduced (is in 2.1 branch)
439	2009-04-08: 2.2.0 released
440	Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done)
441	-->
442	</const>
443	<const name="v1_7" value="9">
444	<desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>
445	<!-- 2008-12-17: 2.1.0 released
446	2009-03-11: settings version 1.7 introduced (is in 2.2 branch)
447	2009-04-08: 2.2.0 released
448	VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done)
449	Machine changes: HardDiskAttachments is now StorageControllers (done)
450	-->
451	</const>
452	<const name="v1_8" value="10">
453	<desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>
454	<!-- Machine additions: Display/@accelerate2DVideo (done)
455	-->
456	</const>
457	<const name="v1_9" value="11">
458	<desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>
459	<!-- The big storage controller / DVD / Floppy rework (done)
460	-->
461	</const>
462	<const name="v1_10" value="12">
463	<desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc>
464	<!-- Machine changes: RTC localOrUTC (done)
465	CPU hot-plug support
466	-->
467	</const>
468	<const name="v1_11" value="13">
469	<desc>Settings version "1.11", written by VirtualBox 3.3.x.</desc>
470	<!-- Machine changes: HD Audio controller, per-machine disk registries
471	-->
472	</const>
473	<const name="Future" value="99999">
474	<desc>Settings version greater than "1.11", written by a future VirtualBox version.</desc>
475	</const>
476	</enum>
477
478	<enum
479	name="AccessMode"
480	uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
481	>
482	<desc>
483	Access mode for opening files.
484	</desc>
485
486	<const name="ReadOnly" value="1"/>
487	<const name="ReadWrite" value="2"/>
488	</enum>
489
490	<enum
491	name="MachineState"
492	uuid="e998d075-543a-41fc-8aa9-5ca3e92393fd"
493	>
494	<desc>
495	Virtual machine execution state.
496
497	This enumeration represents possible values of the <link
498	to="IMachine::state"/> attribute.
499
500	Below is the basic virtual machine state diagram. It shows how the state
501	changes during virtual machine execution. The text in square braces shows
502	a method of the IConsole interface that performs the given state
503	transition.
504
505	<pre>
506	+---------[powerDown()] <- Stuck <--[failure]-+
507	V \|
508	+-> PoweredOff --+-->[powerUp()]--> Starting --+ \| +-----[resume()]-----+
509	\| \| \| \| V \|
510	\| Aborted -----+ +--> Running --[pause()]--> Paused
511	\| \| ^ \| ^ \|
512	\| Saved -----------[powerUp()]--> Restoring -+ \| \| \| \|
513	\| ^ \| \| \| \|
514	\| \| +-----------------------------------------+-\|-------------------+ +
515	\| \| \| \| \|
516	\| \| +-- Saving <--------[takeSnapshot()]<-------+---------------------+
517	\| \| \| \|
518	\| +-------- Saving <--------[saveState()]<----------+---------------------+
519	\| \| \|
520	+-------------- Stopping -------[powerDown()]<----------+---------------------+
521	</pre>
522
523	Note that states to the right from PoweredOff, Aborted and Saved in the
524	above diagram are called <i>online VM states</i>. These states
525	represent the virtual machine which is being executed in a dedicated
526	process (usually with a GUI window attached to it where you can see the
527	activity of the virtual machine and interact with it). There are two
528	special pseudo-states, FirstOnline and LastOnline, that can be used in
529	relational expressions to detect if the given machine state is online or
530	not:
531
532	<pre>
533	if (machine.GetState() >= MachineState_FirstOnline &&
534	machine.GetState() <= MachineState_LastOnline)
535	{
536	...the machine is being executed...
537	}
538	</pre>
539
540	When the virtual machine is in one of the online VM states (that is, being
541	executed), only a few machine settings can be modified. Methods working
542	with such settings contain an explicit note about that. An attempt to
543	change any oter setting or perform a modifying operation during this time
544	will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
545
546	All online states except Running, Paused and Stuck are transitional: they
547	represent temporary conditions of the virtual machine that will last as
548	long as the operation that initiated such a condition.
549
550	The Stuck state is a special case. It means that execution of the machine
551	has reached the "Guru Meditation" condition. This condition indicates an
552	internal VMM (virtual machine manager) failure which may happen as a
553	result of either an unhandled low-level virtual hardware exception or one
554	of the recompiler exceptions (such as the <i>too-many-traps</i>
555	condition).
556
557	Note also that any online VM state may transit to the Aborted state. This
558	happens if the process that is executing the virtual machine terminates
559	unexpectedly (for example, crashes). Other than that, the Aborted state is
560	equivalent to PoweredOff.
561
562	There are also a few additional state diagrams that do not deal with
563	virtual machine execution and therefore are shown separately. The states
564	shown on these diagrams are called <i>offline VM states</i> (this includes
565	PoweredOff, Aborted and Saved too).
566
567	The first diagram shows what happens when a lengthy setup operation is
568	being executed (such as <link to="IMachine::attachDevice"/>).
569
570	<pre>
571	+----------------------------------(same state as before the call)------+
572	\| \|
573	+-> PoweredOff --+ \|
574	\| \| \|
575	\|-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
576	\| \|
577	+-> Saved -------+
578	</pre>
579
580	The next two diagrams demonstrate the process of taking a snapshot of a
581	powered off virtual machine, restoring the state to that as of a snapshot
582	or deleting a snapshot, respectively.
583
584	<pre>
585	+----------------------------------(same state as before the call)------+
586	\| \|
587	+-> PoweredOff --+ \|
588	\| +-->[takeSnapshot()] -------------------> Saving ------+
589	+-> Aborted -----+
590
591	+-> PoweredOff --+
592	\| \|
593	\| Aborted -----+-->[restoreSnapshot() ]-------> RestoringSnapshot -+
594	\| \| [deleteSnapshot() ]-------> DeletingSnapshot --+
595	+-> Saved -------+ \|
596	\| \|
597	+---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
598	</pre>
599
600	Note that the Saving state is present in both the offline state group and
601	online state group. Currently, the only way to determine what group is
602	assumed in a particular case is to remember the previous machine state: if
603	it was Running or Paused, then Saving is an online state, otherwise it is
604	an offline state. This inconsistency may be removed in one of the future
605	versions of VirtualBox by adding a new state.
606
607	<note internal="yes">
608	For whoever decides to touch this enum: In order to keep the
609	comparisons involving FirstOnline and LastOnline pseudo-states valid,
610	the numeric values of these states must be correspondingly updated if
611	needed: for any online VM state, the condition
612	<tt>FirstOnline <= state <= LastOnline</tt> must be
613	@c true. The same relates to transient states for which
614	the condition <tt>FirstOnline <= state <= LastOnline</tt> must be
615	@c true.
616	</note>
617	</desc>
618
619	<const name="Null" value="0">
620	<desc>Null value (never used by the API).</desc>
621	</const>
622	<const name="PoweredOff" value="1">
623	<desc>
624	The machine is not running and has no saved execution state; it has
625	either never been started or been shut down successfully.
626	</desc>
627	</const>
628	<const name="Saved" value="2">
629	<desc>
630	The machine is not currently running, but the execution state of the machine
631	has been saved to an external file when it was running, from where
632	it can be resumed.
633	</desc>
634	</const>
635	<const name="Teleported" value="3">
636	<desc>
637	The machine was teleported to a different host (or process) and then
638	powered off. Take care when powering it on again may corrupt resources
639	it shares with the teleportation target (e.g. disk and network).
640	</desc>
641	</const>
642	<const name="Aborted" value="4">
643	<desc>
644	The process running the machine has terminated abnormally. This may
645	indicate a crash of the VM process in host execution context, or
646	the VM process has been terminated externally.
647	</desc>
648	</const>
649	<const name="Running" value="5">
650	<desc>
651	The machine is currently being executed.
652	<note internal="yes">
653	For whoever decides to touch this enum: In order to keep the
654	comparisons in the old source code valid, this state must immediately
655	precede the Paused state.
656	TODO: Lift this spectacularly wonderful restriction.
657	</note>
658	</desc>
659	</const>
660	<const name="Paused" value="6">
661	<desc>
662	Execution of the machine has been paused.
663	<note internal="yes">
664	For whoever decides to touch this enum: In order to keep the
665	comparisons in the old source code valid, this state must immediately
666	follow the Running state.
667	TODO: Lift this spectacularly wonderful restriction.
668	</note>
669	</desc>
670	</const>
671	<const name="Stuck" value="7">
672	<desc>
673	Execution of the machine has reached the "Guru Meditation"
674	condition. This indicates a severe error in the hypervisor itself.
675	<note internal="yes">
676	bird: Why this uncool name? Could we rename it to "GuruMeditation" or
677	"Guru", perhaps? Or are there some other VMM states that are
678	intended to be lumped in here as well?
679	</note>
680	</desc>
681	</const>
682	<const name="Teleporting" value="8">
683	<desc>
684	The machine is about to be teleported to a different host or process.
685	It is possible to pause a machine in this state, but it will go to the
686	@c TeleportingPausedVM state and it will not be
687	possible to resume it again unless the teleportation fails.
688	</desc>
689	</const>
690	<const name="LiveSnapshotting" value="9">
691	<desc>
692	A live snapshot is being taken. The machine is running normally, but
693	some of the runtime configuration options are inaccessible. Also, if
694	paused while in this state it will transition to
695	@c Saving and it will not be resume the
696	execution until the snapshot operation has completed.
697	</desc>
698	</const>
699	<const name="Starting" value="10">
700	<desc>
701	Machine is being started after powering it on from a
702	zero execution state.
703	</desc>
704	</const>
705	<const name="Stopping" value="11">
706	<desc>
707	Machine is being normally stopped powering it off, or after the guest OS
708	has initiated a shutdown sequence.
709	</desc>
710	</const>
711	<const name="Saving" value="12">
712	<desc>
713	Machine is saving its execution state to a file, or an online
714	snapshot of the machine is being taken.
715	</desc>
716	</const>
717	<const name="Restoring" value="13">
718	<desc>
719	Execution state of the machine is being restored from a file
720	after powering it on from the saved execution state.
721	</desc>
722	</const>
723	<const name="TeleportingPausedVM" value="14">
724	<desc>
725	The machine is being teleported to another host or process, but it is
726	not running. This is the paused variant of the
727	@c state.
728	</desc>
729	</const>
730	<const name="TeleportingIn" value="15">
731	<desc>
732	Teleporting the machine state in from another host or process.
733	</desc>
734	</const>
735	<const name="DeletingSnapshotOnline" value="16">
736	<desc>
737	Like @c DeletingSnapshot, but the merging of media is ongoing in
738	the background while the machine is running.
739	</desc>
740	</const>
741	<const name="DeletingSnapshotPaused" value="17">
742	<desc>
743	Like @c DeletingSnapshotOnline, but the machine was paused when the
744	merging of differencing media was started.
745	</desc>
746	</const>
747	<const name="RestoringSnapshot" value="18">
748	<desc>
749	A machine snapshot is being restored; this typically does not take long.
750	</desc>
751	</const>
752	<const name="DeletingSnapshot" value="19">
753	<desc>
754	A machine snapshot is being deleted; this can take a long time since this
755	may require merging differencing media. This value indicates that the
756	machine is not running while the snapshot is being deleted.
757	</desc>
758	</const>
759	<const name="SettingUp" value="20">
760	<desc>
761	Lengthy setup operation is in progress.
762	</desc>
763	</const>
764
765	<const name="FirstOnline" value="5" wsmap="suppress"> <!-- Running -->
766	<desc>
767	Pseudo-state: first online state (for use in relational expressions).
768	</desc>
769	</const>
770	<const name="LastOnline" value="17" wsmap="suppress"> <!-- DeletingSnapshotPaused -->
771	<desc>
772	Pseudo-state: last online state (for use in relational expressions).
773	</desc>
774	</const>
775
776	<const name="FirstTransient" value="8" wsmap="suppress"> <!-- Teleporting -->
777	<desc>
778	Pseudo-state: first transient state (for use in relational expressions).
779	</desc>
780	</const>
781	<const name="LastTransient" value="20" wsmap="suppress"> <!-- SettingUp -->
782	<desc>
783	Pseudo-state: last transient state (for use in relational expressions).
784	</desc>
785	</const>
786
787	</enum>
788
789	<enum
790	name="SessionState"
791	uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8"
792	>
793	<desc>
794	Session state. This enumeration represents possible values of
795	<link to="IMachine::sessionState"/> and <link to="ISession::state"/>
796	attributes.
797	</desc>
798
799	<const name="Null" value="0">
800	<desc>Null value (never used by the API).</desc>
801	</const>
802	<const name="Unlocked" value="1">
803	<desc>
804	In <link to="IMachine::sessionState"/>, this means that the machine
805	is not locked for any sessions.
806
807	In <link to="ISession::state"/>, this means that no machine is
808	currently locked for this session.
809	</desc>
810	</const>
811	<const name="Locked" value="2">
812	<desc>
813	In <link to="IMachine::sessionState"/>, this means that the machine
814	is currently locked for a session, whose process identifier can
815	then be found in the <link to="IMachine::sessionPid" /> attribute.
816
817	In <link to="ISession::state"/>, this means that a machine is
818	currently locked for this session, and the mutable machine object
819	can be found in the <link to="ISession::machine"/> attribute
820	(see <link to="IMachine::lockMachine" /> for details).
821	</desc>
822	</const>
823	<const name="Spawning" value="3">
824	<desc>
825	A new process is being spawned for the machine as a result of
826	<link to="IMachine::launchVMProcess"/> call. This state also occurs
827	as a short transient state during an <link to="IMachine::lockMachine"/>
828	call.
829	</desc>
830	</const>
831	<const name="Unlocking" value="4">
832	<desc>
833	The session is being unlocked.
834	</desc>
835	</const>
836	</enum>
837
838	<enum
839	name="CPUPropertyType"
840	uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5"
841	>
842	<desc>
843	Virtual CPU property type. This enumeration represents possible values of the
844	IMachine get- and setCPUProperty methods.
845	</desc>
846	<const name="Null" value="0">
847	<desc>Null value (never used by the API).</desc>
848	</const>
849	<const name="PAE" value="1">
850	<desc>
851	This setting determines whether VirtualBox will expose the Physical Address
852	Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
853	is not available, it will not be reported.
854	</desc>
855	</const>
856	<const name="Synthetic" value="2">
857	<desc>
858	This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow
859	teleporting between host systems that differ significantly.
860	</desc>
861	</const>
862	</enum>
863
864
865	<enum
866	name="HWVirtExPropertyType"
867	uuid="ce81dfdd-d2b8-4a90-bbea-40ee8b7ffcee"
868	>
869	<desc>
870	Hardware virtualization property type. This enumeration represents possible values
871	for the <link to="IMachine::getHWVirtExProperty"/> and
872	<link to="IMachine::setHWVirtExProperty"/> methods.
873	</desc>
874	<const name="Null" value="0">
875	<desc>Null value (never used by the API).</desc>
876	</const>
877	<const name="Enabled" value="1">
878	<desc>
879	Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If
880	such extensions are not available, they will not be used.
881	</desc>
882	</const>
883	<const name="Exclusive" value="2">
884	<desc>
885	Whether hardware virtualization is used exclusively by VirtualBox. When enabled,
886	VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V
887	feature of the host. To share these with other hypervisors, you must disable this property.
888	</desc>
889	</const>
890	<const name="VPID" value="3">
891	<desc>
892	Whether VT-x VPID is enabled. If this extension is not available, it will not be used.
893	</desc>
894	</const>
895	<const name="NestedPaging" value="4">
896	<desc>
897	Whether Nested Paging is enabled. If this extension is not available, it will not be used.
898	</desc>
899	</const>
900	<const name="LargePages" value="5">
901	<desc>
902	Whether large page allocation is enabled; requires nested paging and a 64 bits host.
903	</desc>
904	</const>
905	</enum>
906
907	<enum
908	name="LockType"
909	uuid="138b53f8-db4b-47c5-b32b-4ef52f769413"
910	>
911	<desc>
912	Used with <link to="IMachine::lockMachine" />.
913	</desc>
914	<const name="Write" value="2">
915	<desc>Lock the machine for writing.</desc>
916	</const>
917	<const name="Shared" value="1">
918	<desc>Request only a shared read lock for remote-controlling the machine.</desc>
919	</const>
920	</enum>
921
922	<enum
923	name="SessionType"
924	uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
925	>
926	<desc>
927	Session type. This enumeration represents possible values of the
928	<link to="ISession::type"/> attribute.
929	</desc>
930
931	<const name="Null" value="0">
932	<desc>Null value (never used by the API).</desc>
933	</const>
934	<const name="WriteLock" value="1">
935	<desc>
936	Session has acquired an exclusive write lock on a machine
937	using <link to="IMachine::lockMachine"/>.
938	</desc>
939	</const>
940	<const name="Remote" value="2">
941	<desc>
942	Session has launched a VM process using
943	<link to="IMachine::launchVMProcess"/>
944	</desc>
945	</const>
946	<const name="Shared" value="3">
947	<desc>
948	Session has obtained a link to another session using
949	<link to="IMachine::lockMachine"/>
950	</desc>
951	</const>
952	</enum>
953
954	<enum
955	name="DeviceType"
956	uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
957	>
958	<desc>
959	Device type.
960	</desc>
961	<const name="Null" value="0">
962	<desc>
963	Null value, may also mean "no device" (not allowed for
964	<link to="IConsole::getDeviceActivity"/>).
965	</desc>
966	</const>
967	<const name="Floppy" value="1">
968	<desc>Floppy device.</desc>
969	</const>
970	<const name="DVD" value="2">
971	<desc>CD/DVD-ROM device.</desc>
972	</const>
973	<const name="HardDisk" value="3">
974	<desc>Hard disk device.</desc>
975	</const>
976	<const name="Network" value="4">
977	<desc>Network device.</desc>
978	</const>
979	<const name="USB" value="5">
980	<desc>USB device.</desc>
981	</const>
982	<const name="SharedFolder" value="6">
983	<desc>Shared folder device.</desc>
984	</const>
985	</enum>
986
987	<enum
988	name="DeviceActivity"
989	uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
990	>
991	<desc>
992	Device activity for <link to="IConsole::getDeviceActivity"/>.
993	</desc>
994
995	<const name="Null" value="0"/>
996	<const name="Idle" value="1"/>
997	<const name="Reading" value="2"/>
998	<const name="Writing" value="3"/>
999	</enum>
1000
1001	<enum
1002	name="ClipboardMode"
1003	uuid="33364716-4008-4701-8f14-be0fa3d62950"
1004	>
1005	<desc>
1006	Host-Guest clipboard interchange mode.
1007	</desc>
1008
1009	<const name="Disabled" value="0"/>
1010	<const name="HostToGuest" value="1"/>
1011	<const name="GuestToHost" value="2"/>
1012	<const name="Bidirectional" value="3"/>
1013	</enum>
1014
1015	<enum
1016	name="Scope"
1017	uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
1018	>
1019	<desc>
1020	Scope of the operation.
1021
1022	A generic enumeration used in various methods to define the action or
1023	argument scope.
1024	</desc>
1025
1026	<const name="Global" value="0"/>
1027	<const name="Machine" value="1"/>
1028	<const name="Session" value="2"/>
1029	</enum>
1030
1031	<enum
1032	name="BIOSBootMenuMode"
1033	uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
1034	>
1035	<desc>
1036	BIOS boot menu mode.
1037	</desc>
1038
1039	<const name="Disabled" value="0"/>
1040	<const name="MenuOnly" value="1"/>
1041	<const name="MessageAndMenu" value="2"/>
1042	</enum>
1043
1044	<enum
1045	name="ProcessorFeature"
1046	uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
1047	>
1048	<desc>
1049	CPU features.
1050	</desc>
1051
1052	<const name="HWVirtEx" value="0"/>
1053	<const name="PAE" value="1"/>
1054	<const name="LongMode" value="2"/>
1055	<const name="NestedPaging" value="3"/>
1056	</enum>
1057
1058	<enum
1059	name="FirmwareType"
1060	uuid="b903f264-c230-483e-ac74-2b37ce60d371"
1061	>
1062	<desc>
1063	Firmware type.
1064	</desc>
1065	<const name="BIOS" value="1">
1066	<desc>BIOS Firmware.</desc>
1067	</const>
1068	<const name="EFI" value="2">
1069	<desc>EFI Firmware, bitness detetced basing on OS type.</desc>
1070	</const>
1071	<const name="EFI32" value="3">
1072	<desc>Efi firmware, 32-bit.</desc>
1073	</const>
1074	<const name="EFI64" value="4">
1075	<desc>Efi firmware, 64-bit.</desc>
1076	</const>
1077	<const name="EFIDUAL" value="5">
1078	<desc>Efi firmware, combined 32 and 64-bit.</desc>
1079	</const>
1080	</enum>
1081
1082	<enum
1083	name="PointingHidType"
1084	uuid="0d3c17a2-821a-4b2e-ae41-890c6c60aa97"
1085	>
1086	<desc>
1087	Type of pointing device used in a virtual machine.
1088	</desc>
1089	<const name="None" value="1">
1090	<desc>No mouse.</desc>
1091	</const>
1092	<const name="PS2Mouse" value="2">
1093	<desc>PS/2 auxillary device, a.k.a. mouse.</desc>
1094	</const>
1095	<const name="USBMouse" value="3">
1096	<desc>USB mouse (relative pointer).</desc>
1097	</const>
1098	<const name="USBTablet" value="4">
1099	<desc>USB tablet (absolute pointer).</desc>
1100	</const>
1101	<const name="ComboMouse" value="5">
1102	<desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.
1103	Using of such device can have negative performance implications. </desc>
1104	</const>
1105	</enum>
1106
1107	<enum
1108	name="KeyboardHidType"
1109	uuid="5a5b0996-3a3e-44bb-9019-56979812cbcc"
1110	>
1111	<desc>
1112	Type of keyboard device used in a virtual machine.
1113	</desc>
1114	<const name="None" value="1">
1115	<desc>No keyboard.</desc>
1116	</const>
1117	<const name="PS2Keyboard" value="2">
1118	<desc>PS/2 keyboard.</desc>
1119	</const>
1120	<const name="USBKeyboard" value="3">
1121	<desc>USB keyboard.</desc>
1122	</const>
1123	<const name="ComboKeyboard" value="4">
1124	<desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.
1125	Using of such device can have negative performance implications. </desc>
1126	</const>
1127	</enum>
1128
1129	<!--
1130	// IVirtualBoxErrorInfo
1131	/////////////////////////////////////////////////////////////////////////
1132	-->
1133
1134	<interface
1135	name="IVirtualBoxErrorInfo" extends="$errorinfo"
1136	uuid="e053d3c0-f493-491b-a735-3a9f0b1feed4"
1137	supportsErrorInfo="no"
1138	wsmap="managed"
1139	>
1140	<desc>
1141	The IVirtualBoxErrorInfo interface represents extended error information.
1142
1143	Extended error information can be set by VirtualBox components after
1144	unsuccessful or partially successful method invocation. This information
1145	can be retrieved by the calling party as an IVirtualBoxErrorInfo object
1146	and then shown to the client in addition to the plain 32-bit result code.
1147
1148	In MS COM, this interface extends the IErrorInfo interface,
1149	in XPCOM, it extends the nsIException interface. In both cases,
1150	it provides a set of common attributes to retrieve error
1151	information.
1152
1153	Sometimes invocation of some component's method may involve methods of
1154	other components that may also fail (independently of this method's
1155	failure), or a series of non-fatal errors may precede a fatal error that
1156	causes method failure. In cases like that, it may be desirable to preserve
1157	information about all errors happened during method invocation and deliver
1158	it to the caller. The <link to="#next"/> attribute is intended
1159	specifically for this purpose and allows to represent a chain of errors
1160	through a single IVirtualBoxErrorInfo object set after method invocation.
1161
1162	Note that errors are stored to a chain in the reverse order, i.e. the
1163	initial error object you query right after method invocation is the last
1164	error set by the callee, the object it points to in the @a next attribute
1165	is the previous error and so on, up to the first error (which is the last
1166	in the chain).
1167	</desc>
1168
1169	<attribute name="resultCode" type="long" readonly="yes">
1170	<desc>
1171	Result code of the error.
1172	Usually, it will be the same as the result code returned
1173	by the method that provided this error information, but not
1174	always. For example, on Win32, CoCreateInstance() will most
1175	likely return E_NOINTERFACE upon unsuccessful component
1176	instantiation attempt, but not the value the component factory
1177	returned. Value is typed 'long', not 'result',
1178	to make interface usable from scripting languages.
1179	<note>
1180	In MS COM, there is no equivalent.
1181	In XPCOM, it is the same as nsIException::result.
1182	</note>
1183	</desc>
1184	</attribute>
1185
1186	<attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
1187	<desc>
1188	UUID of the interface that defined the error.
1189	<note>
1190	In MS COM, it is the same as IErrorInfo::GetGUID, except for the
1191	data type.
1192	In XPCOM, there is no equivalent.
1193	</note>
1194	</desc>
1195	</attribute>
1196
1197	<attribute name="component" type="wstring" readonly="yes">
1198	<desc>
1199	Name of the component that generated the error.
1200	<note>
1201	In MS COM, it is the same as IErrorInfo::GetSource.
1202	In XPCOM, there is no equivalent.
1203	</note>
1204	</desc>
1205	</attribute>
1206
1207	<attribute name="text" type="wstring" readonly="yes">
1208	<desc>
1209	Text description of the error.
1210	<note>
1211	In MS COM, it is the same as IErrorInfo::GetDescription.
1212	In XPCOM, it is the same as nsIException::message.
1213	</note>
1214	</desc>
1215	</attribute>
1216
1217	<attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
1218	<desc>
1219	Next error object if there is any, or @c null otherwise.
1220	<note>
1221	In MS COM, there is no equivalent.
1222	In XPCOM, it is the same as nsIException::inner.
1223	</note>
1224	</desc>
1225	</attribute>
1226
1227	</interface>
1228
1229	<!--
1230	// IVirtualBox
1231	/////////////////////////////////////////////////////////////////////////
1232	-->
1233
1234	<interface
1235	name="IDHCPServer" extends="$unknown"
1236	uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
1237	wsmap="managed"
1238	>
1239	<desc>
1240	The IDHCPServer interface represents the vbox dhcp server configuration.
1241
1242	To enumerate all the dhcp servers on the host, use the
1243	<link to="IVirtualBox::DHCPServers"/> attribute.
1244	</desc>
1245
1246	<attribute name="enabled" type="boolean">
1247	<desc>
1248	specifies if the dhcp server is enabled
1249	</desc>
1250	</attribute>
1251
1252	<attribute name="IPAddress" type="wstring" readonly="yes">
1253	<desc>
1254	specifies server IP
1255	</desc>
1256	</attribute>
1257
1258	<attribute name="networkMask" type="wstring" readonly="yes">
1259	<desc>
1260	specifies server network mask
1261	</desc>
1262	</attribute>
1263
1264	<attribute name="networkName" type="wstring" readonly="yes">
1265	<desc>
1266	specifies internal network name the server is used for
1267	</desc>
1268	</attribute>
1269
1270	<attribute name="lowerIP" type="wstring" readonly="yes">
1271	<desc>
1272	specifies from IP adrres in server address range
1273	</desc>
1274	</attribute>
1275
1276	<attribute name="upperIP" type="wstring" readonly="yes">
1277	<desc>
1278	specifies to IP adrres in server address range
1279	</desc>
1280	</attribute>
1281
1282	<method name="setConfiguration">
1283	<desc>
1284	configures the server
1285	<result name="E_INVALIDARG">
1286	invalid configuration supplied
1287	</result>
1288	</desc>
1289	<param name="IPAddress" type="wstring" dir="in">
1290	<desc>
1291	server IP address
1292	</desc>
1293	</param>
1294	<param name="networkMask" type="wstring" dir="in">
1295	<desc>
1296	server network mask
1297	</desc>
1298	</param>
1299	<param name="FromIPAddress" type="wstring" dir="in">
1300	<desc>
1301	server From IP address for address range
1302	</desc>
1303	</param>
1304	<param name="ToIPAddress" type="wstring" dir="in">
1305	<desc>
1306	server To IP address for address range
1307	</desc>
1308	</param>
1309	</method>
1310
1311	<method name="start">
1312	<desc>
1313	Starts DHCP server process.
1314	<result name="E_FAIL">
1315	Failed to start the process.
1316	</result>
1317	</desc>
1318	<param name="networkName" type="wstring" dir="in">
1319	<desc>
1320	Name of internal network DHCP server should attach to.
1321	</desc>
1322	</param>
1323	<param name="trunkName" type="wstring" dir="in">
1324	<desc>
1325	Name of internal network trunk.
1326	</desc>
1327	</param>
1328	<param name="trunkType" type="wstring" dir="in">
1329	<desc>
1330	Type of internal network trunk.
1331	</desc>
1332	</param>
1333	</method>
1334
1335	<method name="stop">
1336	<desc>
1337	Stops DHCP server process.
1338	<result name="E_FAIL">
1339	Failed to stop the process.
1340	</result>
1341	</desc>
1342	</method>
1343	</interface>
1344
1345	<interface
1346	name="IVirtualBox" extends="$unknown"
1347	uuid="ec6cc7e7-06a2-4c5d-8993-1e3619c53817"
1348	wsmap="managed"
1349	>
1350	<desc>
1351	The IVirtualBox interface represents the main interface exposed by the
1352	product that provides virtual machine management.
1353
1354	An instance of IVirtualBox is required for the product to do anything
1355	useful. Even though the interface does not expose this, internally,
1356	IVirtualBox is implemented as a singleton and actually lives in the
1357	process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1358	IVirtualBox can track the state of all virtual machines on a particular
1359	host, regardless of which frontend started them.
1360
1361	To enumerate all the virtual machines on the host, use the
1362	<link to="IVirtualBox::machines"/> attribute.
1363	</desc>
1364
1365	<attribute name="version" type="wstring" readonly="yes">
1366	<desc>
1367	A string representing the version number of the product. The
1368	format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1369	last number represents the build number and will frequently change.
1370	</desc>
1371	</attribute>
1372
1373	<attribute name="revision" type="unsigned long" readonly="yes">
1374	<desc>
1375	The internal build revision number of the product.
1376	</desc>
1377	</attribute>
1378
1379	<attribute name="packageType" type="wstring" readonly="yes">
1380	<desc>
1381	A string representing the package type of this product. The
1382	format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1383	SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1384	is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1385	this.
1386	</desc>
1387	</attribute>
1388
1389	<attribute name="homeFolder" type="wstring" readonly="yes">
1390	<desc>
1391	Full path to the directory where the global settings file,
1392	<tt>VirtualBox.xml</tt>, is stored.
1393
1394	In this version of VirtualBox, the value of this property is
1395	always <tt><user_dir>/.VirtualBox</tt> (where
1396	<tt><user_dir></tt> is the path to the user directory,
1397	as determined by the host OS), and cannot be changed.
1398
1399	This path is also used as the base to resolve relative paths in
1400	places where relative paths are allowed (unless otherwise
1401	expressly indicated).
1402	</desc>
1403	</attribute>
1404
1405	<attribute name="settingsFilePath" type="wstring" readonly="yes">
1406	<desc>
1407	Full name of the global settings file.
1408	The value of this property corresponds to the value of
1409	<link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1410	</desc>
1411	</attribute>
1412
1413	<attribute name="host" type="IHost" readonly="yes">
1414	<desc>Associated host object.</desc>
1415	</attribute>
1416
1417	<attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1418	<desc>Associated system information object.</desc>
1419	</attribute>
1420
1421	<attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1422	<desc>
1423	Array of machine objects registered within this VirtualBox instance.
1424	</desc>
1425	</attribute>
1426
1427	<attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
1428	<desc>
1429	Array of medium objects known to this VirtualBox installation.
1430
1431	This array contains only base media. All differencing
1432	media of the given base medium can be enumerated using
1433	<link to="IMedium::children"/>.
1434	</desc>
1435	</attribute>
1436
1437	<attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
1438	<desc>
1439	Array of CD/DVD image objects registered with this VirtualBox instance.
1440	</desc>
1441	</attribute>
1442
1443	<attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
1444	<desc>
1445	Array of floppy image objects registered with this VirtualBox instance.
1446	</desc>
1447	</attribute>
1448
1449	<attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1450
1451	<attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1452
1453	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1454	<desc>
1455	Collection of global shared folders. Global shared folders are
1456	available to all virtual machines.
1457
1458	New shared folders are added to the collection using
1459	<link to="#createSharedFolder"/>. Existing shared folders can be
1460	removed using <link to="#removeSharedFolder"/>.
1461
1462	<note>
1463	In the current version of the product, global shared folders are not
1464	implemented and therefore this collection is always empty.
1465	</note>
1466	</desc>
1467	</attribute>
1468
1469	<attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1470	<desc>
1471	Associated performance collector object.
1472	</desc>
1473	</attribute>
1474
1475	<attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1476	<desc>
1477	dhcp server settings.
1478	</desc>
1479	</attribute>
1480
1481	<attribute name="eventSource" type="IEventSource" readonly="yes">
1482	<desc>
1483	Event source for VirtualBox events.
1484	</desc>
1485	</attribute>
1486
1487
1488	<method name="createMachine">
1489	<desc>
1490	Creates a new virtual machine.
1491
1492	The new machine is created unregistered, with the initial configuration
1493	set according to the specified guest OS type. A typical sequence of
1494	actions to create a new virtual machine is as follows:
1495
1496	<ol>
1497	<li>
1498	Call this method to have a new machine created. The returned machine
1499	object will be "mutable" allowing to change any machine property.
1500	</li>
1501
1502	<li>
1503	Configure the machine using the appropriate attributes and methods.
1504	</li>
1505
1506	<li>
1507	Call <link to="IMachine::saveSettings" /> to write the settings
1508	to the machine's XML settings file. The configuration of the newly
1509	created machine will not be saved to disk until this method is
1510	called.
1511	</li>
1512
1513	<li>
1514	Call <link to="#registerMachine" /> to add the machine to the list
1515	of machines known to VirtualBox.
1516	</li>
1517	</ol>
1518
1519	You should specify valid name for the newly created machine when calling
1520	this method. See the <link to="IMachine::name"/> attribute description
1521	for more details about the machine name.
1522
1523	The specified guest OS type identifier must match an ID of one of known
1524	guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1525	array.
1526
1527	Every machine has a <i>settings file</i> that is used to store
1528	the machine configuration. This file is stored in a directory called the
1529	<i>machine settings subfolder</i>. Both the settings subfolder and file
1530	will have a name that corresponds to the name of the virtual machine.
1531	You can specify where to create the machine setting subfolder using the
1532	@a baseFolder argument. The base folder can be absolute (full path) or
1533	relative to the <link to="IVirtualBox::homeFolder">VirtualBox home
1534	directory</link>.
1535
1536	If @a baseFolder is a @c null or empty string (which is recommended), the
1537	<link to="ISystemProperties::defaultMachineFolder">default machine
1538	settings folder</link> will be used as a base folder for the created
1539	machine. Otherwise the given base folder will be used. In either case,
1540	the full path to the resulting settings file has the following
1541	structure:
1542	<pre>
1543	<base_folder>/<machine_name>/<machine_name>.xml
1544	</pre>
1545
1546	Note that if the resulting settings file already exists, this method
1547	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1548
1549	Optionally, you may specify an UUID of to assign to the created machine.
1550	However, this is not recommended and you should normally pass an empty
1551	(@c null) UUID to this method so that a new UUID will be automatically
1552	generated for every created machine. You can use UUID
1553	00000000-0000-0000-0000-000000000000 as @c null value.
1554
1555	<note>
1556	There is no way to change the name of the settings file or
1557	subfolder of the created machine directly.
1558	</note>
1559
1560	<result name="VBOX_E_OBJECT_NOT_FOUND">
1561	@a osTypeId is invalid.
1562	</result>
1563	<result name="VBOX_E_FILE_ERROR">
1564	Resulting settings file name is invalid or the settings file already
1565	exists or could not be created due to an I/O error.
1566	</result>
1567	<result name="E_INVALIDARG">
1568	@a name is empty or @c null.
1569	</result>
1570	</desc>
1571
1572	<param name="name" type="wstring" dir="in">
1573	<desc>Machine name.</desc>
1574	</param>
1575	<param name="osTypeId" type="wstring" dir="in">
1576	<desc>Guest OS Type ID.</desc>
1577	</param>
1578	<param name="baseFolder" type="wstring" dir="in">
1579	<desc>Base machine folder (optional).</desc>
1580	</param>
1581	<param name="id" type="uuid" mod="string" dir="in">
1582	<desc>Machine UUID (optional).</desc>
1583	</param>
1584	<param name="override" type="boolean" dir="in">
1585	<desc>Create the VM even if there are conflicting files.</desc>
1586	</param>
1587	<param name="machine" type="IMachine" dir="return">
1588	<desc>Created machine object.</desc>
1589	</param>
1590	</method>
1591
1592	<method name="createLegacyMachine">
1593	<desc>
1594	Creates a new virtual machine in "legacy" mode, using the specified
1595	settings file to store machine settings.
1596
1597	As opposed to machines created by <link to="#createMachine"/>,
1598	the settings file of the machine created in "legacy" mode is not
1599	automatically renamed when the machine name is changed -- it will always
1600	remain the same as specified in this method call.
1601
1602	The specified settings file name can be absolute (full path) or relative
1603	to the <link to="IVirtualBox::homeFolder">VirtualBox home
1604	directory</link>. If the file name doesn't contain an extension, the
1605	default extension (.xml) will be appended.
1606
1607	Note that the configuration of the newly created machine is not
1608	saved to disk (and therefore no settings file is created)
1609	until <link to="IMachine::saveSettings"/> is called. If the
1610	specified settings file already exists, this method
1611	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1612
1613	See <link to="#createMachine"/> for more information.
1614
1615	@deprecated This method may be removed later. Use <link
1616	to="IVirtualBox::createMachine"/> instead.
1617
1618	<note>
1619	There is no way to change the name of the settings file
1620	of the machine created in "legacy" mode.
1621	</note>
1622
1623	<result name="VBOX_E_OBJECT_NOT_FOUND">
1624	@a osTypeId is invalid.
1625	</result>
1626	<result name="VBOX_E_FILE_ERROR">
1627	@a settingsFile is invalid or the settings file already exists or
1628	could not be created due to an I/O error.
1629	</result>
1630	<result name="E_INVALIDARG">
1631	@a name or @a settingsFile is empty or @c null.
1632	</result>
1633	</desc>
1634
1635	<param name="name" type="wstring" dir="in">
1636	<desc>Machine name.</desc>
1637	</param>
1638	<param name="osTypeId" type="wstring" dir="in">
1639	<desc>Machine OS Type ID.</desc>
1640	</param>
1641	<param name="settingsFile" type="wstring" dir="in">
1642	<desc>Name of the machine settings file.</desc>
1643	</param>
1644	<param name="id" type="uuid" mod="string" dir="in">
1645	<desc>Machine UUID (optional).</desc>
1646	</param>
1647	<param name="machine" type="IMachine" dir="return">
1648	<desc>Created machine object.</desc>
1649	</param>
1650	</method>
1651
1652	<method name="openMachine">
1653	<desc>
1654	Opens a virtual machine from the existing settings file.
1655	The opened machine remains unregistered until you call
1656	<link to="#registerMachine"/>.
1657
1658	The specified settings file name can be absolute
1659	(full path) or relative to the <link to="IVirtualBox::homeFolder">
1660	VirtualBox home directory</link>. This file must exist
1661	and must be a valid machine settings file whose contents
1662	will be used to construct the machine object.
1663
1664	@deprecated Will be removed soon.
1665	<result name="VBOX_E_FILE_ERROR">
1666	Settings file name invalid, not found or sharing violation.
1667	</result>
1668	</desc>
1669	<param name="settingsFile" type="wstring" dir="in">
1670	<desc>
1671	Name of the machine settings file.
1672	</desc>
1673	</param>
1674	<param name="machine" type="IMachine" dir="return">
1675	<desc>Opened machine object.</desc>
1676	</param>
1677	<note>
1678	<link to="IMachine::settingsModified"/> will return
1679	@c false for the created machine, until any of machine settings
1680	are changed.
1681	</note>
1682	</method>
1683
1684	<method name="registerMachine">
1685	<desc>
1686
1687	Registers the machine previously created using
1688	<link to="#createMachine"/> or opened using
1689	<link to="#openMachine"/> within this VirtualBox installation. After
1690	successful method invocation, the
1691	<link to="IMachineRegisteredEvent"/> event is fired.
1692
1693	<note>
1694	This method implicitly calls <link to="IMachine::saveSettings"/>
1695	to save all current machine settings before registering it.
1696	</note>
1697
1698	<result name="VBOX_E_OBJECT_NOT_FOUND">
1699	No matching virtual machine found.
1700	</result>
1701	<result name="VBOX_E_INVALID_OBJECT_STATE">
1702	Virtual machine was not created within this VirtualBox instance.
1703	</result>
1704
1705	</desc>
1706	<param name="machine" type="IMachine" dir="in"/>
1707	</method>
1708
1709	<method name="getMachine">
1710	<desc>
1711	Attempts to find a virtual machine given its UUID.
1712	To look up a machine by name, use <link to="IVirtualBox::findMachine" />
1713	instead.
1714
1715	<result name="VBOX_E_OBJECT_NOT_FOUND">
1716	Could not find registered machine matching @a id.
1717	</result>
1718
1719	</desc>
1720	<param name="id" type="uuid" mod="string" dir="in"/>
1721	<param name="machine" type="IMachine" dir="return"/>
1722	</method>
1723
1724	<method name="findMachine">
1725	<desc>
1726	Attempts to find a virtual machine given its name.
1727	To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
1728	instead.
1729
1730	<result name="VBOX_E_OBJECT_NOT_FOUND">
1731	Could not find registered machine matching @a name.
1732	</result>
1733
1734	</desc>
1735	<param name="name" type="wstring" dir="in"/>
1736	<param name="machine" type="IMachine" dir="return"/>
1737	</method>
1738
1739	<method name="createAppliance">
1740	<desc>
1741	Creates a new appliance object, which represents an appliance in the Open Virtual Machine
1742	Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
1743	machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
1744	</desc>
1745	<param name="appliance" type="IAppliance" dir="return">
1746	<desc>New appliance.</desc>
1747	</param>
1748	</method>
1749
1750	<method name="createHardDisk">
1751	<desc>
1752	Creates a new base medium object that will use the given storage
1753	format and location for medium data.
1754
1755	Note that the actual storage unit is not created by this method. In
1756	order to do it, and before you are able to attach the created medium
1757	to virtual machines, you must call one of the following methods to
1758	allocate a format-specific storage unit at the specified location:
1759	<ul>
1760	<li><link to="IMedium::createBaseStorage"/></li>
1761	<li><link to="IMedium::createDiffStorage"/></li>
1762	</ul>
1763
1764	Some medium attributes, such as <link to="IMedium::id"/>, may
1765	remain uninitialized until the medium storage unit is successfully
1766	created by one of the above methods.
1767
1768	After the storage unit is successfully created, the medium gets
1769	remembered by this VirtualBox installation and will be accessible
1770	through the <link to="#findMedium"/> method. Remembered base medium
1771	are also returned as part of the <link to="#hardDisks"/> array.
1772	See <link to="IMedium" /> for more details.
1773
1774	The list of all storage formats supported by this VirtualBox
1775	installation can be obtained using
1776	<link to="ISystemProperties::mediumFormats"/>. If the @a format
1777	attribute is empty or @c null then the default storage format
1778	specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
1779	be used for creating a storage unit of the medium.
1780
1781	Note that the format of the location string is storage format specific.
1782	See <link to="IMedium::location"/>, IMedium and
1783	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1784
1785	<result name="VBOX_E_OBJECT_NOT_FOUND">
1786	@a format identifier is invalid. See
1787	<link to="ISystemProperties::mediumFormats"/>.
1788	</result>
1789	<result name="VBOX_E_FILE_ERROR">
1790	@a location is a not valid file name (for file-based formats only).
1791	</result>
1792	</desc>
1793	<param name="format" type="wstring" dir="in">
1794	<desc>
1795	Identifier of the storage format to use for the new medium.
1796	</desc>
1797	</param>
1798	<param name="location" type="wstring" dir="in">
1799	<desc>
1800	Location of the storage unit for the new medium.
1801	</desc>
1802	</param>
1803	<param name="medium" type="IMedium" dir="return">
1804	<desc>Created medium object.</desc>
1805	</param>
1806	</method>
1807
1808	<method name="openMedium">
1809	<desc>
1810	Opens a medium from an existing storage location.
1811
1812	Once a medium has been opened, VirtualBox saves the medium in a media
1813	registry. Prior to VirtualBox 3.3, this registry had to be the global
1814	media registry in the VirtualBox.xml file, which was shared between
1815	all machines and made transporting machines from one host to another
1816	difficult. Now you can optionally specify an <link to="IMachine" />
1817	instance, in which case the medium will be remembered in that machine's
1818	registry. This is the recommended procedure for machines created with
1819	VirtualBox 3.3 or later. <i>(not yet implemented)</i>
1820
1821	Depending on the given device type, the file at the storage location
1822	must be in one of the media formats understood by VirtualBox:
1823
1824	<ul>
1825	<li>With a "HardDisk" device type, the file must be a hard disk image
1826	in one of the formats supported by VirtualBox (see
1827	<link to="ISystemProperties::mediumFormats" />).
1828	After this method succeeds, if the medium is a base medium, it
1829	will be added to the <link to="#hardDisks"/> array attribute. </li>
1830	<li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image.
1831	After this method succeeds, the medium will be added to the
1832	<link to="#DVDImages"/> array attribute.</li>
1833	<li>With a "Floppy" device type, the file must be an RAW floppy image.
1834	After this method succeeds, the medium will be added to the
1835	<link to="#floppyImages"/> array attribute.</li>
1836	</ul>
1837
1838	After having been opened, the medium can be found by the <link to="#findMedium"/>
1839	method and can be attached to virtual machines. See <link to="IMedium" /> for more details.
1840
1841	The UUID of the newly opened medium will either be retrieved from the
1842	storage location, if the format supports it (e.g. for hard disk images),
1843	or a new UUID will be randomly generated (e.g. for ISO and RAW files).
1844	If for some reason you need to change the medium's UUID, use
1845	<link to="IMedium::setIDs" />.
1846
1847	If a differencing hard disk medium is to be opened by this method, the
1848	operation will succeed only if its parent medium and all ancestors,
1849	if any, are already known to this VirtualBox installation (for example,
1850	were opened by this method before).
1851
1852	This method attempts to guess the storage format of the specified medium
1853	by reading medium data at the specified location.
1854
1855	If @a accessMode is ReadWrite (which it should be for hard disks and floppies),
1856	the image is opened for read/write access and must have according permissions,
1857	as VirtualBox may actually write status information into the disk's metadata
1858	sections.
1859
1860	Note that write access is required for all typical hard disk usage in VirtualBox,
1861	since VirtualBox may need to write metadata such as a UUID into the image.
1862	The only exception is opening a source image temporarily for copying and
1863	cloning (see <link to="IMedium::cloneTo" /> when the image will be closed
1864	again soon.
1865
1866	The format of the location string is storage format specific. See
1867	<link to="IMedium::location"/>, IMedium and
1868	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1869
1870	<result name="VBOX_E_FILE_ERROR">
1871	Invalid medium storage file location or could not find the medium
1872	at the specified location.
1873	</result>
1874	<result name="VBOX_E_IPRT_ERROR">
1875	Could not get medium storage format.
1876	</result>
1877	<result name="E_INVALIDARG">
1878	Invalid medium storage format.
1879	</result>
1880	<result name="VBOX_E_INVALID_OBJECT_STATE">
1881	Medium has already been added to a media registry.
1882	</result>
1883	</desc>
1884	<param name="location" type="wstring" dir="in">
1885	<desc>
1886	Location of the storage unit that contains medium data in one of
1887	the supported storage formats.
1888	</desc>
1889	</param>
1890	<param name="deviceType" type="DeviceType" dir="in">
1891	<desc>
1892	Must be one of "HardDisk", "DVD" or "Floppy".
1893	</desc>
1894	</param>
1895	<param name="accessMode" type="AccessMode" dir="in">
1896	<desc>Whether to open the image in read/write or read-only mode. For
1897	a "DVD" device type, this is ignored and read-only mode is always assumed.</desc>
1898	</param>
1899	<param name="medium" type="IMedium" dir="return">
1900	<desc>Opened medium object.</desc>
1901	</param>
1902	</method>
1903
1904	<method name="findMedium">
1905	<desc>
1906	Returns a medium of the given type that uses the given location or
1907	UUID to store medium data.
1908
1909	The given medium must be known to this VirtualBox installation, i.e.
1910	it must be previously created by <link to="#createHardDisk"/> or opened
1911	by <link to="#openMedium"/>.
1912
1913	The search is done by comparing the value of the @a location argument to
1914	the <link to="IMedium::location"/> and <link to="IMedium::id" />
1915	attributes of each known medium.
1916
1917	For locations represented by file names in the host's file system, the
1918	requested location can be a path relative to the
1919	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
1920	only a file name without any path is given, the
1921	<link to="ISystemProperties::defaultHardDiskFolder"> default medium
1922	folder</link> will be prepended to the file name before searching. Note
1923	that on case sensitive file systems, a case sensitive comparison is
1924	performed, otherwise the case of symbols in the file path is ignored.
1925
1926	<result name="VBOX_E_OBJECT_NOT_FOUND">
1927	No medium object matching @a location found.
1928	</result>
1929	</desc>
1930	<param name="location" type="wstring" dir="in">
1931	<desc>What to search for. This can either be the UUID or the location string of an open medium.</desc>
1932	</param>
1933	<param name="type" type="DeviceType" dir="in">
1934	<desc>Device type (must be HardDisk, DVD or Floppy)</desc>
1935	</param>
1936	<param name="medium" type="IMedium" dir="return">
1937	<desc>Medium object, if found.</desc>
1938	</param>
1939	</method>
1940
1941	<method name="getGuestOSType">
1942	<desc>
1943	Returns an object describing the specified guest OS type.
1944
1945	The requested guest OS type is specified using a string which is a
1946	mnemonic identifier of the guest operating system, such as
1947	<tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
1948	particular virtual machine can be read or set using the
1949	<link to="IMachine::OSTypeId"/> attribute.
1950
1951	The <link to="IVirtualBox::guestOSTypes"/> collection contains all
1952	available guest OS type objects. Each object has an
1953	<link to="IGuestOSType::id"/> attribute which contains an identifier of
1954	the guest OS this object describes.
1955
1956	<result name="E_INVALIDARG">
1957	@a id is not a valid Guest OS type.
1958	</result>
1959
1960	</desc>
1961	<param name="id" type="uuid" mod="string" dir="in">
1962	<desc>Guest OS type ID string.</desc>
1963	</param>
1964	<param name="type" type="IGuestOSType" dir="return">
1965	<desc>Guest OS type object.</desc>
1966	</param>
1967	</method>
1968
1969	<method name="createSharedFolder">
1970	<desc>
1971	Creates a new global shared folder by associating the given logical
1972	name with the given host path, adds it to the collection of shared
1973	folders and starts sharing it. Refer to the description of
1974	<link to="ISharedFolder"/> to read more about logical names.
1975	<note>
1976	In the current implementation, this operation is not
1977	implemented.
1978	</note>
1979	</desc>
1980	<param name="name" type="wstring" dir="in">
1981	<desc>Unique logical name of the shared folder.</desc>
1982	</param>
1983	<param name="hostPath" type="wstring" dir="in">
1984	<desc>Full path to the shared folder in the host file system.</desc>
1985	</param>
1986	<param name="writable" type="boolean" dir="in">
1987	<desc>Whether the share is writable or readonly</desc>
1988	</param>
1989	<param name="automount" type="boolean" dir="in">
1990	<desc>Whether the share gets automatically mounted by the guest
1991	or not.</desc>
1992	</param>
1993	</method>
1994
1995	<method name="removeSharedFolder">
1996	<desc>
1997	Removes the global shared folder with the given name previously
1998	created by <link to="#createSharedFolder"/> from the collection of
1999	shared folders and stops sharing it.
2000	<note>
2001	In the current implementation, this operation is not
2002	implemented.
2003	</note>
2004	</desc>
2005	<param name="name" type="wstring" dir="in">
2006	<desc>Logical name of the shared folder to remove.</desc>
2007	</param>
2008	</method>
2009
2010	<method name="getExtraDataKeys">
2011	<desc>
2012	Returns an array representing the global extra data keys which currently
2013	have values defined.
2014	</desc>
2015	<param name="value" type="wstring" dir="return" safearray="yes">
2016	<desc>Array of extra data keys.</desc>
2017	</param>
2018	</method>
2019
2020	<method name="getExtraData">
2021	<desc>
2022	Returns associated global extra data.
2023
2024	If the requested data @a key does not exist, this function will
2025	succeed and return an empty string in the @a value argument.
2026
2027	<result name="VBOX_E_FILE_ERROR">
2028	Settings file not accessible.
2029	</result>
2030	<result name="VBOX_E_XML_ERROR">
2031	Could not parse the settings file.
2032	</result>
2033
2034	</desc>
2035	<param name="key" type="wstring" dir="in">
2036	<desc>Name of the data key to get.</desc>
2037	</param>
2038	<param name="value" type="wstring" dir="return">
2039	<desc>Value of the requested data key.</desc>
2040	</param>
2041	</method>
2042
2043	<method name="setExtraData">
2044	<desc>
2045	Sets associated global extra data.
2046
2047	If you pass @c null or empty string as a key @a value, the given @a key
2048	will be deleted.
2049
2050	<note>
2051	Before performing the actual data change, this method will ask all
2052	registered event listener using the
2053	<link to="IExtraDataCanChangeEvent"/>
2054	notification for a permission. If one of the listeners refuses the
2055	new value, the change will not be performed.
2056	</note>
2057	<note>
2058	On success, the
2059	<link to="IExtraDataChangedEvent"/> notification
2060	is called to inform all registered listeners about a successful data
2061	change.
2062	</note>
2063
2064	<result name="VBOX_E_FILE_ERROR">
2065	Settings file not accessible.
2066	</result>
2067	<result name="VBOX_E_XML_ERROR">
2068	Could not parse the settings file.
2069	</result>
2070	<result name="E_ACCESSDENIED">
2071	Modification request refused.
2072	</result>
2073
2074	</desc>
2075	<param name="key" type="wstring" dir="in">
2076	<desc>Name of the data key to set.</desc>
2077	</param>
2078	<param name="value" type="wstring" dir="in">
2079	<desc>Value to assign to the key.</desc>
2080	</param>
2081	</method>
2082
2083	<method name="waitForPropertyChange">
2084	<desc>
2085	Blocks the caller until any of the properties represented by the
2086	@a what argument changes the value or until the given timeout interval
2087	expires.
2088
2089	The @a what argument is a comma separated list of property masks that
2090	describe properties the caller is interested in. The property mask is
2091	a string in the following format:
2092
2093	<pre>
2094	[[group.]subgroup.]name
2095	</pre>
2096
2097	where @c name is the property name and @c group, @c subgroup are zero
2098	or more property group specifiers. Each element (group or name) in
2099	the property mask may be either a Latin string or an asterisk symbol
2100	(@c "*") which is used to match any string for the given element. A
2101	property mask that doesn't contain asterisk symbols represents a
2102	single fully qualified property name.
2103
2104	Groups in the fully qualified property name go from more generic (the
2105	left-most part) to more specific (the right-most part). The first
2106	element is usually a name of the object the property belongs to. The
2107	second element may be either a property name, or a child object name,
2108	or an index if the preceding element names an object which is one of
2109	many objects of the same type. This way, property names form a
2110	hierarchy of properties. Here are some examples of property names:
2111
2112	<table>
2113	<tr>
2114	<td><tt>VirtualBox.version</tt></td>
2115	<td><link to="IVirtualBox::version"/> property</td>
2116	</tr>
2117	<tr>
2118	<td><tt>Machine.<UUID>.name</tt></td>
2119	<td><link to="IMachine::name"/> property of the machine with the
2120	given UUID</td>
2121	</tr>
2122	</table>
2123
2124	Most property names directly correspond to the properties of objects
2125	(components) provided by the VirtualBox library and may be used to
2126	track changes to these properties. However, there may be
2127	pseudo-property names that don't correspond to any existing object's
2128	property directly, as well as there may be object properties that
2129	don't have a corresponding property name that is understood by this
2130	method, and therefore changes to such properties cannot be
2131	tracked. See individual object's property descriptions to get a
2132	fully qualified property name that can be used with this method (if
2133	any).
2134
2135	There is a special property mask @c "*" (i.e. a string consisting of a
2136	single asterisk symbol) that can be used to match all properties.
2137	Below are more examples of property masks:
2138
2139	<table>
2140	<tr>
2141	<td><tt>VirtualBox.*</tt></td>
2142	<td>Track all properties of the VirtualBox object</td>
2143	</tr>
2144	<tr>
2145	<td><tt>Machine.*.name</tt></td>
2146	<td>Track changes to the <link to="IMachine::name"/> property of
2147	all registered virtual machines</td>
2148	</tr>
2149	</table>
2150
2151	<note>
2152	This function is not implemented in the current version of the
2153	product.
2154	</note>
2155	</desc>
2156	<param name="what" type="wstring" dir="in">
2157	<desc>Comma separated list of property masks.</desc>
2158	</param>
2159	<param name="timeout" type="unsigned long" dir="in">
2160	<desc>
2161	Wait timeout in milliseconds.
2162	Specify -1 for an indefinite wait.
2163	</desc>
2164	</param>
2165	<param name="changed" type="wstring" dir="out">
2166	<desc>
2167	Comma separated list of properties that have been changed and caused
2168	this method to return to the caller.
2169	</desc>
2170	</param>
2171	<param name="values" type="wstring" dir="out">
2172	<desc>Reserved, not currently used.</desc>
2173	</param>
2174	</method>
2175
2176	<!--method name="createDHCPServerForInterface">
2177	<desc>
2178	Creates a dhcp server settings to be used for the given interface
2179	<result name="E_INVALIDARG">
2180	Host network interface @a name already exists.
2181	</result>
2182	</desc>
2183	<param name="interface" type="IHostNetworkInterface" dir="in">
2184	<desc>Network Interface</desc>
2185	</param>
2186	<param name="server" type="IDHCPServer" dir="out">
2187	<desc>Dhcp server settings</desc>
2188	</param>
2189	</method-->
2190
2191	<method name="createDHCPServer">
2192	<desc>
2193	Creates a dhcp server settings to be used for the given internal network name
2194	<result name="E_INVALIDARG">
2195	Host network interface @a name already exists.
2196	</result>
2197	</desc>
2198	<param name="name" type="wstring" dir="in">
2199	<desc>server name</desc>
2200	</param>
2201	<param name="server" type="IDHCPServer" dir="return">
2202	<desc>Dhcp server settings</desc>
2203	</param>
2204	</method>
2205
2206	<method name="findDHCPServerByNetworkName">
2207	<desc>
2208	Searches a dhcp server settings to be used for the given internal network name
2209	<result name="E_INVALIDARG">
2210	Host network interface @a name already exists.
2211	</result>
2212
2213	</desc>
2214	<param name="name" type="wstring" dir="in">
2215	<desc>server name</desc>
2216	</param>
2217	<param name="server" type="IDHCPServer" dir="return">
2218	<desc>Dhcp server settings</desc>
2219	</param>
2220	</method>
2221
2222	<!--method name="findDHCPServerForInterface">
2223	<desc>
2224	Searches a dhcp server settings to be used for the given interface
2225	<result name="E_INVALIDARG">
2226	Host network interface @a name already exists.
2227	</result>
2228	</desc>
2229	<param name="interface" type="IHostNetworkInterface" dir="in">
2230	<desc>Network Interface</desc>
2231	</param>
2232	<param name="server" type="IDHCPServer" dir="out">
2233	<desc>Dhcp server settings</desc>
2234	</param>
2235	</method-->
2236
2237	<method name="removeDHCPServer">
2238	<desc>
2239	Removes the dhcp server settings
2240	<result name="E_INVALIDARG">
2241	Host network interface @a name already exists.
2242	</result>
2243	</desc>
2244	<param name="server" type="IDHCPServer" dir="in">
2245	<desc>Dhcp server settings to be removed</desc>
2246	</param>
2247	</method>
2248
2249
2250	<method name="checkFirmwarePresent">
2251	<desc>
2252	Check if this VirtualBox installation has a firmware
2253	of the given type available, either system-wide or per-user.
2254	Optionally, this may return a hint where this firmware can be
2255	downloaded from.
2256	</desc>
2257	<param name="firmwareType" type="FirmwareType" dir="in">
2258	<desc>
2259	Type of firmware to check.
2260	</desc>
2261	</param>
2262	<param name="version" type="wstring" dir="in">
2263	<desc>Expected version number, usually empty string (presently ignored).</desc>
2264	</param>
2265
2266	<param name="url" type="wstring" dir="out">
2267	<desc>
2268	Suggested URL to download this firmware from.
2269	</desc>
2270	</param>
2271
2272	<param name="file" type="wstring" dir="out">
2273	<desc>
2274	Filename of firmware, only valid if result == TRUE.
2275	</desc>
2276	</param>
2277
2278	<param name="result" type="boolean" dir="return">
2279	<desc>If firmware of this type and version is available.</desc>
2280	</param>
2281	</method>
2282
2283	</interface>
2284
2285	<!--
2286	// IVFSExplorer
2287	/////////////////////////////////////////////////////////////////////////
2288	-->
2289
2290	<enum
2291	name="VFSType"
2292	uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
2293	>
2294	<desc>
2295	Virtual file systems supported by VFSExplorer.
2296	</desc>
2297
2298	<const name="File" value="1" />
2299	<const name="Cloud" value="2" />
2300	<const name="S3" value="3" />
2301	<const name="WebDav" value="4" />
2302	</enum>
2303
2304	<enum
2305	name="VFSFileType"
2306	uuid="714333cd-44e2-415f-a245-d378fa9b1242"
2307	>
2308	<desc>
2309	File types known by VFSExplorer.
2310	</desc>
2311
2312	<const name="Unknown" value="1" />
2313	<const name="Fifo" value="2" />
2314	<const name="DevChar" value="3" />
2315	<const name="Directory" value="4" />
2316	<const name="DevBlock" value="5" />
2317	<const name="File" value="6" />
2318	<const name="SymLink" value="7" />
2319	<const name="Socket" value="8" />
2320	<const name="WhiteOut" value="9" />
2321	</enum>
2322
2323	<interface
2324	name="IVFSExplorer" extends="$unknown"
2325	uuid="2bb864a1-02a3-4474-a1d4-fb5f23b742e1"
2326	wsmap="managed"
2327	>
2328	<desc>
2329	The VFSExplorer interface unifies access to different file system
2330	types. This includes local file systems as well remote file systems like
2331	S3. For a list of supported types see <link to="VFSType" />.
2332	An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
2333	</desc>
2334
2335	<attribute name="path" type="wstring" readonly="yes">
2336	<desc>Returns the current path in the virtual file system.</desc>
2337	</attribute>
2338
2339	<attribute name="type" type="VFSType" readonly="yes">
2340	<desc>Returns the file system type which is currently in use.</desc>
2341	</attribute>
2342
2343	<method name="update">
2344	<desc>Updates the internal list of files/directories from the
2345	current directory level. Use <link to="#entryList" /> to get the full list
2346	after a call to this method.</desc>
2347
2348	<param name="aProgress" type="IProgress" dir="return">
2349	<desc>Progress object to track the operation completion.</desc>
2350	</param>
2351	</method>
2352
2353	<method name="cd">
2354	<desc>Change the current directory level.</desc>
2355
2356	<param name="aDir" type="wstring" dir="in">
2357	<desc>The name of the directory to go in.</desc>
2358	</param>
2359
2360	<param name="aProgress" type="IProgress" dir="return">
2361	<desc>Progress object to track the operation completion.</desc>
2362	</param>
2363	</method>
2364
2365	<method name="cdUp">
2366	<desc>Go one directory upwards from the current directory level.</desc>
2367
2368	<param name="aProgress" type="IProgress" dir="return">
2369	<desc>Progress object to track the operation completion.</desc>
2370	</param>
2371	</method>
2372
2373	<method name="entryList">
2374	<desc>Returns a list of files/directories after a call to <link
2375	to="#update" />. The user is responsible for keeping this internal
2376	list up do date.</desc>
2377
2378	<param name="aNames" type="wstring" safearray="yes" dir="out">
2379	<desc>The list of names for the entries.</desc>
2380	</param>
2381
2382	<param name="aTypes" type="unsigned long" safearray="yes" dir="out">
2383	<desc>The list of types for the entries.</desc>
2384	</param>
2385	</method>
2386
2387	<method name="exists">
2388	<desc>Checks if the given file list exists in the current directory
2389	level.</desc>
2390
2391	<param name="aNames" type="wstring" safearray="yes" dir="in">
2392	<desc>The names to check.</desc>
2393	</param>
2394
2395	<param name="aExists" type="wstring" safearray="yes" dir="return">
2396	<desc>The names which exist.</desc>
2397	</param>
2398	</method>
2399
2400	<method name="remove">
2401	<desc>Deletes the given files in the current directory level.</desc>
2402
2403	<param name="aNames" type="wstring" safearray="yes" dir="in">
2404	<desc>The names to remove.</desc>
2405	</param>
2406
2407	<param name="aProgress" type="IProgress" dir="return">
2408	<desc>Progress object to track the operation completion.</desc>
2409	</param>
2410	</method>
2411
2412	</interface>
2413
2414	<!--
2415	// IAppliance
2416	/////////////////////////////////////////////////////////////////////////
2417	-->
2418
2419	<interface
2420	name="IAppliance" extends="$unknown"
2421	uuid="fb61a4fc-57e7-48d6-859b-71f37d484cf2"
2422	wsmap="managed"
2423	>
2424	<desc>
2425	Represents a platform-independent appliance in OVF format. An instance of this is returned
2426	by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
2427	virtual machines within an appliance with VirtualBox.
2428
2429	The OVF standard suggests two different physical file formats:
2430
2431	<ol>
2432	<li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
2433	file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
2434	this descriptor file references other files such as disk images, as OVF appliances typically
2435	do, those additional files must be in the same directory as the descriptor file.</li>
2436
2437	<li>If the appliance is distributed as a single file, it must be in TAR format and have the
2438	<tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
2439	files and optionally other files.
2440
2441	At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
2442	be added with a later version.</li>
2443	</ol>
2444
2445	<b>Importing</b> an OVF appliance into VirtualBox as instances of
2446	<link to="IMachine" /> involves the following sequence of API calls:
2447
2448	<ol>
2449	<li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
2450	</li>
2451
2452	<li>On the new object, call <link to="#read" /> with the full path of the OVF file you
2453	would like to import. So long as this file is syntactically valid, this will succeed
2454	and fill the appliance object with the parsed data from the OVF file.
2455	</li>
2456
2457	<li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
2458	contents of the IAppliance attributes accordingly. These can be inspected by a
2459	VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
2460	user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
2461	instances of <link to="IVirtualSystemDescription" /> which represent the virtual
2462	systems (machines) in the OVF, which in turn describe the virtual hardware prescribed
2463	by the OVF (network and hardware adapters, virtual disk images, memory size and so on).
2464	The GUI can then give the user the option to confirm and/or change these suggestions.
2465	</li>
2466
2467	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
2468	virtual system (machine) to override the suggestions made by the interpret() routine.
2469	</li>
2470
2471	<li>Finally, call <link to="#importMachines" /> to create virtual machines in
2472	VirtualBox as instances of <link to="IMachine" /> that match the information in the
2473	virtual system descriptions. After this call suceeded, the UUIDs of the machines created
2474	can be found in the <link to="#machines" /> array attribute.
2475	</li>
2476	</ol>
2477
2478	<b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
2479
2480	<ol>
2481	<li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
2482	an empty IAppliance object.
2483	</li>
2484
2485	<li>For each machine you would like to export, call <link to="IMachine::export" />
2486	with the IAppliance object you just created. Each such call creates one instance of
2487	<link to="IVirtualSystemDescription" /> inside the appliance.
2488	</li>
2489
2490	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
2491	virtual system (machine) to override the suggestions made by the export() routine.
2492	</li>
2493
2494	<li>Finally, call <link to="#write" /> with a path specification to have the OVF
2495	file written.</li>
2496	</ol>
2497
2498	</desc>
2499
2500	<attribute name="path" type="wstring" readonly="yes">
2501	<desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
2502	the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
2503	<link to="#write" /> (for export).
2504	This attribute is empty until one of these methods has been called.
2505	</desc>
2506	</attribute>
2507
2508	<attribute name="disks" type="wstring" readonly="yes" safearray="yes">
2509	<desc>
2510	Array of virtual disk definitions. One such description exists for each
2511	disk definition in the OVF; each string array item represents one such piece of
2512	disk information, with the information fields separated by tab (\t) characters.
2513
2514	The caller should be prepared for additional fields being appended to
2515	this string in future versions of VirtualBox and therefore check for
2516	the number of tabs in the strings returned.
2517
2518	In the current version, the following eight fields are returned per string
2519	in the array:
2520
2521	<ol>
2522	<li>Disk ID (unique string identifier given to disk)</li>
2523
2524	<li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
2525
2526	<li>Populated size (optional unsigned integer indicating the current size of the
2527	disk; can be approximate; -1 if unspecified)</li>
2528
2529	<li>Format (string identifying the disk format, typically
2530	"http://www.vmware.com/specifications/vmdk.html#sparse")</li>
2531
2532	<li>Reference (where to find the disk image, typically a file name; if empty,
2533	then the disk should be created on import)</li>
2534
2535	<li>Image size (optional unsigned integer indicating the size of the image,
2536	which need not necessarily be the same as the values specified above, since
2537	the image may be compressed or sparse; -1 if not specified)</li>
2538
2539	<li>Chunk size (optional unsigned integer if the image is split into chunks;
2540	presently unsupported and always -1)</li>
2541
2542	<li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
2543	</ol>
2544	</desc>
2545	</attribute>
2546
2547	<attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
2548	<desc> Array of virtual system descriptions. One such description is created
2549	for each virtual system (machine) found in the OVF.
2550	This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
2551	(for export) has been called.
2552	</desc>
2553	</attribute>
2554
2555	<attribute name="machines" type="wstring" readonly="yes" safearray="yes">
2556	<desc>
2557	Contains the UUIDs of the machines created from the information in this appliances. This is only
2558	relevant for the import case, and will only contain data after a call to <link to="#importMachines" />
2559	succeeded.
2560	</desc>
2561	</attribute>
2562
2563	<method name="read">
2564	<desc>
2565	Reads an OVF file into the appliance object.
2566
2567	This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
2568	mere fact that this method returns successfully does not mean that VirtualBox supports all
2569	features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
2570	</desc>
2571	<param name="file" type="wstring" dir="in">
2572	<desc>
2573	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
2574	on whether the appliance is distributed as a set of files or as a single file, respectively).
2575	</desc>
2576	</param>
2577	<param name="aProgress" type="IProgress" dir="return">
2578	<desc>Progress object to track the operation completion.</desc>
2579	</param>
2580	</method>
2581
2582	<method name="interpret">
2583	<desc>
2584	Interprets the OVF data that was read when the appliance was constructed. After
2585	calling this method, one can inspect the
2586	<link to="#virtualSystemDescriptions" /> array attribute, which will then contain
2587	one <link to="IVirtualSystemDescription" /> for each virtual machine found in
2588	the appliance.
2589
2590	Calling this method is the second step of importing an appliance into VirtualBox;
2591	see <link to="IAppliance" /> for an overview.
2592
2593	After calling this method, one should call <link to="#getWarnings" /> to find out
2594	if problems were encountered during the processing which might later lead to
2595	errors.
2596	</desc>
2597	</method>
2598
2599	<method name="importMachines">
2600	<desc>
2601	Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
2602	and other interfaces that match the information contained in the appliance as
2603	closely as possible, as represented by the import instructions in the
2604	<link to="#virtualSystemDescriptions" /> array.
2605
2606	Calling this method is the final step of importing an appliance into VirtualBox;
2607	see <link to="IAppliance" /> for an overview.
2608
2609	Since importing the appliance will most probably involve copying and converting
2610	disk images, which can take a long time, this method operates asynchronously and
2611	returns an IProgress object to allow the caller to monitor the progress.
2612
2613	After the import succeeded, the UUIDs of the IMachine instances created can be
2614	retrieved from the <link to="#machines" /> array attribute.
2615	</desc>
2616
2617	<param name="aProgress" type="IProgress" dir="return">
2618	<desc>Progress object to track the operation completion.</desc>
2619	</param>
2620	</method>
2621
2622	<method name="createVFSExplorer">
2623	<desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
2624
2625	<param name="aUri" type="wstring" dir="in">
2626	<desc>The URI describing the file system to use.</desc>
2627	</param>
2628
2629	<param name="aExplorer" type="IVFSExplorer" dir="return">
2630	<desc></desc>
2631	</param>
2632	</method>
2633
2634	<method name="write">
2635	<desc>
2636	Writes the contents of the appliance exports into a new OVF file.
2637
2638	Calling this method is the final step of exporting an appliance from VirtualBox;
2639	see <link to="IAppliance" /> for an overview.
2640
2641	Since exporting the appliance will most probably involve copying and converting
2642	disk images, which can take a long time, this method operates asynchronously and
2643	returns an IProgress object to allow the caller to monitor the progress.
2644	</desc>
2645	<param name="format" type="wstring" dir="in">
2646	<desc>
2647	Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
2648	future versions of VirtualBox may support additional formats.
2649	</desc>
2650	</param>
2651	<param name="path" type="wstring" dir="in">
2652	<desc>
2653	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
2654	on whether the appliance is distributed as a set of files or as a single file, respectively).
2655	</desc>
2656	</param>
2657	<param name="aProgress" type="IProgress" dir="return">
2658	<desc>Progress object to track the operation completion.</desc>
2659	</param>
2660	</method>
2661
2662	<method name="getWarnings">
2663	<desc>Returns textual warnings which occured during execution of <link to="#interpret" />.</desc>
2664
2665	<param name="aWarnings" type="wstring" dir="return" safearray="yes">
2666	<desc></desc>
2667	</param>
2668	</method>
2669
2670	</interface>
2671
2672	<enum
2673	name="VirtualSystemDescriptionType"
2674	uuid="c0f8f135-3a1d-417d-afa6-b38b95a91f90"
2675	>
2676	<desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
2677	a configuration value.</desc>
2678
2679	<const name="Ignore" value="1" />
2680	<const name="OS" value="2" />
2681	<const name="Name" value="3" />
2682	<const name="Product" value="4" />
2683	<const name="Vendor" value="5" />
2684	<const name="Version" value="6" />
2685	<const name="ProductUrl" value="7" />
2686	<const name="VendorUrl" value="8" />
2687	<const name="Description" value="9" />
2688	<const name="License" value="10" />
2689	<const name="Miscellaneous" value="11" />
2690	<const name="CPU" value="12" />
2691	<const name="Memory" value="13" />
2692	<const name="HardDiskControllerIDE" value="14" />
2693	<const name="HardDiskControllerSATA" value="15" />
2694	<const name="HardDiskControllerSCSI" value="16" />
2695	<const name="HardDiskControllerSAS" value="17" />
2696	<const name="HardDiskImage" value="18" />
2697	<const name="Floppy" value="19" />
2698	<const name="CDROM" value="20" />
2699	<const name="NetworkAdapter" value="21" />
2700	<const name="USBController" value="22" />
2701	<const name="SoundCard" value="23" />
2702
2703	</enum>
2704
2705	<enum
2706	name="VirtualSystemDescriptionValueType"
2707	uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
2708	>
2709	<desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
2710	type to fetch.</desc>
2711
2712	<const name="Reference" value="1" />
2713	<const name="Original" value="2" />
2714	<const name="Auto" value="3" />
2715	<const name="ExtraConfig" value="4" />
2716
2717	</enum>
2718
2719	<interface
2720	name="IVirtualSystemDescription" extends="$unknown"
2721	uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
2722	wsmap="managed"
2723	>
2724
2725	<desc>Represents one virtual system (machine) in an appliance. This interface is used in
2726	the <link to="IAppliance::virtualSystemDescriptions" /> array. After
2727	<link to="IAppliance::interpret" /> has been called, that array contains information
2728	about how the virtual systems described in the OVF should best be imported into
2729	VirtualBox virtual machines. See <link to="IAppliance" /> for the steps required to
2730	import an OVF into VirtualBox.
2731	</desc>
2732
2733	<attribute name="count" type="unsigned long" readonly="yes">
2734	<desc>Return the number of virtual system description entries.</desc>
2735	</attribute>
2736
2737	<method name="getDescription">
2738	<desc>Returns information about the virtual system as arrays of instruction items. In each array, the
2739	items with the same indices correspond and jointly represent an import instruction for VirtualBox.
2740
2741	The list below identifies the value sets that are possible depending on the
2742	<link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
2743	the array item with the same index in @a aOvfValues[] will contain the original value as contained
2744	in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
2745	will contain a suggested value to be used for VirtualBox. Depending on the description type,
2746	the @a aExtraConfigValues[] array item may also be used.
2747
2748	<ul>
2749	<li>
2750	"OS": the guest operating system type. There must be exactly one such array item on import. The
2751	corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
2752	This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
2753	item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF.
2754	</li>
2755	<li>
2756	"Name": the name to give to the new virtual machine. There can be at most one such array item;
2757	if none is present on import, then an automatic name will be created from the operating system
2758	type. The correponding item im @a aOvfValues[] will contain the suggested virtual machine name
2759	from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
2760	<link to="IMachine" /> name that does not exist yet.
2761	</li>
2762	<li>
2763	"Description": an arbitrary description.
2764	</li>
2765	<li>
2766	"License": the EULA section from the OVF, if present. It is the responsibility of the calling
2767	code to display such a license for agreement; the Main API does not enforce any such policy.
2768	</li>
2769	<li>
2770	Miscellaneous: reserved for future use.
2771	</li>
2772	<li>
2773	"CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
2774	</li>
2775	<li>
2776	"Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
2777	is present on import, then VirtualBox will set a meaningful default based on the operating system
2778	type.
2779	</li>
2780	<li>
2781	"HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
2782	An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
2783	the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
2784	writes into the OVF.
2785	The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
2786	type can use to specify which hard disk controller a virtual disk should be connected to.
2787	Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
2788	in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
2789	its virtual machines supports four channels (primary master, primary slave, secondary master,
2790	secondary slave) and thus maps to two IDE controllers in the OVF sense.
2791	</li>
2792	<li>
2793	"HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
2794	has no value in @a aOvfValues[] or @a aVBoxValues[].
2795	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
2796	</li>
2797	<li>
2798	"HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
2799	The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or
2800	"LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller
2801	whereas VirtualBox considers it a class of storage controllers of its own; see
2802	<link to="StorageControllerType" />).
2803	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
2804	</li>
2805	<li>
2806	"HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
2807	arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
2808
2809	The array item in @a aOvfValues[] will contain the file specification from the OVF file (without
2810	a path since the image file should be in the same location as the OVF file itself), whereas the
2811	item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
2812	hard disk image. This means that on import the image will be copied and converted from the
2813	"ovf" location to the "vbox" location; on export, this will be handled the other way round.
2814	On import, the target image will also be registered with VirtualBox.
2815
2816	The matching item in the @a aExtraConfigValues[] array must contain a string of the following
2817	format: "controller=<index>;channel=<c>"
2818	In this string, <index> must be an integer specifying the hard disk controller to connect
2819	the image to. That number must be the index of an array item with one of the hard disk controller
2820	types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
2821	In addition, <c> must specify the channel to use on that controller. For IDE controllers,
2822	this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
2823	before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
2824	no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
2825	</li>
2826	<li>
2827	"CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
2828	attachment information as with "HardDiskImage" items.
2829	</li>
2830	<li>
2831	"CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
2832	attachment information as with "HardDiskImage" items.
2833	</li>
2834	<li>
2835	"NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
2836	for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
2837	of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
2838	</li>
2839	<li>
2840	"USBController": a USB controller. There can be at most one such item. If and only if such an
2841	item ispresent, USB support will be enabled for the new virtual machine.
2842	</li>
2843	<li>
2844	"SoundCard": a sound card. There can be at most one such item. If and only if such an item is
2845	present, sound support will be enabled for the new virtual machine. Note that the virtual
2846	machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
2847	may be different from the virtual soundcard expected by the appliance.
2848	</li>
2849	</ul>
2850
2851	</desc>
2852
2853	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
2854	<desc></desc>
2855	</param>
2856
2857	<param name="aRefs" type="wstring" dir="out" safearray="yes">
2858	<desc></desc>
2859	</param>
2860
2861	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
2862	<desc></desc>
2863	</param>
2864
2865	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
2866	<desc></desc>
2867	</param>
2868
2869	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
2870	<desc></desc>
2871	</param>
2872
2873	</method>
2874
2875	<method name="getDescriptionByType">
2876	<desc>This is the same as <link to="#getDescription" /> except that you can specify which types
2877	should be returned.</desc>
2878
2879	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
2880	<desc></desc>
2881	</param>
2882
2883	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
2884	<desc></desc>
2885	</param>
2886
2887	<param name="aRefs" type="wstring" dir="out" safearray="yes">
2888	<desc></desc>
2889	</param>
2890
2891	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
2892	<desc></desc>
2893	</param>
2894
2895	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
2896	<desc></desc>
2897	</param>
2898
2899	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
2900	<desc></desc>
2901	</param>
2902
2903	</method>
2904
2905	<method name="getValuesByType">
2906	<desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
2907	value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
2908	values.</desc>
2909
2910	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
2911	<desc></desc>
2912	</param>
2913
2914	<param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
2915	<desc></desc>
2916	</param>
2917
2918	<param name="aValues" type="wstring" dir="return" safearray="yes">
2919	<desc></desc>
2920	</param>
2921
2922	</method>
2923
2924	<method name="setFinalValues">
2925	<desc>
2926	This method allows the appliance's user to change the configuration for the virtual
2927	system descriptions. For each array item returned from <link to="#getDescription" />,
2928	you must pass in one boolean value and one configuration value.
2929
2930	Each item in the boolean array determines whether the particular configuration item
2931	should be enabled.
2932	You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
2933	HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
2934	and SoundCard.
2935
2936	For the "vbox" and "extra configuration" values, if you pass in the same arrays
2937	as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription(),
2938	the configuration remains unchanged. Please see the documentation for getDescription()
2939	for valid configuration values for the individual array item types. If the
2940	corresponding item in the aEnabled array is @c false, the configuration value is ignored.
2941	</desc>
2942
2943	<param name="aEnabled" type="boolean" dir="in" safearray="yes">
2944	<desc></desc>
2945	</param>
2946
2947	<param name="aVBoxValues" type="wstring" dir="in" safearray="yes">
2948	<desc></desc>
2949	</param>
2950
2951	<param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
2952	<desc></desc>
2953	</param>
2954	</method>
2955
2956	<method name="addDescription">
2957	<desc>
2958	This method adds an additional description entry to the stack of already
2959	available descriptions for this virtual system. This is handy for writing
2960	values which aren't directly supported by VirtualBox. One example would
2961	be the License type of <link to="VirtualSystemDescriptionType" />.
2962	</desc>
2963
2964	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
2965	<desc></desc>
2966	</param>
2967
2968	<param name="aVBoxValue" type="wstring" dir="in">
2969	<desc></desc>
2970	</param>
2971
2972	<param name="aExtraConfigValue" type="wstring" dir="in">
2973	<desc></desc>
2974	</param>
2975	</method>
2976	</interface>
2977
2978
2979	<!--
2980	// IMachine
2981	/////////////////////////////////////////////////////////////////////////
2982	-->
2983
2984	<interface
2985	name="IInternalMachineControl" extends="$unknown"
2986	uuid="e2da8b1a-2ad1-490e-b29e-c33a144791b6"
2987	internal="yes"
2988	wsmap="suppress"
2989	>
2990	<method name="setRemoveSavedStateFile">
2991	<desc>
2992	Updates the flag whether the saved state file is removed on a
2993	machine state change from Saved to PoweredOff.
2994	</desc>
2995	<param name="aRemove" type="boolean" dir="in"/>
2996	</method>
2997
2998	<method name="updateState">
2999	<desc>
3000	Updates the VM state.
3001	<note>
3002	This operation will also update the settings file with the correct
3003	information about the saved state file and delete this file from disk
3004	when appropriate.
3005	</note>
3006	</desc>
3007	<param name="state" type="MachineState" dir="in"/>
3008	</method>
3009
3010	<method name="getIPCId">
3011	<param name="id" type="wstring" dir="return"/>
3012	</method>
3013
3014	<method name="beginPowerUp">
3015	<desc>
3016	Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and
3017	gives it the progress object that should be part of any pending
3018	<link to="IMachine::launchVMProcess"/> operations. The progress
3019	object may be called back to reflect an early cancelation, so some care
3020	have to be taken with respect to any cancelation callbacks. The console
3021	object will call <link to="IInternalMachineControl::endPowerUp"/>
3022	to signal the completion of the progress object.
3023	</desc>
3024	<param name="aProgress" type="IProgress" dir="in" />
3025	</method>
3026
3027	<method name="endPowerUp">
3028	<desc>
3029	Tells VBoxSVC that <link to="IConsole::powerUp"/> has completed.
3030	This method may query status information from the progress object it
3031	received in <link to="IInternalMachineControl::beginPowerUp"/> and copy
3032	it over to any in-progress <link to="IMachine::launchVMProcess"/>
3033	call in order to complete that progress object.
3034	</desc>
3035	<param name="result" type="long" dir="in"/>
3036	</method>
3037
3038	<method name="runUSBDeviceFilters">
3039	<desc>
3040	Asks the server to run USB devices filters of the associated
3041	machine against the given USB device and tell if there is
3042	a match.
3043	<note>
3044	Intended to be used only for remote USB devices. Local
3045	ones don't require to call this method (this is done
3046	implicitly by the Host and USBProxyService).
3047	</note>
3048	</desc>
3049	<param name="device" type="IUSBDevice" dir="in"/>
3050	<param name="matched" type="boolean" dir="out"/>
3051	<param name="maskedInterfaces" type="unsigned long" dir="out"/>
3052	</method>
3053
3054	<method name="captureUSBDevice">
3055	<desc>
3056	Requests a capture of the given host USB device.
3057	When the request is completed, the VM process will
3058	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3059	notification.
3060	</desc>
3061	<param name="id" type="uuid" mod="string" dir="in"/>
3062	</method>
3063
3064	<method name="detachUSBDevice">
3065	<desc>
3066	Notification that a VM is going to detach (@a done = @c false) or has
3067	already detached (@a done = @c true) the given USB device.
3068	When the @a done = @c true request is completed, the VM process will
3069	get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3070	notification.
3071	<note>
3072	In the @a done = @c true case, the server must run its own filters
3073	and filters of all VMs but this one on the detached device
3074	as if it were just attached to the host computer.
3075	</note>
3076	</desc>
3077	<param name="id" type="uuid" mod="string" dir="in"/>
3078	<param name="done" type="boolean" dir="in"/>
3079	</method>
3080
3081	<method name="autoCaptureUSBDevices">
3082	<desc>
3083	Requests a capture all matching USB devices attached to the host.
3084	When the request is completed, the VM process will
3085	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3086	notification per every captured device.
3087	</desc>
3088	</method>
3089
3090	<method name="detachAllUSBDevices">
3091	<desc>
3092	Notification that a VM that is being powered down. The done
3093	parameter indicates whether which stage of the power down
3094	we're at. When @a done = @c false the VM is announcing its
3095	intentions, while when @a done = @c true the VM is reporting
3096	what it has done.
3097	<note>
3098	In the @a done = @c true case, the server must run its own filters
3099	and filters of all VMs but this one on all detach devices as
3100	if they were just attached to the host computer.
3101	</note>
3102	</desc>
3103	<param name="done" type="boolean" dir="in"/>
3104	</method>
3105
3106	<method name="onSessionEnd">
3107	<desc>
3108	Triggered by the given session object when the session is about
3109	to close normally.
3110	</desc>
3111	<param name="session" type="ISession" dir="in">
3112	<desc>Session that is being closed</desc>
3113	</param>
3114	<param name="progress" type="IProgress" dir="return">
3115	<desc>
3116	Used to wait until the corresponding machine is actually
3117	dissociated from the given session on the server.
3118	Returned only when this session is a direct one.
3119	</desc>
3120	</param>
3121	</method>
3122
3123	<method name="beginSavingState">
3124	<desc>
3125	Called by the VM process to inform the server it wants to
3126	save the current state and stop the VM execution.
3127	</desc>
3128	<param name="progress" type="IProgress" dir="in">
3129	<desc>
3130	Progress object created by the VM process to wait until
3131	the state is saved.
3132	</desc>
3133	</param>
3134	<param name="stateFilePath" type="wstring" dir="out">
3135	<desc>
3136	File path the VM process must save the execution state to.
3137	</desc>
3138	</param>
3139	</method>
3140
3141	<method name="endSavingState">
3142	<desc>
3143	Called by the VM process to inform the server that saving
3144	the state previously requested by #beginSavingState is either
3145	successfully finished or there was a failure.
3146
3147	<result name="VBOX_E_FILE_ERROR">
3148	Settings file not accessible.
3149	</result>
3150	<result name="VBOX_E_XML_ERROR">
3151	Could not parse the settings file.
3152	</result>
3153
3154	</desc>
3155
3156	<param name="success" type="boolean" dir="in">
3157	<desc>@c true to indicate success and @c false otherwise.
3158	</desc>
3159	</param>
3160	</method>
3161
3162	<method name="adoptSavedState">
3163	<desc>
3164	Gets called by IConsole::adoptSavedState.
3165	<result name="VBOX_E_FILE_ERROR">
3166	Invalid saved state file path.
3167	</result>
3168	</desc>
3169	<param name="savedStateFile" type="wstring" dir="in">
3170	<desc>Path to the saved state file to adopt.</desc>
3171	</param>
3172	</method>
3173
3174	<method name="beginTakingSnapshot">
3175	<desc>
3176	Called from the VM process to request from the server to perform the
3177	server-side actions of creating a snapshot (creating differencing images
3178	and the snapshot object).
3179
3180	<result name="VBOX_E_FILE_ERROR">
3181	Settings file not accessible.
3182	</result>
3183	<result name="VBOX_E_XML_ERROR">
3184	Could not parse the settings file.
3185	</result>
3186	</desc>
3187	<param name="initiator" type="IConsole" dir="in">
3188	<desc>The console object that initiated this call.</desc>
3189	</param>
3190	<param name="name" type="wstring" dir="in">
3191	<desc>Snapshot name.</desc>
3192	</param>
3193	<param name="description" type="wstring" dir="in">
3194	<desc>Snapshot description.</desc>
3195	</param>
3196	<param name="consoleProgress" type="IProgress" dir="in">
3197	<desc>
3198	Progress object created by the VM process tracking the
3199	snapshot's progress. This has the following sub-operations:
3200	<ul>
3201	<li>setting up (weight 1);</li>
3202	<li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
3203	<li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
3204	<li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
3205	<li>finishing up (weight 1)</li>
3206	</ul>
3207	</desc>
3208	</param>
3209	<param name="fTakingSnapshotOnline" type="boolean" dir="in">
3210	<desc>
3211	Whether this is an online snapshot (i.e. the machine is running).
3212	</desc>
3213	</param>
3214	<param name="stateFilePath" type="wstring" dir="out">
3215	<desc>
3216	File path the VM process must save the execution state to.
3217	</desc>
3218	</param>
3219	</method>
3220
3221	<method name="endTakingSnapshot">
3222	<desc>
3223	Called by the VM process to inform the server that the snapshot
3224	previously requested by #beginTakingSnapshot is either
3225	successfully taken or there was a failure.
3226	</desc>
3227
3228	<param name="success" type="boolean" dir="in">
3229	<desc>@c true to indicate success and @c false otherwise</desc>
3230	</param>
3231	</method>
3232
3233	<method name="deleteSnapshot">
3234	<desc>
3235	Gets called by IConsole::deleteSnapshot.
3236	<result name="VBOX_E_INVALID_OBJECT_STATE">
3237	Snapshot has more than one child snapshot.
3238	</result>
3239	</desc>
3240	<param name="initiator" type="IConsole" dir="in">
3241	<desc>The console object that initiated this call.</desc>
3242	</param>
3243	<param name="id" type="uuid" mod="string" dir="in">
3244	<desc>UUID of the snapshot to delete.</desc>
3245	</param>
3246	<param name="machineState" type="MachineState" dir="out">
3247	<desc>New machine state after this operation is started.</desc>
3248	</param>
3249	<param name="progress" type="IProgress" dir="return">
3250	<desc>Progress object to track the operation completion.</desc>
3251	</param>
3252	</method>
3253
3254	<method name="finishOnlineMergeMedium">
3255	<desc>
3256	Gets called by IConsole::onlineMergeMedium.
3257	</desc>
3258	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
3259	<desc>The medium attachment which needs to be cleaned up.</desc>
3260	</param>
3261	<param name="source" type="IMedium" dir="in">
3262	<desc>Merge source medium.</desc>
3263	</param>
3264	<param name="target" type="IMedium" dir="in">
3265	<desc>Merge target medium.</desc>
3266	</param>
3267	<param name="mergeForward" type="boolean" dir="in">
3268	<desc>Merge direction.</desc>
3269	</param>
3270	<param name="parentForTarget" type="IMedium" dir="in">
3271	<desc>For forward merges: new parent for target medium.</desc>
3272	</param>
3273	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
3274	<desc>For backward merges: list of media which need their parent UUID
3275	updated.</desc>
3276	</param>
3277	</method>
3278
3279	<method name="restoreSnapshot">
3280	<desc>
3281	Gets called by IConsole::RestoreSnapshot.
3282	</desc>
3283	<param name="initiator" type="IConsole" dir="in">
3284	<desc>The console object that initiated this call.</desc>
3285	</param>
3286	<param name="snapshot" type="ISnapshot" dir="in">
3287	<desc>The snapshot to restore the VM state from.</desc>
3288	</param>
3289	<param name="machineState" type="MachineState" dir="out">
3290	<desc>New machine state after this operation is started.</desc>
3291	</param>
3292	<param name="progress" type="IProgress" dir="return">
3293	<desc>Progress object to track the operation completion.</desc>
3294	</param>
3295	</method>
3296
3297	<method name="pullGuestProperties">
3298	<desc>
3299	Get the list of the guest properties matching a set of patterns along
3300	with their values, time stamps and flags and give responsibility for
3301	managing properties to the console.
3302	</desc>
3303	<param name="name" type="wstring" dir="out" safearray="yes">
3304	<desc>
3305	The names of the properties returned.
3306	</desc>
3307	</param>
3308	<param name="value" type="wstring" dir="out" safearray="yes">
3309	<desc>
3310	The values of the properties returned. The array entries match the
3311	corresponding entries in the @a name array.
3312	</desc>
3313	</param>
3314	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
3315	<desc>
3316	The time stamps of the properties returned. The array entries match
3317	the corresponding entries in the @a name array.
3318	</desc>
3319	</param>
3320	<param name="flags" type="wstring" dir="out" safearray="yes">
3321	<desc>
3322	The flags of the properties returned. The array entries match the
3323	corresponding entries in the @a name array.
3324	</desc>
3325	</param>
3326	</method>
3327
3328	<method name="pushGuestProperty">
3329	<desc>
3330	Update a single guest property in IMachine.
3331	</desc>
3332	<param name="name" type="wstring" dir="in">
3333	<desc>
3334	The name of the property to be updated.
3335	</desc>
3336	</param>
3337	<param name="value" type="wstring" dir="in">
3338	<desc>
3339	The value of the property.
3340	</desc>
3341	</param>
3342	<param name="timestamp" type="unsigned long long" dir="in">
3343	<desc>
3344	The timestamp of the property.
3345	</desc>
3346	</param>
3347	<param name="flags" type="wstring" dir="in">
3348	<desc>
3349	The flags of the property.
3350	</desc>
3351	</param>
3352	</method>
3353
3354	<method name="lockMedia">
3355	<desc>
3356	Locks all media attached to the machine for writing and parents of
3357	attached differencing media (if any) for reading. This operation is
3358	atomic so that if it fails no media is actually locked.
3359
3360	This method is intended to be called when the machine is in Starting or
3361	Restoring state. The locked media will be automatically unlocked when
3362	the machine is powered off or crashed.
3363	</desc>
3364	</method>
3365	<method name="unlockMedia">
3366	<desc>
3367	Unlocks all media previously locked using
3368	<link to="IInternalMachineControl::lockMedia"/>.
3369
3370	This method is intended to be used with teleportation so that it is
3371	possible to teleport between processes on the same machine.
3372	</desc>
3373	</method>
3374	</interface>
3375
3376	<interface
3377	name="IBIOSSettings" extends="$unknown"
3378	uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
3379	wsmap="managed"
3380	>
3381	<desc>
3382	The IBIOSSettings interface represents BIOS settings of the virtual
3383	machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
3384	</desc>
3385	<attribute name="logoFadeIn" type="boolean">
3386	<desc>Fade in flag for BIOS logo animation.</desc>
3387	</attribute>
3388
3389	<attribute name="logoFadeOut" type="boolean">
3390	<desc>Fade out flag for BIOS logo animation.</desc>
3391	</attribute>
3392
3393	<attribute name="logoDisplayTime" type="unsigned long">
3394	<desc>BIOS logo display time in milliseconds (0 = default).</desc>
3395	</attribute>
3396
3397	<attribute name="logoImagePath" type="wstring">
3398	<desc>
3399	Local file system path for external BIOS splash image. Empty string
3400	means the default image is shown on boot.
3401	</desc>
3402	</attribute>
3403
3404	<attribute name="bootMenuMode" type="BIOSBootMenuMode">
3405	<desc>Mode of the BIOS boot device menu.</desc>
3406	</attribute>
3407
3408	<attribute name="ACPIEnabled" type="boolean">
3409	<desc>ACPI support flag.</desc>
3410	</attribute>
3411
3412	<attribute name="IOAPICEnabled" type="boolean">
3413	<desc>
3414	IO APIC support flag. If set, VirtualBox will provide an IO APIC
3415	and support IRQs above 15.
3416	</desc>
3417	</attribute>
3418
3419	<attribute name="timeOffset" type="long long">
3420	<desc>
3421	Offset in milliseconds from the host system time. This allows for
3422	guests running with a different system date/time than the host.
3423	It is equivalent to setting the system date/time in the BIOS except
3424	it is not an absolute value but a relative one. Guest Additions
3425	time synchronization honors this offset.
3426	</desc>
3427	</attribute>
3428
3429	<attribute name="PXEDebugEnabled" type="boolean">
3430	<desc>
3431	PXE debug logging flag. If set, VirtualBox will write extensive
3432	PXE trace information to the release log.
3433	</desc>
3434	</attribute>
3435
3436	</interface>
3437
3438	<enum name="CleanupMode"
3439	uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441">
3440	<desc>Cleanup mode, used with <link to="IMachine::unregister" />.
3441	</desc>
3442	<const name="UnregisterOnly" value="1">
3443	<desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc>
3444	</const>
3445	<const name="DetachAllReturnNone" value="2">
3446	<desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc>
3447	</const>
3448	<const name="DetachAllReturnHardDisksOnly" value="3">
3449	<desc>Delete all snapshots, detach all media and return hard disks for closing, but not removeable media.</desc>
3450	</const>
3451	<const name="Full" value="4">
3452	<desc>Delete all snapshots, detach all media and return all media for closing.</desc>
3453	</const>
3454	</enum>
3455
3456	<interface
3457	name="IMachine" extends="$unknown"
3458	uuid="082c38ff-d9b3-4b12-b540-01516a931f17"
3459	wsmap="managed"
3460	>
3461	<desc>
3462	The IMachine interface represents a virtual machine, or guest, created
3463	in VirtualBox.
3464
3465	This interface is used in two contexts. First of all, a collection of
3466	objects implementing this interface is stored in the
3467	<link to="IVirtualBox::machines"/> attribute which lists all the virtual
3468	machines that are currently registered with this VirtualBox
3469	installation. Also, once a session has been opened for the given virtual
3470	machine (e.g. the virtual machine is running), the machine object
3471	associated with the open session can be queried from the session object;
3472	see <link to="ISession"/> for details.
3473
3474	The main role of this interface is to expose the settings of the virtual
3475	machine and provide methods to change various aspects of the virtual
3476	machine's configuration. For machine objects stored in the
3477	<link to="IVirtualBox::machines"/> collection, all attributes are
3478	read-only unless explicitly stated otherwise in individual attribute
3479	and method descriptions.
3480
3481	In order to change a machine setting, a session for this machine must be
3482	opened using one of the <link to="IMachine::lockMachine" /> or
3483	<link to="IMachine::launchVMProcess"/> methods. After the
3484	machine has been successfully locked for a session, a mutable machine object
3485	needs to be queried from the session object and then the desired settings
3486	changes can be applied to the returned object using IMachine attributes and
3487	methods. See the <link to="ISession"/> interface description for more
3488	information about sessions.
3489
3490	Note that IMachine does not provide methods to control virtual machine
3491	execution (such as start the machine, or power it down) -- these methods
3492	are grouped in a separate interface called <link to="IConsole" />.
3493
3494	<see>ISession, IConsole</see>
3495	</desc>
3496
3497	<attribute name="parent" type="IVirtualBox" readonly="yes">
3498	<desc>Associated parent object.</desc>
3499	</attribute>
3500
3501	<attribute name="accessible" type="boolean" readonly="yes">
3502	<desc>
3503	Whether this virtual machine is currently accessible or not.
3504
3505	A machine is always deemed accessible unless it is registered <i>and</i>
3506	its settings file cannot be read or parsed (either because the file itself
3507	is unavailable or has invalid XML contents).
3508
3509	Every time this property is read, the accessibility state of
3510	this machine is re-evaluated. If the returned value is @c false,
3511	the <link to="#accessError"/> property may be used to get the
3512	detailed error information describing the reason of
3513	inaccessibility, including XML error messages.
3514
3515	When the machine is inaccessible, only the following properties
3516	can be used on it:
3517	<ul>
3518	<li><link to="#parent"/></li>
3519	<li><link to="#id"/></li>
3520	<li><link to="#settingsFilePath"/></li>
3521	<li><link to="#accessible"/></li>
3522	<li><link to="#accessError"/></li>
3523	</ul>
3524
3525	An attempt to access any other property or method will return
3526	an error.
3527
3528	The only possible action you can perform on an inaccessible
3529	machine is to unregister it using the
3530	<link to="IMachine::unregister"/> call (or, to check
3531	for the accessibility state once more by querying this
3532	property).
3533
3534	<note>
3535	In the current implementation, once this property returns
3536	@c true, the machine will never become inaccessible
3537	later, even if its settings file cannot be successfully
3538	read/written any more (at least, until the VirtualBox
3539	server is restarted). This limitation may be removed in
3540	future releases.
3541	</note>
3542	</desc>
3543	</attribute>
3544
3545	<attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
3546	<desc>
3547	Error information describing the reason of machine
3548	inaccessibility.
3549
3550	Reading this property is only valid after the last call to
3551	<link to="#accessible"/> returned @c false (i.e. the
3552	machine is currently unaccessible). Otherwise, a @c null
3553	IVirtualBoxErrorInfo object will be returned.
3554	</desc>
3555	</attribute>
3556
3557	<attribute name="name" type="wstring">
3558	<desc>
3559	Name of the virtual machine.
3560
3561	Besides being used for human-readable identification purposes
3562	everywhere in VirtualBox, the virtual machine name is also used
3563	as a name of the machine's settings file and as a name of the
3564	subdirectory this settings file resides in. Thus, every time you
3565	change the value of this property, the settings file will be
3566	renamed once you call <link to="#saveSettings"/> to confirm the
3567	change. The containing subdirectory will be also renamed, but
3568	only if it has exactly the same name as the settings file
3569	itself prior to changing this property (for backward compatibility
3570	with previous API releases). The above implies the following
3571	limitations:
3572	<ul>
3573	<li>The machine name cannot be empty.</li>
3574	<li>The machine name can contain only characters that are valid
3575	file name characters according to the rules of the file
3576	system used to store VirtualBox configuration.</li>
3577	<li>You cannot have two or more machines with the same name
3578	if they use the same subdirectory for storing the machine
3579	settings files.</li>
3580	<li>You cannot change the name of the machine if it is running,
3581	or if any file in the directory containing the settings file
3582	is being used by another running machine or by any other
3583	process in the host operating system at a time when
3584	<link to="#saveSettings"/> is called.
3585	</li>
3586	</ul>
3587	If any of the above limitations are hit, <link to="#saveSettings"/>
3588	will return an appropriate error message explaining the exact
3589	reason and the changes you made to this machine will not be
3590	saved.
3591	<note>
3592	For "legacy" machines created using the
3593	<link to="IVirtualBox::createLegacyMachine"/> call,
3594	the above naming limitations do not apply because the
3595	machine name does not affect the settings file name.
3596	The settings file name remains the same as it was specified
3597	during machine creation and never changes.
3598	</note>
3599	</desc>
3600	</attribute>
3601
3602	<attribute name="description" type="wstring">
3603	<desc>
3604	Description of the virtual machine.
3605
3606	The description attribute can contain any text and is
3607	typically used to describe the hardware and software
3608	configuration of the virtual machine in detail (i.e. network
3609	settings, versions of the installed software and so on).
3610	</desc>
3611	</attribute>
3612
3613	<attribute name="id" type="uuid" mod="string" readonly="yes">
3614	<desc>UUID of the virtual machine.</desc>
3615	</attribute>
3616
3617	<attribute name="OSTypeId" type="wstring">
3618	<desc>
3619	User-defined identifier of the Guest OS type.
3620	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
3621	an IGuestOSType object representing details about the given
3622	Guest OS type.
3623	<note>
3624	This value may differ from the value returned by
3625	<link to="IGuest::OSTypeId"/> if Guest Additions are
3626	installed to the guest OS.
3627	</note>
3628	</desc>
3629	</attribute>
3630
3631	<attribute name="HardwareVersion" type="wstring">
3632	<desc>Hardware version identifier. Internal use only for now.</desc>
3633	</attribute>
3634
3635	<attribute name="hardwareUUID" type="uuid" mod="string">
3636	<desc>
3637	The UUID presented to the guest via memory tables, hardware and guest
3638	properties. For most VMs this is the same as the @a id, but for VMs
3639	which have been cloned or teleported it may be the same as the source
3640	VM. This latter is because the guest shouldn't notice that it was
3641	cloned or teleported.
3642	</desc>
3643	</attribute>
3644
3645	<attribute name="CPUCount" type="unsigned long">
3646	<desc>Number of virtual CPUs in the VM.</desc>
3647	</attribute>
3648
3649	<attribute name="CPUHotPlugEnabled" type="boolean">
3650	<desc>
3651	This setting determines whether VirtualBox allows CPU
3652	hotplugging for this machine.</desc>
3653	</attribute>
3654
3655	<attribute name="CPUPriority" type="unsigned long">
3656	<desc>
3657	Priority of the virtual CPUs. Means to limit the number of CPU cycles
3658	a guest can use. The unit is percentage of host CPU cycles per second.
3659	The valid range is 1 - 100. 100 (the default) implies no limit.
3660	</desc>
3661	</attribute>
3662
3663	<attribute name="memorySize" type="unsigned long">
3664	<desc>System memory size in megabytes.</desc>
3665	</attribute>
3666
3667	<attribute name="memoryBalloonSize" type="unsigned long">
3668	<desc>Memory balloon size in megabytes.</desc>
3669	</attribute>
3670
3671	<attribute name="PageFusionEnabled" type="boolean">
3672	<desc>
3673	This setting determines whether VirtualBox allows page
3674	fusion for this machine (64 bits host only).
3675	</desc>
3676	</attribute>
3677
3678	<attribute name="VRAMSize" type="unsigned long">
3679	<desc>Video memory size in megabytes.</desc>
3680	</attribute>
3681
3682	<attribute name="accelerate3DEnabled" type="boolean" default="false">
3683	<desc>
3684	This setting determines whether VirtualBox allows this machine to make
3685	use of the 3D graphics support available on the host.</desc>
3686	</attribute>
3687
3688	<attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
3689	<desc>
3690	This setting determines whether VirtualBox allows this machine to make
3691	use of the 2D video acceleration support available on the host.</desc>
3692	</attribute>
3693
3694	<attribute name="monitorCount" type="unsigned long">
3695	<desc>
3696	Number of virtual monitors.
3697	<note>
3698	Only effective on Windows XP and later guests with
3699	Guest Additions installed.
3700	</note>
3701	</desc>
3702	</attribute>
3703
3704	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
3705	<desc>Object containing all BIOS settings.</desc>
3706	</attribute>
3707
3708	<attribute name="firmwareType" type="FirmwareType">
3709	<desc>Type of firmware (such as legacy BIOS or EFI), used for initial
3710	bootstrap in this VM.</desc>
3711	</attribute>
3712
3713	<attribute name="pointingHidType" type="PointingHidType">
3714	<desc>Type of pointing HID (such as mouse or tablet) used in this VM.
3715	The default is typically "PS2Mouse" but can vary depending on the
3716	requirements of the guest operating system.</desc>
3717	</attribute>
3718
3719	<attribute name="keyboardHidType" type="KeyboardHidType">
3720	<desc>Type of keyboard HID used in this VM.
3721	The default is typically "PS2Keyboard" but can vary depending on the
3722	requirements of the guest operating system.</desc>
3723	</attribute>
3724
3725	<attribute name="hpetEnabled" type="boolean">
3726	<desc>This attribute controls if High Precision Event Timer (HPET) is
3727	enabled in this VM. Use this property if you want to provide guests
3728	with additional time source, or if guest requires HPET to function correctly.
3729	Default is false.</desc>
3730	</attribute>
3731
3732	<attribute name="snapshotFolder" type="wstring">
3733	<desc>
3734	Full path to the directory used to store snapshot data
3735	(differencing media and saved state files) of this machine.
3736
3737	The initial value of this property is
3738	<tt><</tt><link to="#settingsFilePath">
3739	path_to_settings_file</link><tt>>/<</tt>
3740	<link to="#id">machine_uuid</link>
3741	<tt>></tt>.
3742
3743	Currently, it is an error to try to change this property on
3744	a machine that has snapshots (because this would require to
3745	move possibly large files to a different location).
3746	A separate method will be available for this purpose later.
3747
3748	<note>
3749	Setting this property to @c null or to an empty string will restore
3750	the initial value.
3751	</note>
3752	<note>
3753	When setting this property, the specified path can be
3754	absolute (full path) or relative to the directory where the
3755	<link to="#settingsFilePath">machine settings file</link>
3756	is located. When reading this property, a full path is
3757	always returned.
3758	</note>
3759	<note>
3760	The specified path may not exist, it will be created
3761	when necessary.
3762	</note>
3763	</desc>
3764	</attribute>
3765
3766	<attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
3767	<desc>VRDP server object.</desc>
3768	</attribute>
3769
3770	<attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
3771	<desc>Array of media attached to this machine.</desc>
3772	</attribute>
3773
3774	<attribute name="USBController" type="IUSBController" readonly="yes">
3775	<desc>
3776	Associated USB controller object.
3777
3778	<note>
3779	If USB functionality is not available in the given edition of
3780	VirtualBox, this method will set the result code to @c E_NOTIMPL.
3781	</note>
3782	</desc>
3783	</attribute>
3784
3785	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
3786	<desc>Associated audio adapter, always present.</desc>
3787	</attribute>
3788
3789	<attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
3790	<desc>Array of storage controllers attached to this machine.</desc>
3791	</attribute>
3792
3793	<attribute name="settingsFilePath" type="wstring" readonly="yes">
3794	<desc>
3795	Full name of the file containing machine settings data.
3796	</desc>
3797	</attribute>
3798
3799	<attribute name="settingsModified" type="boolean" readonly="yes">
3800	<desc>
3801	Whether the settings of this machine have been modified
3802	(but neither yet saved nor discarded).
3803	<note>
3804	Reading this property is only valid on instances returned
3805	by <link to="ISession::machine"/> and on new machines
3806	created by <link to="IVirtualBox::createMachine"/> or opened
3807	by <link to="IVirtualBox::openMachine"/> but not
3808	yet registered, or on unregistered machines after calling
3809	<link to="IMachine::unregister"/>. For all other
3810	cases, the settings can never be modified.
3811	</note>
3812	<note>
3813	For newly created unregistered machines, the value of this
3814	property is always @c true until <link to="#saveSettings"/>
3815	is called (no matter if any machine settings have been
3816	changed after the creation or not). For opened machines
3817	the value is set to @c false (and then follows to normal rules).
3818	</note>
3819	</desc>
3820	</attribute>
3821
3822	<attribute name="sessionState" type="SessionState" readonly="yes">
3823	<desc>Current session state for this machine.</desc>
3824	</attribute>
3825
3826	<attribute name="sessionType" type="wstring" readonly="yes">
3827	<desc>
3828	Type of the session. If <link to="#sessionState"/> is
3829	Spawning or Locked, this attribute contains the
3830	same value as passed to the
3831	<link to="IMachine::launchVMProcess"/> method in the
3832	@a type parameter. If the session was used with
3833	<link to="IMachine::lockMachine" />, or if
3834	<link to="#sessionState"/> is SessionClosed, the value of this
3835	attribute is an empty string.
3836	</desc>
3837	</attribute>
3838
3839	<attribute name="sessionPid" type="unsigned long" readonly="yes">
3840	<desc>
3841	Identifier of the session process. This attribute contains the
3842	platform-dependent identifier of the process whose session was
3843	used with <link to="IMachine::lockMachine" /> call. The returned
3844	value is only valid if <link to="#sessionState"/> is Locked or
3845	Unlocking by the time this property is read.
3846	</desc>
3847	</attribute>
3848
3849	<attribute name="state" type="MachineState" readonly="yes">
3850	<desc>Current execution state of this machine.</desc>
3851	</attribute>
3852
3853	<attribute name="lastStateChange" type="long long" readonly="yes">
3854	<desc>
3855	Time stamp of the last execution state change,
3856	in milliseconds since 1970-01-01 UTC.
3857	</desc>
3858	</attribute>
3859
3860	<attribute name="stateFilePath" type="wstring" readonly="yes">
3861	<desc>
3862	Full path to the file that stores the execution state of
3863	the machine when it is in the <link to="MachineState_Saved"/> state.
3864	<note>
3865	When the machine is not in the Saved state, this attribute is
3866	an empty string.
3867	</note>
3868	</desc>
3869	</attribute>
3870
3871	<attribute name="logFolder" type="wstring" readonly="yes">
3872	<desc>
3873	Full path to the folder that stores a set of rotated log files
3874	recorded during machine execution. The most recent log file is
3875	named <tt>VBox.log</tt>, the previous log file is
3876	named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
3877	in the current version).
3878	</desc>
3879	</attribute>
3880
3881	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
3882	<desc>
3883	Current snapshot of this machine. This is @c null if the machine
3884	currently has no snapshots. If it is not @c null, then it was
3885	set by one of <link to="IConsole::takeSnapshot" />,
3886	<link to="IConsole::deleteSnapshot" />
3887	or <link to="IConsole::restoreSnapshot" />, depending on which
3888	was called last. See <link to="ISnapshot"/> for details.
3889	</desc>
3890	</attribute>
3891
3892	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
3893	<desc>
3894	Number of snapshots taken on this machine. Zero means the
3895	machine doesn't have any snapshots.
3896	</desc>
3897	</attribute>
3898
3899	<attribute name="currentStateModified" type="boolean" readonly="yes">
3900	<desc>
3901	Returns @c true if the current state of the machine is not
3902	identical to the state stored in the current snapshot.
3903
3904	The current state is identical to the current snapshot only
3905	directly after one of the following calls are made:
3906
3907	<ul>
3908	<li><link to="IConsole::restoreSnapshot"/>
3909	</li>
3910	<li><link to="IConsole::takeSnapshot"/> (issued on a
3911	"powered off" or "saved" machine, for which
3912	<link to="#settingsModified"/> returns @c false)
3913	</li>
3914	<li><link to="IMachine::setCurrentSnapshot"/>
3915	</li>
3916	</ul>
3917
3918	The current state remains identical until one of the following
3919	happens:
3920	<ul>
3921	<li>settings of the machine are changed</li>
3922	<li>the saved state is deleted</li>
3923	<li>the current snapshot is deleted</li>
3924	<li>an attempt to execute the machine is made</li>
3925	</ul>
3926
3927	<note>
3928	For machines that don't have snapshots, this property is
3929	always @c false.
3930	</note>
3931	</desc>
3932	</attribute>
3933
3934	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
3935	<desc>
3936	Collection of shared folders for this machine (permanent shared
3937	folders). These folders are shared automatically at machine startup
3938	and available only to the guest OS installed within this machine.
3939
3940	New shared folders are added to the collection using
3941	<link to="#createSharedFolder"/>. Existing shared folders can be
3942	removed using <link to="#removeSharedFolder"/>.
3943	</desc>
3944	</attribute>
3945
3946	<attribute name="clipboardMode" type="ClipboardMode">
3947	<desc>
3948	Synchronization mode between the host OS clipboard
3949	and the guest OS clipboard.
3950	</desc>
3951	</attribute>
3952
3953	<attribute name="guestPropertyNotificationPatterns" type="wstring">
3954	<desc>
3955	A comma-separated list of simple glob patterns. Changes to guest
3956	properties whose name matches one of the patterns will generate an
3957	<link to="IGuestPropertyChangedEvent"/> signal.
3958	</desc>
3959	</attribute>
3960
3961	<attribute name="teleporterEnabled" type="boolean">
3962	<desc>
3963	When set to @a true, the virtual machine becomes a target teleporter
3964	the next time it is powered on. This can only set to @a true when the
3965	VM is in the @a PoweredOff or @a Aborted state.
3966
3967	<!-- This property is automatically set to @a false when the VM is powered
3968	on. (bird: This doesn't work yet ) -->
3969	</desc>
3970	</attribute>
3971
3972	<attribute name="teleporterPort" type="unsigned long">
3973	<desc>
3974	The TCP port the target teleporter will listen for incoming
3975	teleportations on.
3976
3977	0 means the port is automatically selected upon power on. The actual
3978	value can be read from this property while the machine is waiting for
3979	incoming teleportations.
3980	</desc>
3981	</attribute>
3982
3983	<attribute name="teleporterAddress" type="wstring">
3984	<desc>
3985	The address the target teleporter will listen on. If set to an empty
3986	string, it will listen on all addresses.
3987	</desc>
3988	</attribute>
3989
3990	<attribute name="teleporterPassword" type="wstring">
3991	<desc>
3992	The password the to check for on the target teleporter. This is just a
3993	very basic measure to prevent simple hacks and operators accidentally
3994	beaming a virtual machine to the wrong place.
3995	</desc>
3996	</attribute>
3997
3998	<attribute name="RTCUseUTC" type="boolean">
3999	<desc>
4000	When set to @a true, the RTC device of the virtual machine will run
4001	in UTC time, otherwise in local time. Especially Unix guests prefer
4002	the time in UTC.
4003	</desc>
4004	</attribute>
4005
4006	<attribute name="ioCacheEnabled" type="boolean">
4007	<desc>
4008	When set to @a true, the builtin I/O cache of the virtual machine
4009	will be enabled.
4010	</desc>
4011	</attribute>
4012
4013	<attribute name="ioCacheSize" type="unsigned long">
4014	<desc>
4015	Maximum size of the I/O cache in MB.
4016	</desc>
4017	</attribute>
4018
4019	<method name="lockMachine">
4020	<desc>
4021	Locks the machine for the given session to enable the caller
4022	to make changes to the machine or start the VM or control
4023	VM execution.
4024
4025	There are two ways to lock a machine for such uses:
4026
4027	<ul>
4028	<li>If you want to make changes to the machine settings,
4029	you must obtain an exclusive write lock on the machine
4030	by setting @a lockType to @c Write.
4031
4032	This will only succeed if no other process has locked
4033	the machine to prevent conflicting changes. Only after
4034	an exclusive write lock has been obtained using this method, one
4035	can change all VM settings or execute the VM in the process
4036	space of the session object. (Note that the latter is only of
4037	interest if you actually want to write a new front-end for
4038	virtual machines; but this API gets called internally by
4039	the existing front-ends such as VBoxHeadless and the VirtualBox
4040	GUI to acquire a write lock on the machine that they are running.)
4041
4042	On success, write-locking the machine for a session creates
4043	a second copy of the IMachine object. It is this second object
4044	upon which changes can be made; in VirtualBox terminology, the
4045	second copy is "mutable". It is only this second, mutable machine
4046	object upon which you can call methods that change the
4047	machine state. After having called this method, you can
4048	obtain this second, mutable machine object using the
4049	<link to="ISession::machine" /> attribute.
4050	</li>
4051	<li>If you only want to check the machine state or control
4052	machine execution without actually changing machine
4053	settings (e.g. to get access to VM statistics or take
4054	a snapshot or save the machine state), then set the
4055	@a lockType argument to @c Shared.
4056
4057	If no other session has obtained a lock, you will obtain an
4058	exclusive write lock as described above. However, if another
4059	session has already obtained such a lock, then a link to that
4060	existing session will be established which allows you
4061	to control that existing session.
4062
4063	To find out which type of lock was obtained, you can
4064	inspect <link to="ISession::type" />, which will have been
4065	set to either @c WriteLock or @c Shared.
4066	</li>
4067	</ul>
4068
4069	In either case, you can get access to the <link to="IConsole" />
4070	object which controls VM execution.
4071
4072	Also in all of the above cases, one must always call
4073	<link to="ISession::unlockMachine" /> to release the lock on the machine, or
4074	the machine's state will eventually be set to "Aborted".
4075
4076	To change settings on a machine, the following sequence is typically
4077	performed:
4078
4079	<ol>
4080	<li>Call this method to obtain an exclusive write lock for the current session.</li>
4081
4082	<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
4083
4084	<li>Change the settings of the machine by invoking IMachine methods.</li>
4085
4086	<li>Call <link to="IMachine::saveSettings" />.</li>
4087
4088	<li>Release the write lock by calling <link to="ISession::unlockMachine"/>.</li>
4089	</ol>
4090
4091	<result name="E_UNEXPECTED">
4092	Virtual machine not registered.
4093	</result>
4094	<result name="E_ACCESSDENIED">
4095	Process not started by OpenRemoteSession.
4096	</result>
4097	<result name="VBOX_E_INVALID_OBJECT_STATE">
4098	Session already open or being opened.
4099	</result>
4100	<result name="VBOX_E_VM_ERROR">
4101	Failed to assign machine to session.
4102	</result>
4103	</desc>
4104	<param name="session" type="ISession" dir="in">
4105	<desc>
4106	Session object for which the machine will be locked.
4107	</desc>
4108	</param>
4109	<param name="lockType" type="LockType" dir="in">
4110	<desc>
4111	If set to @c Write, then attempt to acquire an exclusive write lock or fail.
4112	If set to @c Shared, then either acquire an exclusive write lock or establish
4113	a link to an existing session.
4114	</desc>
4115	</param>
4116	</method>
4117
4118	<method name="launchVMProcess">
4119	<desc>
4120	Spawns a new process that will execute the virtual machine and obtains a shared
4121	lock on the machine for the calling session.
4122
4123	If launching the VM succeeds, the new VM process will create its own session
4124	and write-lock the machine for it, preventing conflicting changes from other
4125	processes. If the machine is already locked (because it is already running or
4126	because another session has a write lock), launching the VM process will therefore
4127	fail. Reversely, future attempts to obtain a write lock will also fail while the
4128	machine is running.
4129
4130	The caller's session object remains separate from the session opened by the new
4131	VM process. It receives its own <link to="IConsole" /> object which can be used
4132	to control machine execution, but it cannot be used to change all VM settings
4133	which would be available after a <link to="#lockMachine" /> call.
4134
4135	The caller must eventually release the session's shared lock by calling
4136	<link to="ISession::unlockMachine" /> on the local session object once this call
4137	has returned. However, the session's state (see <link to="ISession::state" />)
4138	will not return to "Unlocked" until the remote session has also unlocked
4139	the machine (i.e. the machine has stopped running).
4140
4141	Lauching a VM process can take some time (a new VM is started in a new process,
4142	for which memory and other resources need to be set up). Because of this,
4143	an <link to="IProgress" /> object is returned to allow the caller to wait
4144	for this asynchronous operation to be completed. Until then, the caller's
4145	session object remains in the "Unlocked" state, and its <link to="ISession::machine" />
4146	and <link to="ISession::console" /> attributes cannot be accessed.
4147	It is recommended to use <link to="IProgress::waitForCompletion" /> or
4148	similar calls to wait for completion. Completion is signalled when the VM
4149	is powered on. If launching the VM fails, error messages can be queried
4150	via the progress object, if available.
4151
4152	The progress object will have at least 2 sub-operations. The first
4153	operation covers the period up to the new VM process calls powerUp.
4154	The subsequent operations mirror the <link to="IConsole::powerUp"/>
4155	progress object. Because <link to="IConsole::powerUp"/> may require
4156	some extra sub-operations, the <link to="IProgress::operationCount"/>
4157	may change at the completion of operation.
4158
4159	For details on the teleportation progress operation, see
4160	<link to="IConsole::powerUp"/>.
4161
4162	The @a environment argument is a string containing definitions of
4163	environment variables in the following format:
4164	@code
4165	NAME[=VALUE]\n
4166	NAME[=VALUE]\n
4167	...
4168	@endcode
4169	where <tt>\\n</tt> is the new line character. These environment
4170	variables will be appended to the environment of the VirtualBox server
4171	process. If an environment variable exists both in the server process
4172	and in this list, the value from this list takes precedence over the
4173	server's variable. If the value of the environment variable is
4174	omitted, this variable will be removed from the resulting environment.
4175	If the environment string is @c null or empty, the server environment
4176	is inherited by the started process as is.
4177
4178	<result name="E_UNEXPECTED">
4179	Virtual machine not registered.
4180	</result>
4181	<result name="E_INVALIDARG">
4182	Invalid session type @a type.
4183	</result>
4184	<result name="VBOX_E_OBJECT_NOT_FOUND">
4185	No machine matching @a machineId found.
4186	</result>
4187	<result name="VBOX_E_INVALID_OBJECT_STATE">
4188	Session already open or being opened.
4189	</result>
4190	<result name="VBOX_E_IPRT_ERROR">
4191	Launching process for machine failed.
4192	</result>
4193	<result name="VBOX_E_VM_ERROR">
4194	Failed to assign machine to session.
4195	</result>
4196	</desc>
4197	<param name="session" type="ISession" dir="in">
4198	<desc>
4199	Client session object to which the VM process will be connected (this
4200	must be in "Unlocked" state).
4201	</desc>
4202	</param>
4203	<param name="type" type="wstring" dir="in">
4204	<desc>
4205	Front-end to use for the new VM process. The following are currently supported:
4206	<ul>
4207	<li><tt>"gui"</tt>: VirtualBox Qt GUI front-end</li>
4208	<li><tt>"vrdp"</tt>: VBoxHeadless (VRDP Server) front-end</li>
4209	<li><tt>"sdl"</tt>: VirtualBox SDL front-end</li>
4210	</ul>
4211	</desc>
4212	</param>
4213	<param name="environment" type="wstring" dir="in">
4214	<desc>
4215	Environment to pass to the VM process.
4216	</desc>
4217	</param>
4218	<param name="progress" type="IProgress" dir="return">
4219	<desc>Progress object to track the operation completion.</desc>
4220	</param>
4221	</method>
4222
4223	<method name="setBootOrder">
4224	<desc>
4225	Puts the given device to the specified position in
4226	the boot order.
4227
4228	To indicate that no device is associated with the given position,
4229	<link to="DeviceType_Null"/> should be used.
4230
4231	@todo setHardDiskBootOrder(), setNetworkBootOrder()
4232
4233	<result name="E_INVALIDARG">
4234	Boot @a position out of range.
4235	</result>
4236	<result name="E_NOTIMPL">
4237	Booting from USB @a device currently not supported.
4238	</result>
4239
4240	</desc>
4241	<param name="position" type="unsigned long" dir="in">
4242	<desc>
4243	Position in the boot order (@c 1 to the total number of
4244	devices the machine can boot from, as returned by
4245	<link to="ISystemProperties::maxBootPosition"/>).
4246	</desc>
4247	</param>
4248	<param name="device" type="DeviceType" dir="in">
4249	<desc>
4250	The type of the device used to boot at the given position.
4251	</desc>
4252	</param>
4253	</method>
4254
4255	<method name="getBootOrder" const="yes">
4256	<desc>
4257	Returns the device type that occupies the specified
4258	position in the boot order.
4259
4260	@todo [remove?]
4261	If the machine can have more than one device of the returned type
4262	(such as hard disks), then a separate method should be used to
4263	retrieve the individual device that occupies the given position.
4264
4265	If here are no devices at the given position, then
4266	<link to="DeviceType_Null"/> is returned.
4267
4268	@todo getHardDiskBootOrder(), getNetworkBootOrder()
4269
4270	<result name="E_INVALIDARG">
4271	Boot @a position out of range.
4272	</result>
4273
4274	</desc>
4275	<param name="position" type="unsigned long" dir="in">
4276	<desc>
4277	Position in the boot order (@c 1 to the total number of
4278	devices the machine can boot from, as returned by
4279	<link to="ISystemProperties::maxBootPosition"/>).
4280	</desc>
4281	</param>
4282	<param name="device" type="DeviceType" dir="return">
4283	<desc>
4284	Device at the given position.
4285	</desc>
4286	</param>
4287	</method>
4288
4289	<method name="attachDevice">
4290	<desc>
4291	Attaches a device and optionally mounts a medium to the given storage
4292	controller (<link to="IStorageController" />, identified by @a name),
4293	at the indicated port and device.
4294
4295	This method is intended for managing storage devices in general (it works
4296	for both fixed and removable media) while a machine is powered off.
4297	In a VM's default configuration of virtual machines, the secondary
4298	master of the IDE controller is used for a CD/DVD drive.
4299
4300	For fixed media such as hard disks, the given medium identifier cannot
4301	be a zero UUID.
4302
4303	For storage devices supporting removable media (such as DVDs and floppies),
4304	you can also use <link to="IMachine::mountMedium"/> for changing the media
4305	while the machine is running. For those devices, you can also specify
4306	a zero UUID to indicate an empty drive or the UUID of a host drive;
4307	see <link to="IMediumAttachment" /> for details.
4308
4309	After calling this returns successfully, a new instance of
4310	<link to="IMediumAttachment"/> will appear in the machine's list of medium
4311	attachments (see <link to="IMachine::mediumAttachments"/>).
4312
4313	The specified device slot must not have a device attached to it,
4314	or this method will fail.
4315
4316	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
4317	information about attaching media.
4318
4319	<note>
4320	You cannot attach a device to a running machine. Also, you cannot
4321	attach a device to a newly created machine until this machine's
4322	settings are saved to disk using <link to="#saveSettings"/>.
4323	</note>
4324	<note>
4325	If the medium is being attached indirectly, a new differencing medium
4326	will implicitly be created for it and attached instead. If the
4327	changes made to the machine settings (including this indirect
4328	attachment) are later cancelled using <link to="#discardSettings"/>,
4329	this implicitly created differencing medium will implicitly
4330	be deleted.
4331	</note>
4332
4333	<result name="E_INVALIDARG">
4334	SATA device, SATA port, IDE port or IDE slot out of range.
4335	</result>
4336	<result name="VBOX_E_INVALID_OBJECT_STATE">
4337	Machine must be registered before media can be attached.
4338	</result>
4339	<result name="VBOX_E_INVALID_VM_STATE">
4340	Invalid machine state.
4341	</result>
4342	<result name="VBOX_E_OBJECT_IN_USE">
4343	A medium is already attached to this or another virtual machine.
4344	</result>
4345
4346	</desc>
4347	<param name="name" type="wstring" dir="in">
4348	<desc>Name of the storage controller to attach the device to.</desc>
4349	</param>
4350	<param name="controllerPort" type="long" dir="in">
4351	<desc>Port to attach the device to. For an IDE controller, 0 specifies
4352	the primary controller and 1 specifies the secondary controller.
4353	For a SCSI controller, this must range from 0 to 15; for a SATA controller,
4354	from 0 to 29; for an SAS controller, from 0 to 7.</desc>
4355	</param>
4356	<param name="device" type="long" dir="in">
4357	<desc>Device slot in the given port to attach the device to. This is only
4358	relevant for IDE controllers, for which 0 specifies the master device and
4359	1 specifies the slave device. For all other controller types, this must
4360	be 0.</desc>
4361	</param>
4362	<param name="type" type="DeviceType" dir="in">
4363	<desc>Device type of the attached device.</desc>
4364	</param>
4365	<param name="id" type="uuid" mod="string" dir="in">
4366	<desc>UUID of the medium to mount. Can be a zero UUID or the UUID of
4367	a host drive for removeable media; see <link to="IMediumAttachment" />
4368	for details.</desc>
4369	</param>
4370	</method>
4371
4372	<method name="detachDevice">
4373	<desc>
4374	Detaches the device attached to a device slot of the specified bus.
4375
4376	Detaching the device from the virtual machine is deferred. This means
4377	that the medium remains associated with the machine when this method
4378	returns and gets actually de-associated only after a successful
4379	<link to="#saveSettings"/> call. See <link to="IMedium"/>
4380	for more detailed information about attaching media.
4381
4382	<note>
4383	You cannot detach a device from a running machine.
4384	</note>
4385	<note>
4386	Detaching differencing media implicitly created by <link
4387	to="#attachDevice"/> for the indirect attachment using this
4388	method will <b>not</b> implicitly delete them. The
4389	<link to="IMedium::deleteStorage"/> operation should be
4390	explicitly performed by the caller after the medium is successfully
4391	detached and the settings are saved with
4392	<link to="#saveSettings"/>, if it is the desired action.
4393	</note>
4394
4395	<result name="VBOX_E_INVALID_VM_STATE">
4396	Attempt to detach medium from a running virtual machine.
4397	</result>
4398	<result name="VBOX_E_OBJECT_NOT_FOUND">
4399	No medium attached to given slot/bus.
4400	</result>
4401	<result name="VBOX_E_NOT_SUPPORTED">
4402	Medium format does not support storage deletion.
4403	</result>
4404
4405	</desc>
4406	<param name="name" type="wstring" dir="in">
4407	<desc>Name of the storage controller to detach the medium from.</desc>
4408	</param>
4409	<param name="controllerPort" type="long" dir="in">
4410	<desc>Port number to detach the medium from.</desc>
4411	</param>
4412	<param name="device" type="long" dir="in">
4413	<desc>Device slot number to detach the medium from.</desc>
4414	</param>
4415	</method>
4416
4417	<method name="passthroughDevice">
4418	<desc>
4419	Sets the passthrough mode of an existing DVD device. Changing the
4420	setting while the VM is running is forbidden. The setting is only used
4421	if at VM start the device is configured as a host DVD drive, in all
4422	other cases it is ignored. The device must already exist; see
4423	<link to="IMachine::attachDevice"/> for how to attach a new device.
4424
4425	The @a controllerPort and @a device parameters specify the device slot and
4426	have have the same meaning as with <link to="IMachine::attachDevice" />.
4427
4428	<result name="E_INVALIDARG">
4429	SATA device, SATA port, IDE port or IDE slot out of range.
4430	</result>
4431	<result name="VBOX_E_INVALID_OBJECT_STATE">
4432	Attempt to modify an unregistered virtual machine.
4433	</result>
4434	<result name="VBOX_E_INVALID_VM_STATE">
4435	Invalid machine state.
4436	</result>
4437
4438	</desc>
4439	<param name="name" type="wstring" dir="in">
4440	<desc>Name of the storage controller.</desc>
4441	</param>
4442	<param name="controllerPort" type="long" dir="in">
4443	<desc>Storage controller port.</desc>
4444	</param>
4445	<param name="device" type="long" dir="in">
4446	<desc>Device slot in the given port.</desc>
4447	</param>
4448	<param name="passthrough" type="boolean" dir="in">
4449	<desc>New value for the passthrough setting.</desc>
4450	</param>
4451	</method>
4452
4453	<method name="mountMedium">
4454	<desc>
4455	Mounts a medium (<link to="IMedium" />, identified
4456	by the given UUID @a id) to the given storage controller
4457	(<link to="IStorageController" />, identified by @a name),
4458	at the indicated port and device. The device must already exist;
4459	see <link to="IMachine::attachDevice"/> for how to attach a new device.
4460
4461	This method is intended only for managing removable media, where the
4462	device is fixed but media is changeable at runtime (such as DVDs
4463	and floppies). It cannot be used for fixed media such as hard disks.
4464
4465	The @a controllerPort and @a device parameters specify the device slot and
4466	have have the same meaning as with <link to="IMachine::attachDevice" />.
4467
4468	The specified device slot can have a medium mounted, which will be
4469	unmounted first. Specifying a zero UUID (or an empty string) for
4470	@a medium does just an unmount.
4471
4472	See <link to="IMedium"/> for more detailed information about
4473	attaching media.
4474
4475	<result name="E_INVALIDARG">
4476	SATA device, SATA port, IDE port or IDE slot out of range.
4477	</result>
4478	<result name="VBOX_E_INVALID_OBJECT_STATE">
4479	Attempt to attach medium to an unregistered virtual machine.
4480	</result>
4481	<result name="VBOX_E_INVALID_VM_STATE">
4482	Invalid machine state.
4483	</result>
4484	<result name="VBOX_E_OBJECT_IN_USE">
4485	Medium already attached to this or another virtual machine.
4486	</result>
4487
4488	</desc>
4489	<param name="name" type="wstring" dir="in">
4490	<desc>Name of the storage controller to attach the medium to.</desc>
4491	</param>
4492	<param name="controllerPort" type="long" dir="in">
4493	<desc>Port to attach the medium to.</desc>
4494	</param>
4495	<param name="device" type="long" dir="in">
4496	<desc>Device slot in the given port to attach the medium to.</desc>
4497	</param>
4498	<param name="medium" type="uuid" mod="string" dir="in">
4499	<desc>UUID of the medium to attach. A zero UUID means unmount the
4500	currently mounted medium.</desc>
4501	</param>
4502	<param name="force" type="boolean" dir="in">
4503	<desc>Allows to force unmount/mount of a medium which is locked by
4504	theDevice slot in the given port to attach the medium to.</desc>
4505	</param>
4506	</method>
4507
4508	<method name="getMedium" const="yes">
4509	<desc>
4510	Returns the virtual medium attached to a device slot of the specified
4511	bus.
4512
4513	Note that if the medium was indirectly attached by
4514	<link to="#mountMedium"/> to the given device slot then this
4515	method will return not the same object as passed to the
4516	<link to="#mountMedium"/> call. See <link to="IMedium"/> for
4517	more detailed information about mounting a medium.
4518
4519	<result name="VBOX_E_OBJECT_NOT_FOUND">
4520	No medium attached to given slot/bus.
4521	</result>
4522
4523	</desc>
4524	<param name="name" type="wstring" dir="in">
4525	<desc>Name of the storage controller the medium is attached to.</desc>
4526	</param>
4527	<param name="controllerPort" type="long" dir="in">
4528	<desc>Port to query.</desc>
4529	</param>
4530	<param name="device" type="long" dir="in">
4531	<desc>Device slot in the given port to query.</desc>
4532	</param>
4533	<param name="medium" type="IMedium" dir="return">
4534	<desc>Attached medium object.</desc>
4535	</param>
4536	</method>
4537
4538	<method name="getMediumAttachmentsOfController" const="yes">
4539	<desc>
4540	Returns an array of medium attachments which are attached to the
4541	the controller with the given name.
4542
4543	<result name="VBOX_E_OBJECT_NOT_FOUND">
4544	A storage controller with given name doesn't exist.
4545	</result>
4546	</desc>
4547	<param name="name" type="wstring" dir="in"/>
4548	<param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
4549	</method>
4550
4551	<method name="getMediumAttachment" const="yes">
4552	<desc>
4553	Returns a medium attachment which corresponds to the controller with
4554	the given name, on the given port and device slot.
4555
4556	<result name="VBOX_E_OBJECT_NOT_FOUND">
4557	No attachment exists for the given controller/port/device combination.
4558	</result>
4559	</desc>
4560	<param name="name" type="wstring" dir="in"/>
4561	<param name="controllerPort" type="long" dir="in"/>
4562	<param name="device" type="long" dir="in"/>
4563	<param name="attachment" type="IMediumAttachment" dir="return"/>
4564	</method>
4565
4566	<method name="getNetworkAdapter" const="yes">
4567	<desc>
4568	Returns the network adapter associated with the given slot.
4569	Slots are numbered sequentially, starting with zero. The total
4570	number of adapters per machine is defined by the
4571	<link to="ISystemProperties::networkAdapterCount"/> property,
4572	so the maximum slot number is one less than that property's value.
4573
4574	<result name="E_INVALIDARG">
4575	Invalid @a slot number.
4576	</result>
4577
4578	</desc>
4579	<param name="slot" type="unsigned long" dir="in"/>
4580	<param name="adapter" type="INetworkAdapter" dir="return"/>
4581	</method>
4582
4583	<method name="addStorageController">
4584	<desc>
4585	Adds a new storage controller (SCSI, SAS or SATA controller) to the
4586	machine and returns it as an instance of
4587	<link to="IStorageController" />.
4588
4589	@a name identifies the controller for subsequent calls such as
4590	<link to="#getStorageControllerByName" />,
4591	<link to="#getStorageControllerByInstance" />,
4592	<link to="#removeStorageController" />,
4593	<link to="#attachDevice" /> or <link to="#mountMedium" />.
4594
4595	After the controller has been added, you can set its exact
4596	type by setting the <link to="IStorageController::controllerType" />.
4597
4598	<result name="VBOX_E_OBJECT_IN_USE">
4599	A storage controller with given name exists already.
4600	</result>
4601	<result name="E_INVALIDARG">
4602	Invalid @a controllerType.
4603	</result>
4604	</desc>
4605	<param name="name" type="wstring" dir="in"/>
4606	<param name="connectionType" type="StorageBus" dir="in"/>
4607	<param name="controller" type="IStorageController" dir="return"/>
4608	</method>
4609
4610	<method name="getStorageControllerByName" const="yes">
4611	<desc>
4612	Returns a storage controller with the given name.
4613
4614	<result name="VBOX_E_OBJECT_NOT_FOUND">
4615	A storage controller with given name doesn't exist.
4616	</result>
4617	</desc>
4618	<param name="name" type="wstring" dir="in"/>
4619	<param name="storageController" type="IStorageController" dir="return"/>
4620	</method>
4621
4622	<method name="getStorageControllerByInstance" const="yes">
4623	<desc>
4624	Returns a storage controller with the given instance number.
4625
4626	<result name="VBOX_E_OBJECT_NOT_FOUND">
4627	A storage controller with given instance number doesn't exist.
4628	</result>
4629	</desc>
4630	<param name="instance" type="unsigned long" dir="in"/>
4631	<param name="storageController" type="IStorageController" dir="return"/>
4632	</method>
4633
4634	<method name="removeStorageController">
4635	<desc>
4636	Removes a storage controller from the machine.
4637
4638	<result name="VBOX_E_OBJECT_NOT_FOUND">
4639	A storage controller with given name doesn't exist.
4640	</result>
4641	</desc>
4642	<param name="name" type="wstring" dir="in"/>
4643	</method>
4644
4645	<method name="getSerialPort" const="yes">
4646	<desc>
4647	Returns the serial port associated with the given slot.
4648	Slots are numbered sequentially, starting with zero. The total
4649	number of serial ports per machine is defined by the
4650	<link to="ISystemProperties::serialPortCount"/> property,
4651	so the maximum slot number is one less than that property's value.
4652
4653	<result name="E_INVALIDARG">
4654	Invalid @a slot number.
4655	</result>
4656
4657	</desc>
4658	<param name="slot" type="unsigned long" dir="in"/>
4659	<param name="port" type="ISerialPort" dir="return"/>
4660	</method>
4661
4662	<method name="getParallelPort" const="yes">
4663	<desc>
4664	Returns the parallel port associated with the given slot.
4665	Slots are numbered sequentially, starting with zero. The total
4666	number of parallel ports per machine is defined by the
4667	<link to="ISystemProperties::parallelPortCount"/> property,
4668	so the maximum slot number is one less than that property's value.
4669
4670	<result name="E_INVALIDARG">
4671	Invalid @a slot number.
4672	</result>
4673
4674	</desc>
4675	<param name="slot" type="unsigned long" dir="in"/>
4676	<param name="port" type="IParallelPort" dir="return"/>
4677	</method>
4678
4679	<method name="getExtraDataKeys">
4680	<desc>
4681	Returns an array representing the machine-specific extra data keys
4682	which currently have values defined.
4683	</desc>
4684	<param name="value" type="wstring" dir="return" safearray="yes">
4685	<desc>Array of extra data keys.</desc>
4686	</param>
4687	</method>
4688
4689	<method name="getExtraData">
4690	<desc>
4691	Returns associated machine-specific extra data.
4692
4693	If the requested data @a key does not exist, this function will
4694	succeed and return an empty string in the @a value argument.
4695
4696	<result name="VBOX_E_FILE_ERROR">
4697	Settings file not accessible.
4698	</result>
4699	<result name="VBOX_E_XML_ERROR">
4700	Could not parse the settings file.
4701	</result>
4702
4703	</desc>
4704	<param name="key" type="wstring" dir="in">
4705	<desc>Name of the data key to get.</desc>
4706	</param>
4707	<param name="value" type="wstring" dir="return">
4708	<desc>Value of the requested data key.</desc>
4709	</param>
4710	</method>
4711
4712	<method name="setExtraData">
4713	<desc>
4714	Sets associated machine-specific extra data.
4715
4716	If you pass @c null or an empty string as a key @a value, the given
4717	@a key will be deleted.
4718
4719	<note>
4720	Before performing the actual data change, this method will ask all
4721	registered listeners using the
4722	<link to="IExtraDataCanChangeEvent"/>
4723	notification for a permission. If one of the listeners refuses the
4724	new value, the change will not be performed.
4725	</note>
4726	<note>
4727	On success, the
4728	<link to="IExtraDataChangedEvent"/> notification
4729	is called to inform all registered listeners about a successful data
4730	change.
4731	</note>
4732	<note>
4733	This method can be called outside the machine session and therefore
4734	it's a caller's responsibility to handle possible race conditions
4735	when several clients change the same key at the same time.
4736	</note>
4737
4738	<result name="VBOX_E_FILE_ERROR">
4739	Settings file not accessible.
4740	</result>
4741	<result name="VBOX_E_XML_ERROR">
4742	Could not parse the settings file.
4743	</result>
4744
4745	</desc>
4746	<param name="key" type="wstring" dir="in">
4747	<desc>Name of the data key to set.</desc>
4748	</param>
4749	<param name="value" type="wstring" dir="in">
4750	<desc>Value to assign to the key.</desc>
4751	</param>
4752	</method>
4753
4754	<method name="getCPUProperty" const="yes">
4755	<desc>
4756	Returns the virtual CPU boolean value of the specified property.
4757
4758	<result name="E_INVALIDARG">
4759	Invalid property.
4760	</result>
4761
4762	</desc>
4763	<param name="property" type="CPUPropertyType" dir="in">
4764	<desc>
4765	Property type to query.
4766	</desc>
4767	</param>
4768	<param name="value" type="boolean" dir="return">
4769	<desc>
4770	Property value.
4771	</desc>
4772	</param>
4773	</method>
4774
4775	<method name="setCPUProperty">
4776	<desc>
4777	Sets the virtual CPU boolean value of the specified property.
4778
4779	<result name="E_INVALIDARG">
4780	Invalid property.
4781	</result>
4782
4783	</desc>
4784	<param name="property" type="CPUPropertyType" dir="in">
4785	<desc>
4786	Property type to query.
4787	</desc>
4788	</param>
4789	<param name="value" type="boolean" dir="in">
4790	<desc>
4791	Property value.
4792	</desc>
4793	</param>
4794	</method>
4795
4796	<method name="getCPUIDLeaf" const="yes">
4797	<desc>
4798	Returns the virtual CPU cpuid information for the specified leaf.
4799
4800	Currently supported index values for cpuid:
4801	Standard CPUID leafs: 0 - 0xA
4802	Extended CPUID leafs: 0x80000000 - 0x8000000A
4803
4804	See the Intel and AMD programmer's manuals for detailed information
4805	about the cpuid instruction and its leafs.
4806	<result name="E_INVALIDARG">
4807	Invalid id.
4808	</result>
4809
4810	</desc>
4811	<param name="id" type="unsigned long" dir="in">
4812	<desc>
4813	CPUID leaf index.
4814	</desc>
4815	</param>
4816	<param name="valEax" type="unsigned long" dir="out">
4817	<desc>
4818	CPUID leaf value for register eax.
4819	</desc>
4820	</param>
4821	<param name="valEbx" type="unsigned long" dir="out">
4822	<desc>
4823	CPUID leaf value for register ebx.
4824	</desc>
4825	</param>
4826	<param name="valEcx" type="unsigned long" dir="out">
4827	<desc>
4828	CPUID leaf value for register ecx.
4829	</desc>
4830	</param>
4831	<param name="valEdx" type="unsigned long" dir="out">
4832	<desc>
4833	CPUID leaf value for register edx.
4834	</desc>
4835	</param>
4836	</method>
4837
4838	<method name="setCPUIDLeaf">
4839	<desc>
4840	Sets the virtual CPU cpuid information for the specified leaf. Note that these values
4841	are not passed unmodified. VirtualBox clears features that it doesn't support.
4842
4843	Currently supported index values for cpuid:
4844	Standard CPUID leafs: 0 - 0xA
4845	Extended CPUID leafs: 0x80000000 - 0x8000000A
4846
4847	See the Intel and AMD programmer's manuals for detailed information
4848	about the cpuid instruction and its leafs.
4849
4850	Do not use this method unless you know exactly what you're doing. Misuse can lead to
4851	random crashes inside VMs.
4852	<result name="E_INVALIDARG">
4853	Invalid id.
4854	</result>
4855
4856	</desc>
4857	<param name="id" type="unsigned long" dir="in">
4858	<desc>
4859	CPUID leaf index.
4860	</desc>
4861	</param>
4862	<param name="valEax" type="unsigned long" dir="in">
4863	<desc>
4864	CPUID leaf value for register eax.
4865	</desc>
4866	</param>
4867	<param name="valEbx" type="unsigned long" dir="in">
4868	<desc>
4869	CPUID leaf value for register ebx.
4870	</desc>
4871	</param>
4872	<param name="valEcx" type="unsigned long" dir="in">
4873	<desc>
4874	CPUID leaf value for register ecx.
4875	</desc>
4876	</param>
4877	<param name="valEdx" type="unsigned long" dir="in">
4878	<desc>
4879	CPUID leaf value for register edx.
4880	</desc>
4881	</param>
4882	</method>
4883
4884	<method name="removeCPUIDLeaf">
4885	<desc>
4886	Removes the virtual CPU cpuid leaf for the specified index
4887
4888	<result name="E_INVALIDARG">
4889	Invalid id.
4890	</result>
4891
4892	</desc>
4893	<param name="id" type="unsigned long" dir="in">
4894	<desc>
4895	CPUID leaf index.
4896	</desc>
4897	</param>
4898	</method>
4899
4900	<method name="removeAllCPUIDLeaves">
4901	<desc>
4902	Removes all the virtual CPU cpuid leaves
4903	</desc>
4904	</method>
4905
4906	<method name="getHWVirtExProperty" const="yes">
4907	<desc>
4908	Returns the value of the specified hardware virtualization boolean property.
4909
4910	<result name="E_INVALIDARG">
4911	Invalid property.
4912	</result>
4913
4914	</desc>
4915	<param name="property" type="HWVirtExPropertyType" dir="in">
4916	<desc>
4917	Property type to query.
4918	</desc>
4919	</param>
4920	<param name="value" type="boolean" dir="return">
4921	<desc>
4922	Property value.
4923	</desc>
4924	</param>
4925	</method>
4926
4927	<method name="setHWVirtExProperty">
4928	<desc>
4929	Sets a new value for the specified hardware virtualization boolean property.
4930
4931	<result name="E_INVALIDARG">
4932	Invalid property.
4933	</result>
4934
4935	</desc>
4936	<param name="property" type="HWVirtExPropertyType" dir="in">
4937	<desc>
4938	Property type to set.
4939	</desc>
4940	</param>
4941	<param name="value" type="boolean" dir="in">
4942	<desc>
4943	New property value.
4944	</desc>
4945	</param>
4946	</method>
4947
4948	<method name="saveSettings">
4949	<desc>
4950	Saves any changes to machine settings made since the session
4951	has been opened or a new machine has been created, or since the
4952	last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
4953	For registered machines, new settings become visible to all
4954	other VirtualBox clients after successful invocation of this
4955	method.
4956	<note>
4957	The method sends <link to="IMachineDataChangedEvent"/>
4958	notification event after the configuration has been successfully
4959	saved (only for registered machines).
4960	</note>
4961	<note>
4962	Calling this method is only valid on instances returned
4963	by <link to="ISession::machine"/> and on new machines
4964	created by <link to="IVirtualBox::createMachine"/> but not
4965	yet registered, or on unregistered machines after calling
4966	<link to="IMachine::unregister"/>.
4967	</note>
4968
4969	<result name="VBOX_E_FILE_ERROR">
4970	Settings file not accessible.
4971	</result>
4972	<result name="VBOX_E_XML_ERROR">
4973	Could not parse the settings file.
4974	</result>
4975	<result name="E_ACCESSDENIED">
4976	Modification request refused.
4977	</result>
4978
4979	</desc>
4980	</method>
4981
4982	<method name="discardSettings">
4983	<desc>
4984	Discards any changes to the machine settings made since the session
4985	has been opened or since the last call to <link to="#saveSettings"/>
4986	or <link to="#discardSettings"/>.
4987	<note>
4988	Calling this method is only valid on instances returned
4989	by <link to="ISession::machine"/> and on new machines
4990	created by <link to="IVirtualBox::createMachine"/> or
4991	opened by <link to="IVirtualBox::openMachine"/> but not
4992	yet registered, or on unregistered machines after calling
4993	<link to="IMachine::unregister"/>.
4994	</note>
4995
4996	<result name="VBOX_E_INVALID_VM_STATE">
4997	Virtual machine is not mutable.
4998	</result>
4999
5000	</desc>
5001	</method>
5002
5003	<method name="unregister">
5004	<desc>
5005	Unregisters the machine, which must have been previously registered using
5006	<link to="IVirtualBox::registerMachine"/>, and optionally do additional
5007	cleanup before the machine is unregistered.
5008
5009	This method does not delete any files. It only changes the machine configuration and
5010	the list of registered machines in the VirtualBox object. To delete the files which
5011	belonged to the machine, including the XML file of the machine itself, call
5012	<link to="#delete"/>, optionally with the array of IMedium objects which was returned
5013	from this method.
5014
5015	How thoroughly this method cleans up the machine configuration before unregistering
5016	the machine depends on the @a cleanupMode argument.
5017
5018	<ul>
5019	<li>With "UnregisterOnly", the machine will only be unregistered, but no additional
5020	cleanup will be performed. The call will fail if the machine is in "Saved" state
5021	or has any snapshots or any media attached (see <link to="IMediumAttachment" />.
5022	It is the responsibility of the caller to delete all such configuration in this mode.
5023	In this mode, the API behaves like the former @c IVirtualBox::unregisterMachine() API
5024	which it replaces.</li>
5025	<li>With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved"
5026	state or if it has snapshots or media attached. All media attached to the current machine
5027	state or in snapshots will be detached. No medium objects will be returned; all of the
5028	machine's media will remain open.</li>
5029	<li>With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone",
5030	except that all the hard disk medium objects which were detached from the machine will
5031	be returned as an array. This allows for quickly passing them to the <link to="#delete" />
5032	API for closing and deletion.</li>
5033	<li>With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except
5034	that all media will be returned in the array, including removeable media like DVDs and
5035	floppies. This might be useful if the user wants to inspect in detail which media were
5036	attached to the machine. Be careful when passing the media array to <link to="#delete" />
5037	in that case because users will typically want to preserve ISO and RAW image files.</li>
5038	</ul>
5039
5040	This API does not verify whether the media files returned in the array are still
5041	attached to other machines (i.e. shared between several machines). If such a shared
5042	image is passed to <link to="#delete" /> however, closing the image will fail there
5043	and the image will be silently skipped.
5044
5045	A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the
5046	resulting IMedia array to <link to="#delete"/>. This way, the machine is completely
5047	deleted with all its saved states and hard disk images, but images for removeable
5048	drives (such as ISO and RAW files) will remain on disk.
5049
5050	The call will fail if the machine is currently locked (see <link to="ISession" />).
5051	It implicitly calls <link to="#saveSettings"/> to save all current machine settings
5052	before unregistering it.
5053
5054	After successful method invocation, the <link to="IMachineRegisteredEvent"/> event
5055	is fired.
5056
5057	<note>
5058	If the given machine is inaccessible (see <link to="#accessible"/>), it
5059	will be unregistered and fully uninitialized right afterwards. As a result,
5060	the returned machine object will be unusable and an attempt to call
5061	<b>any</b> method will return the "Object not ready" error.
5062	</note>
5063
5064	<result name="VBOX_E_INVALID_OBJECT_STATE">
5065	Machine is currently locked for a session.
5066	</result>
5067	</desc>
5068
5069	<param name="cleanupMode" type="CleanupMode" dir="in">
5070	<desc>How to clean up after the machine has been unregistered.</desc>
5071	</param>
5072	<param name="aMedia" type="IMedium" safearray="yes" dir="return">
5073	<desc>List of media detached from the machine, depending on the @a cleanupMode parameter.</desc>
5074	</param>
5075	</method>
5076
5077	<method name="delete">
5078	<desc>
5079	Deletes the files associated with this machine from disk. If medium objects are passed
5080	in with the @a aMedia argument, they are closed and, if closing was succesful, their
5081	storage files are deleted as well. For convenience, this array of media files can be
5082	the same as the one returned from a previous <link to="#unregister" /> call.
5083
5084	This method must only be called on machines which are either write-locked (i.e. on instances
5085	returned by <link to="ISession::machine"/>) or on unregistered machines (i.e. not yet
5086	registered machines created by <link to="IVirtualBox::createMachine"/> or opened by
5087	<link to="IVirtualBox::openMachine"/>, or after having called <link to="#unregister"/>).
5088
5089	The following files will be deleted by this method:
5090	<ul>
5091	<li>If <link to="#unregister" /> had been previously called with a @a cleanupMode
5092	argument other than "UnregisterOnly", this will delete all saved state files that
5093	the machine had in use; possibly one if the machine was in "Saved" state and one
5094	for each online snapshot that the machine had.</li>
5095	<li>On each medium object passed in the @a aMedia array, this will call
5096	<link to="IMedium::close" />. If that succeeds, this will attempt to delete the
5097	medium's storage on disk. Since the close() call will fail if the medium is still
5098	in use, e.g. because it is still attached to a second machine; in that case the
5099	storage will not be deleted.</li>
5100	<li>Finally, the machine's own XML file will be deleted.</li>
5101	</ul>
5102
5103	Since deleting large disk image files can be a time-consuming I/O operation, this
5104	method operates asynchronously and returns an IProgress object to allow the caller
5105	to monitor the progress. There will be one sub-operation for each file that is
5106	being deleted (saved state or medium storage file).
5107
5108	<note>
5109	<link to="#settingsModified"/> will return @c true after this
5110	method successfully returns.
5111	</note>
5112
5113	<result name="VBOX_E_INVALID_VM_STATE">
5114	Machine is registered but not write-locked.
5115	</result>
5116	<result name="VBOX_E_IPRT_ERROR">
5117	Could not delete the settings file.
5118	</result>
5119	</desc>
5120	<param name="aMedia" type="IMedium" safearray="yes" dir="in">
5121	<desc>List of media to be closed and whose storage files will be deleted.</desc>
5122	</param>
5123	<param name="aProgress" type="IProgress" dir="return">
5124	<desc>Progress object to track the operation completion.</desc>
5125	</param>
5126	</method>
5127
5128	<method name="export">
5129	<desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
5130	steps required to export VirtualBox machines to OVF.
5131	</desc>
5132
5133	<param name="aAppliance" type="IAppliance" dir="in">
5134	<desc>Appliance to export this machine to.</desc>
5135	</param>
5136	<param name="aDescription" type="IVirtualSystemDescription" dir="return">
5137	<desc>VirtualSystemDescription object which is created for this machine.</desc>
5138	</param>
5139	</method >
5140
5141	<method name="getSnapshot">
5142	<desc>
5143	Returns a snapshot of this machine with the given UUID.
5144	A @c null UUID can be used to obtain the first snapshot
5145	taken on this machine. This is useful if you want to traverse
5146	the whole tree of snapshots starting from the root.
5147
5148	<result name="VBOX_E_OBJECT_NOT_FOUND">
5149	Virtual machine has no snapshots or snapshot not found.
5150	</result>
5151
5152	</desc>
5153	<param name="id" type="uuid" mod="string" dir="in">
5154	<desc>UUID of the snapshot to get</desc>
5155	</param>
5156	<param name="snapshot" type="ISnapshot" dir="return">
5157	<desc>Snapshot object with the given UUID.</desc>
5158	</param>
5159	</method>
5160
5161	<method name="findSnapshot">
5162	<desc>
5163	Returns a snapshot of this machine with the given name.
5164
5165	<result name="VBOX_E_OBJECT_NOT_FOUND">
5166	Virtual machine has no snapshots or snapshot not found.
5167	</result>
5168
5169	</desc>
5170	<param name="name" type="wstring" dir="in">
5171	<desc>Name of the snapshot to find</desc>
5172	</param>
5173	<param name="snapshot" type="ISnapshot" dir="return">
5174	<desc>Snapshot object with the given name.</desc>
5175	</param>
5176	</method>
5177
5178	<method name="setCurrentSnapshot">
5179	<desc>
5180	Sets the current snapshot of this machine.
5181	<note>
5182	In the current implementation, this operation is not
5183	implemented.
5184	</note>
5185	</desc>
5186	<param name="id" type="uuid" mod="string" dir="in">
5187	<desc>UUID of the snapshot to set as the current snapshot.</desc>
5188	</param>
5189	</method>
5190
5191	<method name="createSharedFolder">
5192	<desc>
5193	Creates a new permanent shared folder by associating the given logical
5194	name with the given host path, adds it to the collection of shared
5195	folders and starts sharing it. Refer to the description of
5196	<link to="ISharedFolder"/> to read more about logical names.
5197
5198	<result name="VBOX_E_OBJECT_IN_USE">
5199	Shared folder already exists.
5200	</result>
5201	<result name="VBOX_E_FILE_ERROR">
5202	Shared folder @a hostPath not accessible.
5203	</result>
5204
5205	</desc>
5206	<param name="name" type="wstring" dir="in">
5207	<desc>Unique logical name of the shared folder.</desc>
5208	</param>
5209	<param name="hostPath" type="wstring" dir="in">
5210	<desc>Full path to the shared folder in the host file system.</desc>
5211	</param>
5212	<param name="writable" type="boolean" dir="in">
5213	<desc>Whether the share is writable or readonly.</desc>
5214	</param>
5215	<param name="automount" type="boolean" dir="in">
5216	<desc>Whether the share gets automatically mounted by the guest
5217	or not.</desc>
5218	</param>
5219	</method>
5220
5221	<method name="removeSharedFolder">
5222	<desc>
5223	Removes the permanent shared folder with the given name previously
5224	created by <link to="#createSharedFolder"/> from the collection of
5225	shared folders and stops sharing it.
5226
5227	<result name="VBOX_E_INVALID_VM_STATE">
5228	Virtual machine is not mutable.
5229	</result>
5230	<result name="VBOX_E_OBJECT_NOT_FOUND">
5231	Shared folder @a name does not exist.
5232	</result>
5233
5234	</desc>
5235	<param name="name" type="wstring" dir="in">
5236	<desc>Logical name of the shared folder to remove.</desc>
5237	</param>
5238	</method>
5239
5240	<method name="canShowConsoleWindow">
5241	<desc>
5242	Returns @c true if the VM console process can activate the
5243	console window and bring it to foreground on the desktop of
5244	the host PC.
5245	<note>
5246	This method will fail if a session for this machine is not
5247	currently open.
5248	</note>
5249
5250	<result name="VBOX_E_INVALID_VM_STATE">
5251	Machine session is not open.
5252	</result>
5253
5254	</desc>
5255	<param name="canShow" type="boolean" dir="return">
5256	<desc>
5257	@c true if the console window can be shown and @c false otherwise.
5258	</desc>
5259	</param>
5260	</method>
5261
5262	<method name="showConsoleWindow">
5263	<desc>
5264	Activates the console window and brings it to foreground on
5265	the desktop of the host PC. Many modern window managers on
5266	many platforms implement some sort of focus stealing
5267	prevention logic, so that it may be impossible to activate
5268	a window without the help of the currently active
5269	application. In this case, this method will return a non-zero
5270	identifier that represents the top-level window of the VM
5271	console process. The caller, if it represents a currently
5272	active process, is responsible to use this identifier (in a
5273	platform-dependent manner) to perform actual window
5274	activation.
5275	<note>
5276	This method will fail if a session for this machine is not
5277	currently open.
5278	</note>
5279
5280	<result name="VBOX_E_INVALID_VM_STATE">
5281	Machine session is not open.
5282	</result>
5283
5284	</desc>
5285	<param name="winId" type="unsigned long long" dir="return">
5286	<desc>
5287	Platform-dependent identifier of the top-level VM console
5288	window, or zero if this method has performed all actions
5289	necessary to implement the <i>show window</i> semantics for
5290	the given platform and/or VirtualBox front-end.
5291	</desc>
5292	</param>
5293	</method>
5294
5295	<method name="getGuestProperty" const="yes">
5296	<desc>
5297	Reads an entry from the machine's guest property store.
5298
5299	<result name="VBOX_E_INVALID_VM_STATE">
5300	Machine session is not open.
5301	</result>
5302
5303	</desc>
5304	<param name="name" type="wstring" dir="in">
5305	<desc>
5306	The name of the property to read.
5307	</desc>
5308	</param>
5309	<param name="value" type="wstring" dir="out">
5310	<desc>
5311	The value of the property. If the property does not exist then this
5312	will be empty.
5313	</desc>
5314	</param>
5315	<param name="timestamp" type="unsigned long long" dir="out">
5316	<desc>
5317	The time at which the property was last modified, as seen by the
5318	server process.
5319	</desc>
5320	</param>
5321	<param name="flags" type="wstring" dir="out">
5322	<desc>
5323	Additional property parameters, passed as a comma-separated list of
5324	"name=value" type entries.
5325	</desc>
5326	</param>
5327	</method>
5328
5329	<method name="getGuestPropertyValue" const="yes">
5330	<desc>
5331	Reads a value from the machine's guest property store.
5332
5333	<result name="VBOX_E_INVALID_VM_STATE">
5334	Machine session is not open.
5335	</result>
5336
5337	</desc>
5338	<param name="property" type="wstring" dir="in">
5339	<desc>
5340	The name of the property to read.
5341	</desc>
5342	</param>
5343	<param name="value" type="wstring" dir="return">
5344	<desc>
5345	The value of the property. If the property does not exist then this
5346	will be empty.
5347	</desc>
5348	</param>
5349	</method>
5350
5351	<method name="getGuestPropertyTimestamp" const="yes">
5352	<desc>
5353	Reads a property timestamp from the machine's guest property store.
5354
5355	<result name="VBOX_E_INVALID_VM_STATE">
5356	Machine session is not open.
5357	</result>
5358
5359	</desc>
5360	<param name="property" type="wstring" dir="in">
5361	<desc>
5362	The name of the property to read.
5363	</desc>
5364	</param>
5365	<param name="value" type="unsigned long long" dir="return">
5366	<desc>
5367	The timestamp. If the property does not exist then this will be
5368	empty.
5369	</desc>
5370	</param>
5371	</method>
5372
5373	<method name="setGuestProperty">
5374	<desc>
5375	Sets, changes or deletes an entry in the machine's guest property
5376	store.
5377
5378	<result name="E_ACCESSDENIED">
5379	Property cannot be changed.
5380	</result>
5381	<result name="E_INVALIDARG">
5382	Invalid @a flags.
5383	</result>
5384	<result name="VBOX_E_INVALID_VM_STATE">
5385	Virtual machine is not mutable or session not open.
5386	</result>
5387	<result name="VBOX_E_INVALID_OBJECT_STATE">
5388	Cannot set transient property when machine not running.
5389	</result>
5390
5391	</desc>
5392	<param name="property" type="wstring" dir="in">
5393	<desc>
5394	The name of the property to set, change or delete.
5395	</desc>
5396	</param>
5397	<param name="value" type="wstring" dir="in">
5398	<desc>
5399	The new value of the property to set, change or delete. If the
5400	property does not yet exist and value is non-empty, it will be
5401	created. If the value is @c null or empty, the property will be
5402	deleted if it exists.
5403	</desc>
5404	</param>
5405	<param name="flags" type="wstring" dir="in">
5406	<desc>
5407	Additional property parameters, passed as a comma-separated list of
5408	"name=value" type entries.
5409	</desc>
5410	</param>
5411	</method>
5412
5413	<method name="setGuestPropertyValue">
5414	<desc>
5415	Sets, changes or deletes a value in the machine's guest property
5416	store. The flags field will be left unchanged or created empty for a
5417	new property.
5418
5419	<result name="E_ACCESSDENIED">
5420	Property cannot be changed.
5421	</result>
5422	<result name="VBOX_E_INVALID_VM_STATE">
5423	Virtual machine is not mutable or session not open.
5424	</result>
5425	<result name="VBOX_E_INVALID_OBJECT_STATE">
5426	Cannot set transient property when machine not running.
5427	</result>
5428	</desc>
5429
5430	<param name="property" type="wstring" dir="in">
5431	<desc>
5432	The name of the property to set, change or delete.
5433	</desc>
5434	</param>
5435	<param name="value" type="wstring" dir="in">
5436	<desc>
5437	The new value of the property to set, change or delete. If the
5438	property does not yet exist and value is non-empty, it will be
5439	created. If the value is @c null or empty, the property will be
5440	deleted if it exists.
5441	</desc>
5442	</param>
5443	</method>
5444
5445	<method name="enumerateGuestProperties">
5446	<desc>
5447	Return a list of the guest properties matching a set of patterns along
5448	with their values, time stamps and flags.
5449	</desc>
5450	<param name="patterns" type="wstring" dir="in">
5451	<desc>
5452	The patterns to match the properties against, separated by '\|'
5453	characters. If this is empty or @c null, all properties will match.
5454	</desc>
5455	</param>
5456	<param name="name" type="wstring" dir="out" safearray="yes">
5457	<desc>
5458	The names of the properties returned.
5459	</desc>
5460	</param>
5461	<param name="value" type="wstring" dir="out" safearray="yes">
5462	<desc>
5463	The values of the properties returned. The array entries match the
5464	corresponding entries in the @a name array.
5465	</desc>
5466	</param>
5467	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
5468	<desc>
5469	The time stamps of the properties returned. The array entries match
5470	the corresponding entries in the @a name array.
5471	</desc>
5472	</param>
5473	<param name="flags" type="wstring" dir="out" safearray="yes">
5474	<desc>
5475	The flags of the properties returned. The array entries match the
5476	corresponding entries in the @a name array.
5477	</desc>
5478	</param>
5479	</method>
5480
5481	<method name="querySavedThumbnailSize">
5482	<desc>
5483	Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
5484	</desc>
5485	<param name="screenId" type="unsigned long" dir="in">
5486	<desc>
5487	Saved guest screen to query info from.
5488	</desc>
5489	</param>
5490	<param name="size" type="unsigned long" dir="out">
5491	<desc>
5492	Size of buffer required to store the bitmap.
5493	</desc>
5494	</param>
5495	<param name="width" type="unsigned long" dir="out">
5496	<desc>
5497	Bitmap width.
5498	</desc>
5499	</param>
5500	<param name="height" type="unsigned long" dir="out">
5501	<desc>
5502	Bitmap height.
5503	</desc>
5504	</param>
5505	</method>
5506
5507	<method name="readSavedThumbnailToArray">
5508	<desc>
5509	Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
5510	</desc>
5511	<param name="screenId" type="unsigned long" dir="in">
5512	<desc>
5513	Saved guest screen to read from.
5514	</desc>
5515	</param>
5516	<param name="BGR" type="boolean" dir="in">
5517	<desc>
5518	How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
5519	bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
5520	</desc>
5521	</param>
5522	<param name="width" type="unsigned long" dir="out">
5523	<desc>
5524	Bitmap width.
5525	</desc>
5526	</param>
5527	<param name="height" type="unsigned long" dir="out">
5528	<desc>
5529	Bitmap height.
5530	</desc>
5531	</param>
5532	<param name="data" type="octet" dir="return" safearray="yes">
5533	<desc>
5534	Array with resulting bitmap data.
5535	</desc>
5536	</param>
5537	</method>
5538
5539	<method name="querySavedScreenshotPNGSize">
5540	<desc>
5541	Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
5542	</desc>
5543	<param name="screenId" type="unsigned long" dir="in">
5544	<desc>
5545	Saved guest screen to query info from.
5546	</desc>
5547	</param>
5548	<param name="size" type="unsigned long" dir="out">
5549	<desc>
5550	Size of buffer required to store the PNG binary data.
5551	</desc>
5552	</param>
5553	<param name="width" type="unsigned long" dir="out">
5554	<desc>
5555	Image width.
5556	</desc>
5557	</param>
5558	<param name="height" type="unsigned long" dir="out">
5559	<desc>
5560	Image height.
5561	</desc>
5562	</param>
5563	</method>
5564
5565	<method name="readSavedScreenshotPNGToArray">
5566	<desc>
5567	Screenshot in PNG format is retrieved to an array of bytes.
5568	</desc>
5569	<param name="screenId" type="unsigned long" dir="in">
5570	<desc>
5571	Saved guest screen to read from.
5572	</desc>
5573	</param>
5574	<param name="width" type="unsigned long" dir="out">
5575	<desc>
5576	Image width.
5577	</desc>
5578	</param>
5579	<param name="height" type="unsigned long" dir="out">
5580	<desc>
5581	Image height.
5582	</desc>
5583	</param>
5584	<param name="data" type="octet" dir="return" safearray="yes">
5585	<desc>
5586	Array with resulting PNG data.
5587	</desc>
5588	</param>
5589	</method>
5590
5591	<method name="hotPlugCPU">
5592	<desc>
5593	Plugs a CPU into the machine.
5594	</desc>
5595	<param name="cpu" type="unsigned long" dir="in">
5596	<desc>
5597	The CPU id to insert.
5598	</desc>
5599	</param>
5600	</method>
5601
5602	<method name="hotUnplugCPU">
5603	<desc>
5604	Removes a CPU from the machine.
5605	</desc>
5606	<param name="cpu" type="unsigned long" dir="in">
5607	<desc>
5608	The CPU id to remove.
5609	</desc>
5610	</param>
5611	</method>
5612
5613	<method name="getCPUStatus">
5614	<desc>
5615	Returns the current status of the given CPU.
5616	</desc>
5617	<param name="cpu" type="unsigned long" dir="in">
5618	<desc>
5619	The CPU id to check for.
5620	</desc>
5621	</param>
5622	<param name="attached" type="boolean" dir="return">
5623	<desc>
5624	Status of the CPU.
5625	</desc>
5626	</param>
5627	</method>
5628
5629	<method name="queryLogFilename">
5630	<desc>
5631	Queries for the VM log file name of an given index. Returns an empty
5632	string if a log file with that index doesn't exists.
5633	</desc>
5634	<param name="idx" type="unsigned long" dir="in">
5635	<desc>
5636	Which log file name to query. 0=current log file.
5637	</desc>
5638	</param>
5639	<param name="filename" type="wstring" dir="return">
5640	<desc>
5641	On return the full path to the log file or an empty string on error.
5642	</desc>
5643	</param>
5644	</method>
5645
5646	<method name="readLog">
5647	<desc>
5648	Reads the VM log file. The chunk size is limited, so even if you
5649	ask for a big piece there might be less data returned.
5650	</desc>
5651	<param name="idx" type="unsigned long" dir="in">
5652	<desc>
5653	Which log file to read. 0=current log file.
5654	</desc>
5655	</param>
5656	<param name="offset" type="unsigned long long" dir="in">
5657	<desc>
5658	Offset in the log file.
5659	</desc>
5660	</param>
5661	<param name="size" type="unsigned long long" dir="in">
5662	<desc>
5663	Chunk size to read in the log file.
5664	</desc>
5665	</param>
5666	<param name="data" type="octet" dir="return" safearray="yes">
5667	<desc>
5668	Data read from the log file. A data size of 0 means end of file
5669	if the requested chunk size was not 0. This is the unprocessed
5670	file data, i.e. the line ending style depends on the platform of
5671	the system the server is running on.
5672	</desc>
5673	</param>
5674	</method>
5675	</interface>
5676
5677	<!--
5678	// IConsole
5679	/////////////////////////////////////////////////////////////////////////
5680	-->
5681
5682	<interface
5683	name="IRemoteDisplayInfo" extends="$unknown"
5684	uuid="b3741084-806f-4c3b-8c42-ebad1a81e45a"
5685	wsmap="struct"
5686	>
5687	<desc>
5688	Contains information about the remote display (VRDP) capabilities and status.
5689	This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
5690	</desc>
5691
5692	<attribute name="active" type="boolean" readonly="yes">
5693	<desc>
5694	Whether the remote display connection is active.
5695	</desc>
5696	</attribute>
5697
5698	<attribute name="port" type="long" readonly="yes">
5699	<desc>
5700	VRDP server port number. If this property is equal to <tt>0</tt>, then
5701	the VRDP server failed to start, usually because there are no free TCP
5702	ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDP
5703	server has not yet been started.
5704	</desc>
5705	</attribute>
5706
5707	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
5708	<desc>
5709	How many times a client connected.
5710	</desc>
5711	</attribute>
5712
5713	<attribute name="beginTime" type="long long" readonly="yes">
5714	<desc>
5715	When the last connection was established, in milliseconds since 1970-01-01 UTC.
5716	</desc>
5717	</attribute>
5718
5719	<attribute name="endTime" type="long long" readonly="yes">
5720	<desc>
5721	When the last connection was terminated or the current time, if
5722	connection is still active, in milliseconds since 1970-01-01 UTC.
5723	</desc>
5724	</attribute>
5725
5726	<attribute name="bytesSent" type="unsigned long long" readonly="yes">
5727	<desc>
5728	How many bytes were sent in last or current, if still active, connection.
5729	</desc>
5730	</attribute>
5731
5732	<attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
5733	<desc>
5734	How many bytes were sent in all connections.
5735	</desc>
5736	</attribute>
5737
5738	<attribute name="bytesReceived" type="unsigned long long" readonly="yes">
5739	<desc>
5740	How many bytes were received in last or current, if still active, connection.
5741	</desc>
5742	</attribute>
5743
5744	<attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
5745	<desc>
5746	How many bytes were received in all connections.
5747	</desc>
5748	</attribute>
5749
5750	<attribute name="user" type="wstring" readonly="yes">
5751	<desc>
5752	Login user name supplied by the client.
5753	</desc>
5754	</attribute>
5755
5756	<attribute name="domain" type="wstring" readonly="yes">
5757	<desc>
5758	Login domain name supplied by the client.
5759	</desc>
5760	</attribute>
5761
5762	<attribute name="clientName" type="wstring" readonly="yes">
5763	<desc>
5764	The client name supplied by the client.
5765	</desc>
5766	</attribute>
5767
5768	<attribute name="clientIP" type="wstring" readonly="yes">
5769	<desc>
5770	The IP address of the client.
5771	</desc>
5772	</attribute>
5773
5774	<attribute name="clientVersion" type="unsigned long" readonly="yes">
5775	<desc>
5776	The client software version number.
5777	</desc>
5778	</attribute>
5779
5780	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
5781	<desc>
5782	Public key exchange method used when connection was established.
5783	Values: 0 - RDP4 public key exchange scheme.
5784	1 - X509 certificates were sent to client.
5785	</desc>
5786	</attribute>
5787
5788	</interface>
5789
5790	<interface
5791	name="IConsole" extends="$unknown"
5792	uuid="03cb7897-ea17-4e6c-81ae-4bd90be2fde2"
5793	wsmap="managed"
5794	>
5795	<desc>
5796	The IConsole interface represents an interface to control virtual
5797	machine execution.
5798
5799	A console object gets created when a machine has been locked for a
5800	particular session (client process) using <link to="IMachine::lockMachine" />
5801	or <link to="IMachine::launchVMProcess"/>. The console object can
5802	then be found in the session's <link to="ISession::console" /> attribute.
5803
5804	Methods of the IConsole interface allow the caller to query the current
5805	virtual machine execution state, pause the machine or power it down, save
5806	the machine state or take a snapshot, attach and detach removable media
5807	and so on.
5808
5809	<see>ISession</see>
5810	</desc>
5811
5812	<attribute name="machine" type="IMachine" readonly="yes">
5813	<desc>
5814	Machine object this console is sessioned with.
5815	<note>
5816	This is a convenience property, it has the same value as
5817	<link to="ISession::machine"/> of the corresponding session
5818	object.
5819	</note>
5820	</desc>
5821	</attribute>
5822
5823	<attribute name="state" type="MachineState" readonly="yes">
5824	<desc>
5825	Current execution state of the machine.
5826	<note>
5827	This property always returns the same value as the corresponding
5828	property of the IMachine object this console is sessioned with.
5829	For the process that owns (executes) the VM, this is the
5830	preferable way of querying the VM state, because no IPC
5831	calls are made.
5832	</note>
5833	</desc>
5834	</attribute>
5835
5836	<attribute name="guest" type="IGuest" readonly="yes">
5837	<desc>Guest object.</desc>
5838	</attribute>
5839
5840	<attribute name="keyboard" type="IKeyboard" readonly="yes">
5841	<desc>
5842	Virtual keyboard object.
5843	<note>
5844	If the machine is not running, any attempt to use
5845	the returned object will result in an error.
5846	</note>
5847	</desc>
5848	</attribute>
5849
5850	<attribute name="mouse" type="IMouse" readonly="yes">
5851	<desc>
5852	Virtual mouse object.
5853	<note>
5854	If the machine is not running, any attempt to use
5855	the returned object will result in an error.
5856	</note>
5857	</desc>
5858	</attribute>
5859
5860	<attribute name="display" type="IDisplay" readonly="yes">
5861	<desc>Virtual display object.
5862	<note>
5863	If the machine is not running, any attempt to use
5864	the returned object will result in an error.
5865	</note>
5866	</desc>
5867	</attribute>
5868
5869	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
5870	<desc>Debugging interface.</desc>
5871	</attribute>
5872
5873	<attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
5874	<desc>
5875	Collection of USB devices currently attached to the virtual
5876	USB controller.
5877	<note>
5878	The collection is empty if the machine is not running.
5879	</note>
5880	</desc>
5881	</attribute>
5882
5883	<attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
5884	<desc>
5885	List of USB devices currently attached to the remote VRDP client.
5886	Once a new device is physically attached to the remote host computer,
5887	it appears in this list and remains there until detached.
5888	</desc>
5889	</attribute>
5890
5891	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
5892	<desc>
5893	Collection of shared folders for the current session. These folders
5894	are called transient shared folders because they are available to the
5895	guest OS running inside the associated virtual machine only for the
5896	duration of the session (as opposed to
5897	<link to="IMachine::sharedFolders"/> which represent permanent shared
5898	folders). When the session is closed (e.g. the machine is powered down),
5899	these folders are automatically discarded.
5900
5901	New shared folders are added to the collection using
5902	<link to="#createSharedFolder"/>. Existing shared folders can be
5903	removed using <link to="#removeSharedFolder"/>.
5904	</desc>
5905	</attribute>
5906
5907	<attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
5908	<desc>
5909	Interface that provides information on Remote Display (VRDP) connection.
5910	</desc>
5911	</attribute>
5912
5913	<attribute name="eventSource" type="IEventSource" readonly="yes">
5914	<desc>
5915	Event source for console events.
5916	</desc>
5917	</attribute>
5918
5919	<method name="powerUp">
5920	<desc>
5921	Starts the virtual machine execution using the current machine
5922	state (that is, its current execution state, current settings and
5923	current storage devices).
5924
5925	<note>
5926	This method is only useful for front-ends that want to actually
5927	execute virtual machines in their own process (like the VirtualBox
5928	or VBoxSDL front-ends). Unless you are intending to write such a
5929	front-end, do not call this method. If you simply want to
5930	start virtual machine execution using one of the existing front-ends
5931	(for example the VirtualBox GUI or headless server), use
5932	<link to="IMachine::launchVMProcess"/> instead; these
5933	front-ends will power up the machine automatically for you.
5934	</note>
5935
5936	If the machine is powered off or aborted, the execution will
5937	start from the beginning (as if the real hardware were just
5938	powered on).
5939
5940	If the machine is in the <link to="MachineState_Saved"/> state,
5941	it will continue its execution the point where the state has
5942	been saved.
5943
5944	If the machine <link to="IMachine::teleporterEnabled"/> property is
5945	enabled on the machine being powered up, the machine will wait for an
5946	incoming teleportation in the <link to="MachineState_TeleportingIn"/>
5947	state. The returned progress object will have at least three
5948	operations where the last three are defined as: (1) powering up and
5949	starting TCP server, (2) waiting for incoming teleportations, and
5950	(3) perform teleportation. These operations will be reflected as the
5951	last three operations of the progress objected returned by
5952	<link to="IMachine::launchVMProcess"/> as well.
5953
5954	<see>#saveState</see>
5955
5956	<result name="VBOX_E_INVALID_VM_STATE">
5957	Virtual machine already running.
5958	</result>
5959	<result name="VBOX_E_HOST_ERROR">
5960	Host interface does not exist or name not set.
5961	</result>
5962	<result name="VBOX_E_FILE_ERROR">
5963	Invalid saved state file.
5964	</result>
5965	</desc>
5966	<param name="progress" type="IProgress" dir="return">
5967	<desc>Progress object to track the operation completion.</desc>
5968	</param>
5969	</method>
5970
5971	<method name="powerUpPaused">
5972	<desc>
5973	Identical to powerUp except that the VM will enter the
5974	<link to="MachineState_Paused"/> state, instead of
5975	<link to="MachineState_Running"/>.
5976
5977	<see>#powerUp</see>
5978	<result name="VBOX_E_INVALID_VM_STATE">
5979	Virtual machine already running.
5980	</result>
5981	<result name="VBOX_E_HOST_ERROR">
5982	Host interface does not exist or name not set.
5983	</result>
5984	<result name="VBOX_E_FILE_ERROR">
5985	Invalid saved state file.
5986	</result>
5987	</desc>
5988	<param name="progress" type="IProgress" dir="return">
5989	<desc>Progress object to track the operation completion.</desc>
5990	</param>
5991	</method>
5992
5993	<method name="powerDown">
5994	<desc>
5995	Initiates the power down procedure to stop the virtual machine
5996	execution.
5997
5998	The completion of the power down procedure is tracked using the returned
5999	IProgress object. After the operation is complete, the machine will go
6000	to the PoweredOff state.
6001	<result name="VBOX_E_INVALID_VM_STATE">
6002	Virtual machine must be Running, Paused or Stuck to be powered down.
6003	</result>
6004	</desc>
6005	<param name="progress" type="IProgress" dir="return">
6006	<desc>Progress object to track the operation completion.</desc>
6007	</param>
6008	</method>
6009
6010	<method name="reset">
6011	<desc>Resets the virtual machine.
6012	<result name="VBOX_E_INVALID_VM_STATE">
6013	Virtual machine not in Running state.
6014	</result>
6015	<result name="VBOX_E_VM_ERROR">
6016	Virtual machine error in reset operation.
6017	</result>
6018	</desc>
6019	</method>
6020
6021	<method name="pause">
6022	<desc>Pauses the virtual machine execution.
6023	<result name="VBOX_E_INVALID_VM_STATE">
6024	Virtual machine not in Running state.
6025	</result>
6026	<result name="VBOX_E_VM_ERROR">
6027	Virtual machine error in suspend operation.
6028	</result>
6029	</desc>
6030	</method>
6031
6032	<method name="resume">
6033	<desc>Resumes the virtual machine execution.
6034	<result name="VBOX_E_INVALID_VM_STATE">
6035	Virtual machine not in Paused state.
6036	</result>
6037	<result name="VBOX_E_VM_ERROR">
6038	Virtual machine error in resume operation.
6039	</result>
6040	</desc>
6041	</method>
6042
6043	<method name="powerButton">
6044	<desc>Sends the ACPI power button event to the guest.
6045	<result name="VBOX_E_INVALID_VM_STATE">
6046	Virtual machine not in Running state.
6047	</result>
6048	<result name="VBOX_E_PDM_ERROR">
6049	Controlled power off failed.
6050	</result>
6051	</desc>
6052	</method>
6053
6054	<method name="sleepButton">
6055	<desc>Sends the ACPI sleep button event to the guest.
6056	<result name="VBOX_E_INVALID_VM_STATE">
6057	Virtual machine not in Running state.
6058	</result>
6059	<result name="VBOX_E_PDM_ERROR">
6060	Sending sleep button event failed.
6061	</result>
6062	</desc>
6063	</method>
6064
6065	<method name="getPowerButtonHandled">
6066	<desc>Checks if the last power button event was handled by guest.
6067	<result name="VBOX_E_PDM_ERROR">
6068	Checking if the event was handled by the guest OS failed.
6069	</result>
6070	</desc>
6071	<param name="handled" type="boolean" dir="return"/>
6072	</method>
6073
6074	<method name="getGuestEnteredACPIMode">
6075	<desc>Checks if the guest entered the ACPI mode G0 (working) or
6076	G1 (sleeping). If this method returns @c false, the guest will
6077	most likely not respond to external ACPI events.
6078	<result name="VBOX_E_INVALID_VM_STATE">
6079	Virtual machine not in Running state.
6080	</result>
6081	</desc>
6082	<param name="entered" type="boolean" dir="return"/>
6083	</method>
6084
6085	<method name="saveState">
6086	<desc>
6087	Saves the current execution state of a running virtual machine
6088	and stops its execution.
6089
6090	After this operation completes, the machine will go to the
6091	Saved state. Next time it is powered up, this state will
6092	be restored and the machine will continue its execution from
6093	the place where it was saved.
6094
6095	This operation differs from taking a snapshot to the effect
6096	that it doesn't create new differencing media. Also, once
6097	the machine is powered up from the state saved using this method,
6098	the saved state is deleted, so it will be impossible to return
6099	to this state later.
6100
6101	<note>
6102	On success, this method implicitly calls
6103	<link to="IMachine::saveSettings"/> to save all current machine
6104	settings (including runtime changes to the DVD medium, etc.).
6105	Together with the impossibility to change any VM settings when it is
6106	in the Saved state, this guarantees adequate hardware
6107	configuration of the machine when it is restored from the saved
6108	state file.
6109	</note>
6110
6111	<note>
6112	The machine must be in the Running or Paused state, otherwise
6113	the operation will fail.
6114	</note>
6115	<result name="VBOX_E_INVALID_VM_STATE">
6116	Virtual machine state neither Running nor Paused.
6117	</result>
6118	<result name="VBOX_E_FILE_ERROR">
6119	Failed to create directory for saved state file.
6120	</result>
6121
6122	<see><link to="#takeSnapshot"/></see>
6123	</desc>
6124	<param name="progress" type="IProgress" dir="return">
6125	<desc>Progress object to track the operation completion.</desc>
6126	</param>
6127	</method>
6128
6129	<method name="adoptSavedState">
6130	<desc>
6131	Associates the given saved state file to the virtual machine.
6132
6133	On success, the machine will go to the Saved state. Next time it is
6134	powered up, it will be restored from the adopted saved state and
6135	continue execution from the place where the saved state file was
6136	created.
6137
6138	The specified saved state file path may be absolute or relative to the
6139	folder the VM normally saves the state to (usually,
6140	<link to="IMachine::snapshotFolder"/>).
6141
6142	<note>
6143	It's a caller's responsibility to make sure the given saved state
6144	file is compatible with the settings of this virtual machine that
6145	represent its virtual hardware (memory size, storage disk configuration
6146	etc.). If there is a mismatch, the behavior of the virtual machine
6147	is undefined.
6148	</note>
6149	<result name="VBOX_E_INVALID_VM_STATE">
6150	Virtual machine state neither PoweredOff nor Aborted.
6151	</result>
6152	</desc>
6153	<param name="savedStateFile" type="wstring" dir="in">
6154	<desc>Path to the saved state file to adopt.</desc>
6155	</param>
6156	</method>
6157
6158	<method name="discardSavedState">
6159	<desc>
6160	Forcibly resets the machine to "Powered Off" state if it is
6161	currently in the "Saved" state (previously created by <link to="#saveState"/>).
6162	Next time the machine is powered up, a clean boot will occur.
6163	<note>
6164	This operation is equivalent to resetting or powering off
6165	the machine without doing a proper shutdown of the guest
6166	operating system; as with resetting a running phyiscal
6167	computer, it can can lead to data loss.
6168	</note>
6169	If @a fRemoveFile is @c true, the file in the machine directory
6170	into which the machine state was saved is also deleted. If
6171	this is @c false, then the state can be recovered and later
6172	re-inserted into a machine using <link to="#adoptSavedState" />.
6173	The location of the file can be found in the
6174	<link to="IMachine::stateFilePath" /> attribute.
6175	<result name="VBOX_E_INVALID_VM_STATE">
6176	Virtual machine not in state Saved.
6177	</result>
6178	</desc>
6179	<param name="fRemoveFile" type="boolean" dir="in" >
6180	<desc>Whether to also remove the saved state file.</desc>
6181	</param>
6182	</method>
6183
6184	<method name="getDeviceActivity">
6185	<desc>
6186	Gets the current activity type of a given device or device group.
6187	<result name="E_INVALIDARG">
6188	Invalid device type.
6189	</result>
6190	</desc>
6191	<param name="type" type="DeviceType" dir="in"/>
6192	<param name="activity" type="DeviceActivity" dir="return"/>
6193	</method>
6194
6195	<method name="attachUSBDevice">
6196	<desc>
6197	Attaches a host USB device with the given UUID to the
6198	USB controller of the virtual machine.
6199
6200	The device needs to be in one of the following states:
6201	<link to="USBDeviceState_Busy"/>,
6202	<link to="USBDeviceState_Available"/> or
6203	<link to="USBDeviceState_Held"/>,
6204	otherwise an error is immediately returned.
6205
6206	When the device state is
6207	<link to="USBDeviceState_Busy">Busy</link>, an error may also
6208	be returned if the host computer refuses to release it for some reason.
6209
6210	<see>IUSBController::deviceFilters, USBDeviceState</see>
6211	<result name="VBOX_E_INVALID_VM_STATE">
6212	Virtual machine state neither Running nor Paused.
6213	</result>
6214	<result name="VBOX_E_PDM_ERROR">
6215	Virtual machine does not have a USB controller.
6216	</result>
6217	</desc>
6218	<param name="id" type="uuid" mod="string" dir="in">
6219	<desc>UUID of the host USB device to attach.</desc>
6220	</param>
6221	</method>
6222
6223	<method name="detachUSBDevice">
6224	<desc>
6225	Detaches an USB device with the given UUID from the USB controller
6226	of the virtual machine.
6227
6228	After this method succeeds, the VirtualBox server re-initiates
6229	all USB filters as if the device were just physically attached
6230	to the host, but filters of this machine are ignored to avoid
6231	a possible automatic re-attachment.
6232
6233	<see>IUSBController::deviceFilters, USBDeviceState</see>
6234
6235	<result name="VBOX_E_PDM_ERROR">
6236	Virtual machine does not have a USB controller.
6237	</result>
6238	<result name="E_INVALIDARG">
6239	USB device not attached to this virtual machine.
6240	</result>
6241	</desc>
6242	<param name="id" type="uuid" mod="string" dir="in">
6243	<desc>UUID of the USB device to detach.</desc>
6244	</param>
6245	<param name="device" type="IUSBDevice" dir="return">
6246	<desc>Detached USB device.</desc>
6247	</param>
6248	</method>
6249
6250	<method name="findUSBDeviceByAddress">
6251	<desc>
6252	Searches for a USB device with the given host address.
6253
6254	<result name="VBOX_E_OBJECT_NOT_FOUND">
6255	Given @c name does not correspond to any USB device.
6256	</result>
6257
6258	<see>IUSBDevice::address</see>
6259	</desc>
6260	<param name="name" type="wstring" dir="in">
6261	<desc>
6262	Address of the USB device (as assigned by the host) to
6263	search for.
6264	</desc>
6265	</param>
6266	<param name="device" type="IUSBDevice" dir="return">
6267	<desc>Found USB device object.</desc>
6268	</param>
6269	</method>
6270
6271	<method name="findUSBDeviceById">
6272	<desc>
6273	Searches for a USB device with the given UUID.
6274
6275	<result name="VBOX_E_OBJECT_NOT_FOUND">
6276	Given @c id does not correspond to any USB device.
6277	</result>
6278
6279	<see>IUSBDevice::id</see>
6280	</desc>
6281	<param name="id" type="uuid" mod="string" dir="in">
6282	<desc>UUID of the USB device to search for.</desc>
6283	</param>
6284	<param name="device" type="IUSBDevice" dir="return">
6285	<desc>Found USB device object.</desc>
6286	</param>
6287	</method>
6288
6289	<method name="createSharedFolder">
6290	<desc>
6291	Creates a transient new shared folder by associating the given logical
6292	name with the given host path, adds it to the collection of shared
6293	folders and starts sharing it. Refer to the description of
6294	<link to="ISharedFolder"/> to read more about logical names.
6295
6296	<result name="VBOX_E_INVALID_VM_STATE">
6297	Virtual machine in Saved state or currently changing state.
6298	</result>
6299	<result name="VBOX_E_FILE_ERROR">
6300	Shared folder already exists or not accessible.
6301	</result>
6302	</desc>
6303	<param name="name" type="wstring" dir="in">
6304	<desc>Unique logical name of the shared folder.</desc>
6305	</param>
6306	<param name="hostPath" type="wstring" dir="in">
6307	<desc>Full path to the shared folder in the host file system.</desc>
6308	</param>
6309	<param name="writable" type="boolean" dir="in">
6310	<desc>Whether the share is writable or readonly</desc>
6311	</param>
6312	<param name="automount" type="boolean" dir="in">
6313	<desc>Whether the share gets automatically mounted by the guest
6314	or not.</desc>
6315	</param>
6316	</method>
6317
6318	<method name="removeSharedFolder">
6319	<desc>
6320	Removes a transient shared folder with the given name previously
6321	created by <link to="#createSharedFolder"/> from the collection of
6322	shared folders and stops sharing it.
6323	<result name="VBOX_E_INVALID_VM_STATE">
6324	Virtual machine in Saved state or currently changing state.
6325	</result>
6326	<result name="VBOX_E_FILE_ERROR">
6327	Shared folder does not exists.
6328	</result>
6329	</desc>
6330	<param name="name" type="wstring" dir="in">
6331	<desc>Logical name of the shared folder to remove.</desc>
6332	</param>
6333	</method>
6334
6335	<method name="takeSnapshot">
6336	<desc>
6337	Saves the current execution state
6338	and all settings of the machine and creates differencing images
6339	for all normal (non-independent) media.
6340	See <link to="ISnapshot" /> for an introduction to snapshots.
6341
6342	This method can be called for a PoweredOff, Saved (see
6343	<link to="#saveState"/>), Running or
6344	Paused virtual machine. When the machine is PoweredOff, an
6345	offline snapshot is created. When the machine is Running a live
6346	snapshot is created, and an online snapshot is is created when Paused.
6347
6348	The taken snapshot is always based on the
6349	<link to="IMachine::currentSnapshot">current snapshot</link>
6350	of the associated virtual machine and becomes a new current snapshot.
6351
6352	<note>
6353	This method implicitly calls <link to="IMachine::saveSettings"/> to
6354	save all current machine settings before taking an offline snapshot.
6355	</note>
6356
6357	<result name="VBOX_E_INVALID_VM_STATE">
6358	Virtual machine currently changing state.
6359	</result>
6360	</desc>
6361	<param name="name" type="wstring" dir="in">
6362	<desc>Short name for the snapshot.</desc>
6363	</param>
6364	<param name="description" type="wstring" dir="in">
6365	<desc>Optional description of the snapshot.</desc>
6366	</param>
6367	<param name="progress" type="IProgress" dir="return">
6368	<desc>Progress object to track the operation completion.</desc>
6369	</param>
6370	</method>
6371
6372	<method name="deleteSnapshot">
6373	<desc>
6374	Starts deleting the specified snapshot asynchronously.
6375	See <link to="ISnapshot" /> for an introduction to snapshots.
6376
6377	The execution state and settings of the associated machine stored in
6378	the snapshot will be deleted. The contents of all differencing media of
6379	this snapshot will be merged with the contents of their dependent child
6380	media to keep the medium chain valid (in other words, all changes
6381	represented by media being deleted will be propagated to their child
6382	medium). After that, this snapshot's differencing medium will be
6383	deleted. The parent of this snapshot will become a new parent for all
6384	its child snapshots.
6385
6386	If the deleted snapshot is the current one, its parent snapshot will
6387	become a new current snapshot. The current machine state is not directly
6388	affected in this case, except that currently attached differencing
6389	media based on media of the deleted snapshot will be also merged as
6390	described above.
6391
6392	If the deleted snapshot is the first or current snapshot, then the
6393	respective IMachine attributes will be adjusted. Deleting the current
6394	snapshot will also implicitly call <link to="IMachine::saveSettings"/>
6395	to make all current machine settings permanent.
6396
6397	Deleting a snapshot has the following preconditions:
6398
6399	<ul>
6400	<li>Child media of all normal media of the deleted snapshot
6401	must be accessible (see <link to="IMedium::state"/>) for this
6402	operation to succeed. In particular, this means that all virtual
6403	machines, whose media are directly or indirectly based on the
6404	media of deleted snapshot, must be powered off.</li>
6405
6406	<li>You cannot delete the snapshot if a medium attached to it has
6407	more than once child medium (differencing images) because otherwise
6408	merging would be impossible. This might be the case if there is
6409	more than one child snapshot or differencing images were created
6410	for other reason (e.g. implicitly because of multiple machine
6411	attachments).</li>
6412	</ul>
6413
6414
6415	The virtual machine's <link to="IMachine::state">state</link> is
6416	changed to "DeletingSnapshot", "DeletingSnapshotOnline" or
6417	"DeletingSnapshotPaused" while this operation is in progress.
6418
6419	<note>
6420	Merging medium contents can be very time and disk space
6421	consuming, if these media are big in size and have many
6422	children. However, if the snapshot being deleted is the last
6423	(head) snapshot on the branch, the operation will be rather
6424	quick.
6425	</note>
6426	<result name="VBOX_E_INVALID_VM_STATE">
6427	The running virtual machine prevents deleting this snapshot. This
6428	happens only in very specific situations, usually snapshots can be
6429	deleted without trouble while a VM is running. The error message
6430	text explains the reason for the failure.
6431	</result>
6432	</desc>
6433	<param name="id" type="uuid" mod="string" dir="in">
6434	<desc>UUID of the snapshot to delete.</desc>
6435	</param>
6436	<param name="progress" type="IProgress" dir="return">
6437	<desc>Progress object to track the operation completion.</desc>
6438	</param>
6439	</method>
6440
6441	<method name="restoreSnapshot">
6442	<desc>
6443	Starts resetting the machine's current state to the state contained
6444	in the given snapshot, asynchronously. All current settings of the
6445	machine will be reset and changes stored in differencing media
6446	will be lost.
6447	See <link to="ISnapshot" /> for an introduction to snapshots.
6448
6449	After this operation is successfully completed, new empty differencing
6450	media are created for all normal media of the machine.
6451
6452	If the given snapshot is an online snapshot, the machine will go to
6453	the <link to="MachineState_Saved"> saved state</link>, so that the
6454	next time it is powered on, the execution state will be restored
6455	from the state of the snapshot.
6456
6457	<note>
6458	The machine must not be running, otherwise the operation will fail.
6459	</note>
6460
6461	<note>
6462	If the machine state is <link to="MachineState_Saved">Saved</link>
6463	prior to this operation, the saved state file will be implicitly
6464	deleted (as if <link to="IConsole::discardSavedState"/> were
6465	called).
6466	</note>
6467
6468	<result name="VBOX_E_INVALID_VM_STATE">
6469	Virtual machine is running.
6470	</result>
6471	</desc>
6472	<param name="snapshot" type="ISnapshot" dir="in">
6473	<desc>The snapshot to restore the VM state from.</desc>
6474	</param>
6475	<param name="progress" type="IProgress" dir="return">
6476	<desc>Progress object to track the operation completion.</desc>
6477	</param>
6478	</method>
6479
6480	<method name="teleport">
6481	<desc>
6482	Teleport the VM to a different host machine or process.
6483
6484	TODO explain the details.
6485
6486	<result name="VBOX_E_INVALID_VM_STATE">
6487	Virtual machine not running or paused.
6488	</result>
6489	</desc>
6490	<param name="hostname" type="wstring" dir="in">
6491	<desc>The name or IP of the host to teleport to.</desc>
6492	</param>
6493	<param name="tcpport" type="unsigned long" dir="in">
6494	<desc>The TCP port to connect to (1..65535).</desc>
6495	</param>
6496	<param name="password" type="wstring" dir="in">
6497	<desc>The password.</desc>
6498	</param>
6499	<param name="maxDowntime" type="unsigned long" dir="in">
6500	<desc>
6501	The maximum allowed downtime given as milliseconds. 0 is not a valid
6502	value. Recommended value: 250 ms.
6503
6504	The higher the value is, the greater the chance for a successful
6505	teleportation. A small value may easily result in the teleportation
6506	process taking hours and eventually fail.
6507
6508	<note>
6509	The current implementation treats this a guideline, not as an
6510	absolute rule.
6511	</note>
6512	</desc>
6513	</param>
6514	<param name="progress" type="IProgress" dir="return">
6515	<desc>Progress object to track the operation completion.</desc>
6516	</param>
6517	</method>
6518
6519	</interface>
6520
6521	<!--
6522	// IHost
6523	/////////////////////////////////////////////////////////////////////////
6524	-->
6525
6526	<enum
6527	name="HostNetworkInterfaceMediumType"
6528	uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
6529	>
6530	<desc>
6531	Type of encapsulation. Ethernet encapsulation includes both wired and
6532	wireless Ethernet connections.
6533	<see>IHostNetworkInterface</see>
6534	</desc>
6535
6536	<const name="Unknown" value="0">
6537	<desc>
6538	The type of interface cannot be determined.
6539	</desc>
6540	</const>
6541	<const name="Ethernet" value="1">
6542	<desc>
6543	Ethernet frame encapsulation.
6544	</desc>
6545	</const>
6546	<const name="PPP" value="2">
6547	<desc>
6548	Point-to-point protocol encapsulation.
6549	</desc>
6550	</const>
6551	<const name="SLIP" value="3">
6552	<desc>
6553	Serial line IP encapsulation.
6554	</desc>
6555	</const>
6556	</enum>
6557
6558	<enum
6559	name="HostNetworkInterfaceStatus"
6560	uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
6561	>
6562	<desc>
6563	Current status of the interface.
6564	<see>IHostNetworkInterface</see>
6565	</desc>
6566
6567	<const name="Unknown" value="0">
6568	<desc>
6569	The state of interface cannot be determined.
6570	</desc>
6571	</const>
6572	<const name="Up" value="1">
6573	<desc>
6574	The interface is fully operational.
6575	</desc>
6576	</const>
6577	<const name="Down" value="2">
6578	<desc>
6579	The interface is not functioning.
6580	</desc>
6581	</const>
6582	</enum>
6583
6584	<enum
6585	name="HostNetworkInterfaceType"
6586	uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
6587	>
6588	<desc>
6589	Network interface type.
6590	</desc>
6591	<const name="Bridged" value="1"/>
6592	<const name="HostOnly" value="2"/>
6593	</enum>
6594
6595	<interface
6596	name="IHostNetworkInterface" extends="$unknown"
6597	uuid="ce6fae58-7642-4102-b5db-c9005c2320a8"
6598	wsmap="managed"
6599	>
6600	<desc>
6601	Represents one of host's network interfaces. IP V6 address and network
6602	mask are strings of 32 hexdecimal digits grouped by four. Groups are
6603	separated by colons.
6604	For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
6605	</desc>
6606	<attribute name="name" type="wstring" readonly="yes">
6607	<desc>Returns the host network interface name.</desc>
6608	</attribute>
6609
6610	<attribute name="id" type="uuid" mod="string" readonly="yes">
6611	<desc>Returns the interface UUID.</desc>
6612	</attribute>
6613
6614	<attribute name="networkName" type="wstring" readonly="yes">
6615	<desc>Returns the name of a virtual network the interface gets attached to.</desc>
6616	</attribute>
6617
6618	<attribute name="dhcpEnabled" type="boolean" readonly="yes">
6619	<desc>Specifies whether the DHCP is enabled for the interface.</desc>
6620	</attribute>
6621
6622	<attribute name="IPAddress" type="wstring" readonly="yes">
6623	<desc>Returns the IP V4 address of the interface.</desc>
6624	</attribute>
6625
6626	<attribute name="networkMask" type="wstring" readonly="yes">
6627	<desc>Returns the network mask of the interface.</desc>
6628	</attribute>
6629
6630	<attribute name="IPV6Supported" type="boolean" readonly="yes">
6631	<desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
6632	</attribute>
6633
6634	<attribute name="IPV6Address" type="wstring" readonly="yes">
6635	<desc>Returns the IP V6 address of the interface.</desc>
6636	</attribute>
6637
6638	<attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
6639	<desc>Returns the length IP V6 network mask prefix of the interface.</desc>
6640	</attribute>
6641
6642	<attribute name="hardwareAddress" type="wstring" readonly="yes">
6643	<desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
6644	</attribute>
6645
6646	<attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
6647	<desc>Type of protocol encapsulation used.</desc>
6648	</attribute>
6649
6650	<attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
6651	<desc>Status of the interface.</desc>
6652	</attribute>
6653
6654	<attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
6655	<desc>specifies the host interface type.</desc>
6656	</attribute>
6657
6658	<method name="enableStaticIpConfig">
6659	<desc>sets and enables the static IP V4 configuration for the given interface.</desc>
6660	<param name="IPAddress" type="wstring" dir="in">
6661	<desc>
6662	IP address.
6663	</desc>
6664	</param>
6665	<param name="networkMask" type="wstring" dir="in">
6666	<desc>
6667	network mask.
6668	</desc>
6669	</param>
6670	</method>
6671
6672	<method name="enableStaticIpConfigV6">
6673	<desc>sets and enables the static IP V6 configuration for the given interface.</desc>
6674	<param name="IPV6Address" type="wstring" dir="in">
6675	<desc>
6676	IP address.
6677	</desc>
6678	</param>
6679	<param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
6680	<desc>
6681	network mask.
6682	</desc>
6683	</param>
6684	</method>
6685
6686	<method name="enableDynamicIpConfig">
6687	<desc>enables the dynamic IP configuration.</desc>
6688	</method>
6689
6690	<method name="dhcpRediscover">
6691	<desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
6692	</method>
6693
6694	</interface>
6695
6696	<interface
6697	name="IHost" extends="$unknown"
6698	uuid="35b004f4-7806-4009-bfa8-d1308adba7e5"
6699	wsmap="managed"
6700	>
6701	<desc>
6702	The IHost interface represents the physical machine that this VirtualBox
6703	installation runs on.
6704
6705	An object implementing this interface is returned by the
6706	<link to="IVirtualBox::host" /> attribute. This interface contains
6707	read-only information about the host's physical hardware (such as what
6708	processors and disks are available, what the host operating system is,
6709	and so on) and also allows for manipulating some of the host's hardware,
6710	such as global USB device filters and host interface networking.
6711
6712	</desc>
6713	<attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
6714	<desc>List of DVD drives available on the host.</desc>
6715	</attribute>
6716
6717	<attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
6718	<desc>List of floppy drives available on the host.</desc>
6719	</attribute>
6720
6721	<attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6722	<desc>
6723	List of USB devices currently attached to the host.
6724	Once a new device is physically attached to the host computer,
6725	it appears in this list and remains there until detached.
6726
6727	<note>
6728	If USB functionality is not available in the given edition of
6729	VirtualBox, this method will set the result code to @c E_NOTIMPL.
6730	</note>
6731	</desc>
6732	</attribute>
6733
6734	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
6735	<desc>
6736	List of USB device filters in action.
6737	When a new device is physically attached to the host computer,
6738	filters from this list are applied to it (in order they are stored
6739	in the list). The first matched filter will determine the
6740	<link to="IHostUSBDeviceFilter::action">action</link>
6741	performed on the device.
6742
6743	Unless the device is ignored by these filters, filters of all
6744	currently running virtual machines
6745	(<link to="IUSBController::deviceFilters"/>) are applied to it.
6746
6747	<note>
6748	If USB functionality is not available in the given edition of
6749	VirtualBox, this method will set the result code to @c E_NOTIMPL.
6750	</note>
6751
6752	<see>IHostUSBDeviceFilter, USBDeviceState</see>
6753	</desc>
6754	</attribute>
6755
6756	<attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
6757	<desc>List of host network interfaces currently defined on the host.</desc>
6758	</attribute>
6759
6760	<attribute name="processorCount" type="unsigned long" readonly="yes">
6761	<desc>Number of (logical) CPUs installed in the host system.</desc>
6762	</attribute>
6763
6764	<attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
6765	<desc>Number of (logical) CPUs online in the host system.</desc>
6766	</attribute>
6767
6768	<attribute name="processorCoreCount" type="unsigned long" readonly="yes">
6769	<desc>Number of physical processor cores installed in the host system.</desc>
6770	</attribute>
6771
6772	<method name="getProcessorSpeed">
6773	<desc>Query the (approximate) maximum speed of a specified host CPU in
6774	Megahertz.
6775	</desc>
6776	<param name="cpuId" type="unsigned long" dir="in">
6777	<desc>
6778	Identifier of the CPU.
6779	</desc>
6780	</param>
6781	<param name="speed" type="unsigned long" dir="return">
6782	<desc>
6783	Speed value. 0 is returned if value is not known or @a cpuId is
6784	invalid.
6785	</desc>
6786	</param>
6787	</method>
6788
6789	<method name="getProcessorFeature">
6790	<desc>Query whether a CPU feature is supported or not.</desc>
6791	<param name="feature" type="ProcessorFeature" dir="in">
6792	<desc>
6793	CPU Feature identifier.
6794	</desc>
6795	</param>
6796	<param name="supported" type="boolean" dir="return">
6797	<desc>
6798	Feature is supported or not.
6799	</desc>
6800	</param>
6801	</method>
6802
6803	<method name="getProcessorDescription">
6804	<desc>Query the model string of a specified host CPU.
6805	</desc>
6806	<param name="cpuId" type="unsigned long" dir="in">
6807	<desc>
6808	Identifier of the CPU.
6809	<note>
6810	The current implementation might not necessarily return the
6811	description for this exact CPU.
6812	</note>
6813	</desc>
6814	</param>
6815	<param name="description" type="wstring" dir="return">
6816	<desc>
6817	Model string. An empty string is returned if value is not known or
6818	@a cpuId is invalid.
6819	</desc>
6820	</param>
6821	</method>
6822
6823	<method name="getProcessorCPUIDLeaf">
6824	<desc>
6825	Returns the CPU cpuid information for the specified leaf.
6826	</desc>
6827	<param name="cpuId" type="unsigned long" dir="in">
6828	<desc>
6829	Identifier of the CPU. The CPU most be online.
6830	<note>
6831	The current implementation might not necessarily return the
6832	description for this exact CPU.
6833	</note>
6834	</desc>
6835	</param>
6836	<param name="leaf" type="unsigned long" dir="in">
6837	<desc>
6838	CPUID leaf index (eax).
6839	</desc>
6840	</param>
6841	<param name="subLeaf" type="unsigned long" dir="in">
6842	<desc>
6843	CPUID leaf sub index (ecx). This currently only applies to cache
6844	information on Intel CPUs. Use 0 if retriving values for
6845	<link to="IMachine::setCPUIDLeaf"/>.
6846	</desc>
6847	</param>
6848	<param name="valEax" type="unsigned long" dir="out">
6849	<desc>
6850	CPUID leaf value for register eax.
6851	</desc>
6852	</param>
6853	<param name="valEbx" type="unsigned long" dir="out">
6854	<desc>
6855	CPUID leaf value for register ebx.
6856	</desc>
6857	</param>
6858	<param name="valEcx" type="unsigned long" dir="out">
6859	<desc>
6860	CPUID leaf value for register ecx.
6861	</desc>
6862	</param>
6863	<param name="valEdx" type="unsigned long" dir="out">
6864	<desc>
6865	CPUID leaf value for register edx.
6866	</desc>
6867	</param>
6868	</method>
6869
6870	<attribute name="memorySize" type="unsigned long" readonly="yes">
6871	<desc>Amount of system memory in megabytes installed in the host system.</desc>
6872	</attribute>
6873
6874	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
6875	<desc>Available system memory in the host system.</desc>
6876	</attribute>
6877
6878	<attribute name="operatingSystem" type="wstring" readonly="yes">
6879	<desc>Name of the host system's operating system.</desc>
6880	</attribute>
6881
6882	<attribute name="OSVersion" type="wstring" readonly="yes">
6883	<desc>Host operating system's version string.</desc>
6884	</attribute>
6885
6886	<attribute name="UTCTime" type="long long" readonly="yes">
6887	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
6888	</attribute>
6889
6890	<attribute name="Acceleration3DAvailable" type="boolean" readonly="yes">
6891	<desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
6892	</attribute>
6893
6894	<method name="createHostOnlyNetworkInterface">
6895	<desc>
6896	Creates a new adapter for Host Only Networking.
6897	<result name="E_INVALIDARG">
6898	Host network interface @a name already exists.
6899	</result>
6900	</desc>
6901	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
6902	<desc>
6903	Created host interface object.
6904	</desc>
6905	</param>
6906	<param name="progress" type="IProgress" dir="return">
6907	<desc>
6908	Progress object to track the operation completion.
6909	</desc>
6910	</param>
6911	</method>
6912
6913	<method name="removeHostOnlyNetworkInterface">
6914	<desc>
6915	Removes the given Host Only Networking interface.
6916	<result name="VBOX_E_OBJECT_NOT_FOUND">
6917	No host network interface matching @a id found.
6918	</result>
6919	</desc>
6920	<param name="id" type="uuid" mod="string" dir="in">
6921	<desc>
6922	Adapter GUID.
6923	</desc>
6924	</param>
6925	<param name="progress" type="IProgress" dir="return">
6926	<desc>
6927	Progress object to track the operation completion.
6928	</desc>
6929	</param>
6930	</method>
6931
6932	<method name="createUSBDeviceFilter">
6933	<desc>
6934	Creates a new USB device filter. All attributes except
6935	the filter name are set to empty (any match),
6936	<i>active</i> is @c false (the filter is not active).
6937
6938	The created filter can be added to the list of filters using
6939	<link to="#insertUSBDeviceFilter"/>.
6940
6941	<see>#USBDeviceFilters</see>
6942	</desc>
6943	<param name="name" type="wstring" dir="in">
6944	<desc>
6945	Filter name. See <link to="IUSBDeviceFilter::name"/> for more information.
6946	</desc>
6947	</param>
6948	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
6949	<desc>Created filter object.</desc>
6950	</param>
6951	</method>
6952
6953	<method name="insertUSBDeviceFilter">
6954	<desc>
6955	Inserts the given USB device to the specified position
6956	in the list of filters.
6957
6958	Positions are numbered starting from @c 0. If the specified
6959	position is equal to or greater than the number of elements in
6960	the list, the filter is added at the end of the collection.
6961
6962	<note>
6963	Duplicates are not allowed, so an attempt to insert a
6964	filter already in the list is an error.
6965	</note>
6966	<note>
6967	If USB functionality is not available in the given edition of
6968	VirtualBox, this method will set the result code to @c E_NOTIMPL.
6969	</note>
6970
6971	<see>#USBDeviceFilters</see>
6972
6973	<result name="VBOX_E_INVALID_OBJECT_STATE">
6974	USB device filter is not created within this VirtualBox instance.
6975	</result>
6976	<result name="E_INVALIDARG">
6977	USB device filter already in list.
6978	</result>
6979
6980	</desc>
6981	<param name="position" type="unsigned long" dir="in">
6982	<desc>Position to insert the filter to.</desc>
6983	</param>
6984	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
6985	<desc>USB device filter to insert.</desc>
6986	</param>
6987	</method>
6988
6989	<method name="removeUSBDeviceFilter">
6990	<desc>
6991	Removes a USB device filter from the specified position in the
6992	list of filters.
6993
6994	Positions are numbered starting from @c 0. Specifying a
6995	position equal to or greater than the number of elements in
6996	the list will produce an error.
6997
6998	<note>
6999	If USB functionality is not available in the given edition of
7000	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7001	</note>
7002
7003	<see>#USBDeviceFilters</see>
7004
7005	<result name="E_INVALIDARG">
7006	USB device filter list empty or invalid @a position.
7007	</result>
7008
7009	</desc>
7010	<param name="position" type="unsigned long" dir="in">
7011	<desc>Position to remove the filter from.</desc>
7012	</param>
7013	</method>
7014
7015	<method name="findHostDVDDrive">
7016	<desc>
7017	Searches for a host DVD drive with the given @c name.
7018
7019	<result name="VBOX_E_OBJECT_NOT_FOUND">
7020	Given @c name does not correspond to any host drive.
7021	</result>
7022
7023	</desc>
7024	<param name="name" type="wstring" dir="in">
7025	<desc>Name of the host drive to search for</desc>
7026	</param>
7027	<param name="drive" type="IMedium" dir="return">
7028	<desc>Found host drive object</desc>
7029	</param>
7030	</method>
7031
7032	<method name="findHostFloppyDrive">
7033	<desc>
7034	Searches for a host floppy drive with the given @c name.
7035
7036	<result name="VBOX_E_OBJECT_NOT_FOUND">
7037	Given @c name does not correspond to any host floppy drive.
7038	</result>
7039
7040	</desc>
7041	<param name="name" type="wstring" dir="in">
7042	<desc>Name of the host floppy drive to search for</desc>
7043	</param>
7044	<param name="drive" type="IMedium" dir="return">
7045	<desc>Found host floppy drive object</desc>
7046	</param>
7047	</method>
7048
7049	<method name="findHostNetworkInterfaceByName">
7050	<desc>
7051	Searches through all host network interfaces for an interface with
7052	the given @c name.
7053	<note>
7054	The method returns an error if the given @c name does not
7055	correspond to any host network interface.
7056	</note>
7057	</desc>
7058	<param name="name" type="wstring" dir="in">
7059	<desc>Name of the host network interface to search for.</desc>
7060	</param>
7061	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
7062	<desc>Found host network interface object.</desc>
7063	</param>
7064	</method>
7065	<method name="findHostNetworkInterfaceById">
7066	<desc>
7067	Searches through all host network interfaces for an interface with
7068	the given GUID.
7069	<note>
7070	The method returns an error if the given GUID does not
7071	correspond to any host network interface.
7072	</note>
7073	</desc>
7074	<param name="id" type="uuid" mod="string" dir="in">
7075	<desc>GUID of the host network interface to search for.</desc>
7076	</param>
7077	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
7078	<desc>Found host network interface object.</desc>
7079	</param>
7080	</method>
7081	<method name="findHostNetworkInterfacesOfType">
7082	<desc>
7083	Searches through all host network interfaces and returns a list of interfaces of the specified type
7084	</desc>
7085	<param name="type" type="HostNetworkInterfaceType" dir="in">
7086	<desc>type of the host network interfaces to search for.</desc>
7087	</param>
7088	<param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
7089	<desc>Found host network interface objects.</desc>
7090	</param>
7091	</method>
7092
7093	<method name="findUSBDeviceById">
7094	<desc>
7095	Searches for a USB device with the given UUID.
7096
7097	<result name="VBOX_E_OBJECT_NOT_FOUND">
7098	Given @c id does not correspond to any USB device.
7099	</result>
7100
7101	<see>IHostUSBDevice::id</see>
7102	</desc>
7103	<param name="id" type="uuid" mod="string" dir="in">
7104	<desc>UUID of the USB device to search for.</desc>
7105	</param>
7106	<param name="device" type="IHostUSBDevice" dir="return">
7107	<desc>Found USB device object.</desc>
7108	</param>
7109	</method>
7110
7111	<method name="findUSBDeviceByAddress">
7112	<desc>
7113	Searches for a USB device with the given host address.
7114
7115	<result name="VBOX_E_OBJECT_NOT_FOUND">
7116	Given @c name does not correspond to any USB device.
7117	</result>
7118
7119	<see>IHostUSBDevice::address</see>
7120	</desc>
7121	<param name="name" type="wstring" dir="in">
7122	<desc>
7123	Address of the USB device (as assigned by the host) to
7124	search for.
7125	</desc>
7126	</param>
7127	<param name="device" type="IHostUSBDevice" dir="return">
7128	<desc>Found USB device object.</desc>
7129	</param>
7130	</method>
7131
7132	</interface>
7133
7134	<!--
7135	// ISystemProperties
7136	/////////////////////////////////////////////////////////////////////////
7137	-->
7138
7139	<interface
7140	name="ISystemProperties"
7141	extends="$unknown"
7142	uuid="07c3ffd8-8f59-49cc-b608-53a332e85cc3"
7143	wsmap="managed"
7144	>
7145	<desc>
7146	The ISystemProperties interface represents global properties of the given
7147	VirtualBox installation.
7148
7149	These properties define limits and default values for various attributes
7150	and parameters. Most of the properties are read-only, but some can be
7151	changed by a user.
7152	</desc>
7153
7154	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
7155	<desc>Minimum guest system memory in Megabytes.</desc>
7156	</attribute>
7157
7158	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
7159	<desc>Maximum guest system memory in Megabytes.</desc>
7160	</attribute>
7161
7162	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
7163	<desc>Minimum guest video memory in Megabytes.</desc>
7164	</attribute>
7165
7166	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
7167	<desc>Maximum guest video memory in Megabytes.</desc>
7168	</attribute>
7169
7170	<attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
7171	<desc>Minimum CPU count.</desc>
7172	</attribute>
7173
7174	<attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
7175	<desc>Maximum CPU count.</desc>
7176	</attribute>
7177
7178	<attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
7179	<desc>Maximum of monitors which could be connected.</desc>
7180	</attribute>
7181
7182	<attribute name="maxVDISize" type="unsigned long long" readonly="yes">
7183	<desc>Maximum size of a virtual disk image in Megabytes.</desc>
7184	</attribute>
7185
7186	<attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
7187	<desc>
7188	Number of network adapters associated with every
7189	<link to="IMachine"/> instance.
7190	</desc>
7191	</attribute>
7192
7193	<attribute name="serialPortCount" type="unsigned long" readonly="yes">
7194	<desc>
7195	Number of serial ports associated with every
7196	<link to="IMachine"/> instance.
7197	</desc>
7198	</attribute>
7199
7200	<attribute name="parallelPortCount" type="unsigned long" readonly="yes">
7201	<desc>
7202	Number of parallel ports associated with every
7203	<link to="IMachine"/> instance.
7204	</desc>
7205	</attribute>
7206
7207	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
7208	<desc>
7209	Maximum device position in the boot order. This value corresponds
7210	to the total number of devices a machine can boot from, to make it
7211	possible to include all possible devices to the boot list.
7212	<see><link to="IMachine::setBootOrder"/></see>
7213	</desc>
7214	</attribute>
7215
7216	<attribute name="defaultMachineFolder" type="wstring">
7217	<desc>
7218	Full path to the default directory used to create new or open
7219	existing machines when a settings file name contains no
7220	path.
7221
7222	The initial value of this property is
7223	<tt><</tt><link to="IVirtualBox::homeFolder">
7224	VirtualBox_home</link><tt>>/Machines</tt>.
7225
7226	<note>
7227	Setting this property to @c null or an empty string will restore the
7228	initial value.
7229	</note>
7230	<note>
7231	When settings this property, the specified path can be
7232	absolute (full path) or relative
7233	to the <link to="IVirtualBox::homeFolder">
7234	VirtualBox home directory</link>.
7235	When reading this property, a full path is
7236	always returned.
7237	</note>
7238	<note>
7239	The specified path may not exist, it will be created
7240	when necessary.
7241	</note>
7242
7243	<see>
7244	<link to="IVirtualBox::createMachine"/>,
7245	<link to="IVirtualBox::openMachine"/>
7246	</see>
7247	</desc>
7248	</attribute>
7249
7250	<attribute name="defaultHardDiskFolder" type="wstring">
7251	<desc>
7252	Full path to the default directory used to create new or open existing
7253	virtual disks.
7254
7255	This path is used when the storage unit of a hard disk is a regular file
7256	in the host's file system and only a file name that contains no path is
7257	given.
7258
7259	The initial value of this property is
7260	<tt><</tt>
7261	<link to="IVirtualBox::homeFolder">VirtualBox_home</link>
7262	<tt>>/HardDisks</tt>.
7263
7264	<note>
7265	Setting this property to @c null or empty string will restore the
7266	initial value.
7267	</note>
7268	<note>
7269	When settings this property, the specified path can be relative
7270	to the
7271	<link to="IVirtualBox::homeFolder">VirtualBox home directory</link> or
7272	absolute. When reading this property, a full path is
7273	always returned.
7274	</note>
7275	<note>
7276	The specified path may not exist, it will be created
7277	when necessary.
7278	</note>
7279
7280	<see>
7281	IMedium,
7282	<link to="IVirtualBox::createHardDisk"/>,
7283	<link to="IVirtualBox::openMedium"/>,
7284	<link to="IMedium::location"/>
7285	</see>
7286	</desc>
7287	</attribute>
7288
7289	<attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
7290	<desc>
7291	List of all medium storage formats supported by this VirtualBox
7292	installation.
7293
7294	Keep in mind that the medium format identifier
7295	(<link to="IMediumFormat::id"/>) used in other API calls like
7296	<link to="IVirtualBox::createHardDisk"/> to refer to a particular
7297	medium format is a case-insensitive string. This means that, for
7298	example, all of the following strings:
7299	<pre>
7300	"VDI"
7301	"vdi"
7302	"VdI"</pre>
7303	refer to the same medium format.
7304
7305	Note that the virtual medium framework is backend-based, therefore
7306	the list of supported formats depends on what backends are currently
7307	installed.
7308
7309	<see>
7310	<link to="IMediumFormat"/>,
7311	</see>
7312	</desc>
7313	</attribute>
7314
7315	<attribute name="defaultHardDiskFormat" type="wstring">
7316	<desc>
7317	Identifier of the default medium format used by VirtualBox.
7318
7319	The medium format set by this attribute is used by VirtualBox
7320	when the medium format was not specified explicitly. One example is
7321	<link to="IVirtualBox::createHardDisk"/> with the empty
7322	format argument. A more complex example is implicit creation of
7323	differencing media when taking a snapshot of a virtual machine:
7324	this operation will try to use a format of the parent medium first
7325	and if this format does not support differencing media the default
7326	format specified by this argument will be used.
7327
7328	The list of supported medium formats may be obtained by the
7329	<link to="#mediumFormats"/> call. Note that the default medium
7330	format must have a capability to create differencing media;
7331	otherwise operations that create media implicitly may fail
7332	unexpectedly.
7333
7334	The initial value of this property is <tt>"VDI"</tt> in the current
7335	version of the VirtualBox product, but may change in the future.
7336
7337	<note>
7338	Setting this property to @c null or empty string will restore the
7339	initial value.
7340	</note>
7341
7342	<see>
7343	<link to="#mediumFormats"/>,
7344	<link to="IMediumFormat::id"/>,
7345	<link to="IVirtualBox::createHardDisk"/>
7346	</see>
7347	</desc>
7348	</attribute>
7349
7350	<attribute name="freeDiskSpaceWarning" type="unsigned long long">
7351	<desc>Issue a warning if the free disk space is below (or in some disk
7352	intensive operation is expected to go below) the given size in
7353	Megabytes.</desc>
7354	</attribute>
7355
7356	<attribute name="freeDiskSpacePercentWarning" type="unsigned long">
7357	<desc>Issue a warning if the free disk space is below (or in some disk
7358	intensive operation is expected to go below) the given percentage.</desc>
7359	</attribute>
7360
7361	<attribute name="freeDiskSpaceError" type="unsigned long long">
7362	<desc>Issue an error if the free disk space is below (or in some disk
7363	intensive operation is expected to go below) the given size in
7364	Megabytes.</desc>
7365	</attribute>
7366
7367	<attribute name="freeDiskSpacePercentError" type="unsigned long">
7368	<desc>Issue an error if the free disk space is below (or in some disk
7369	intensive operation is expected to go below) the given percentage.</desc>
7370	</attribute>
7371
7372	<attribute name="remoteDisplayAuthLibrary" type="wstring">
7373	<desc>
7374	Library that provides authentication for VRDP clients. The library
7375	is used if a virtual machine's authentication type is set to "external"
7376	in the VM RemoteDisplay configuration.
7377
7378	The system library extension (".DLL" or ".so") must be omitted.
7379	A full path can be specified; if not, then the library must reside on the
7380	system's default library path.
7381
7382	The default value of this property is <tt>"VRDPAuth"</tt>. There is a library
7383	of that name in one of the default VirtualBox library directories.
7384
7385	For details about VirtualBox authentication libraries and how to implement
7386	them, please refer to the VirtualBox manual.
7387
7388	<note>
7389	Setting this property to @c null or empty string will restore the
7390	initial value.
7391	</note>
7392	</desc>
7393	</attribute>
7394
7395	<attribute name="webServiceAuthLibrary" type="wstring">
7396	<desc>
7397	Library that provides authentication for webservice clients. The library
7398	is used if a virtual machine's authentication type is set to "external"
7399	in the VM RemoteDisplay configuration and will be called from
7400	within the <link to="IWebsessionManager::logon" /> implementation.
7401
7402	As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
7403	there is no per-VM setting for this, as the webservice is a global
7404	resource (if it is running). Only for this setting (for the webservice),
7405	setting this value to a literal <tt>"null"</tt> string disables authentication,
7406	meaning that <link to="IWebsessionManager::logon" /> will always succeed,
7407	no matter what user name and password are supplied.
7408
7409	The initial value of this property is <tt>"VRDPAuth"</tt>,
7410	meaning that the webservice will use the same authentication
7411	library that is used by default for VBoxVRDP (again, see
7412	<link to="ISystemProperties::remoteDisplayAuthLibrary" />).
7413	The format and calling convention of authentication libraries
7414	is the same for the webservice as it is for VBoxVRDP.
7415
7416	<note>
7417	Setting this property to @c null or empty string will restore the
7418	initial value.
7419	</note>
7420	</desc>
7421	</attribute>
7422
7423	<attribute name="LogHistoryCount" type="unsigned long">
7424	<desc>
7425	This value specifies how many old release log files are kept.
7426	</desc>
7427	</attribute>
7428
7429	<attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
7430	<desc>This value hold the default audio driver for the current
7431	system.</desc>
7432	</attribute>
7433
7434	<method name="getMaxDevicesPerPortForStorageBus">
7435	<desc>Returns the maximum number of devices which can be attached to a port
7436	for the given storage bus.</desc>
7437
7438	<param name="bus" type="StorageBus" dir="in">
7439	<desc>The storage bus type to get the value for.</desc>
7440	</param>
7441
7442	<param name="maxDevicesPerPort" type="unsigned long" dir="return">
7443	<desc>The maximum number of devices which can eb attached to the port for the given
7444	storage bus.</desc>
7445	</param>
7446	</method>
7447
7448	<method name="getMinPortCountForStorageBus">
7449	<desc>Returns the minimum number of ports the given storage bus supports.</desc>
7450
7451	<param name="bus" type="StorageBus" dir="in">
7452	<desc>The storage bus type to get the value for.</desc>
7453	</param>
7454
7455	<param name="minPortCount" type="unsigned long" dir="return">
7456	<desc>The minimum number of ports for the given storage bus.</desc>
7457	</param>
7458	</method>
7459
7460	<method name="getMaxPortCountForStorageBus">
7461	<desc>Returns the maximum number of ports the given storage bus supports.</desc>
7462
7463	<param name="bus" type="StorageBus" dir="in">
7464	<desc>The storage bus type to get the value for.</desc>
7465	</param>
7466
7467	<param name="maxPortCount" type="unsigned long" dir="return">
7468	<desc>The maximum number of ports for the given storage bus.</desc>
7469	</param>
7470	</method>
7471
7472	<method name="getMaxInstancesOfStorageBus">
7473	<desc>Returns the maximum number of storage bus instances which
7474	can be configured for each VM. This corresponds to the number of
7475	storage controllers one can have.</desc>
7476
7477	<param name="bus" type="StorageBus" dir="in">
7478	<desc>The storage bus type to get the value for.</desc>
7479	</param>
7480
7481	<param name="maxInstances" type="unsigned long" dir="return">
7482	<desc>The maximum number of instances for the given storage bus.</desc>
7483	</param>
7484	</method>
7485
7486	<method name="getDeviceTypesForStorageBus">
7487	<desc>Returns list of all the supported device types
7488	(<link to="DeviceType"/>) for the given type of storage
7489	bus.</desc>
7490
7491	<param name="bus" type="StorageBus" dir="in">
7492	<desc>The storage bus type to get the value for.</desc>
7493	</param>
7494
7495	<param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
7496	<desc>The list of all supported device types for the given storage bus.</desc>
7497	</param>
7498	</method>
7499	</interface>
7500
7501	<!--
7502	// IGuest
7503	/////////////////////////////////////////////////////////////////////////
7504	-->
7505
7506	<interface
7507	name="IGuestOSType" extends="$unknown"
7508	uuid="e3f6727e-a09b-41ea-a824-864a176472f3"
7509	wsmap="struct"
7510	>
7511	<desc>
7512	</desc>
7513
7514	<attribute name="familyId" type="wstring" readonly="yes">
7515	<desc>Guest OS family identifier string.</desc>
7516	</attribute>
7517
7518	<attribute name="familyDescription" type="wstring" readonly="yes">
7519	<desc>Human readable description of the guest OS family.</desc>
7520	</attribute>
7521
7522	<attribute name="id" type="wstring" readonly="yes">
7523	<desc>Guest OS identifier string.</desc>
7524	</attribute>
7525
7526	<attribute name="description" type="wstring" readonly="yes">
7527	<desc>Human readable description of the guest OS.</desc>
7528	</attribute>
7529
7530	<attribute name="is64Bit" type="boolean" readonly="yes">
7531	<desc>Returns @c true if the given OS is 64-bit</desc>
7532	</attribute>
7533
7534	<attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
7535	<desc>Returns @c true if IO APIC recommended for this OS type.</desc>
7536	</attribute>
7537
7538	<attribute name="recommendedVirtEx" type="boolean" readonly="yes">
7539	<desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
7540	</attribute>
7541
7542	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
7543	<desc>Recommended RAM size in Megabytes.</desc>
7544	</attribute>
7545
7546	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
7547	<desc>Recommended video RAM size in Megabytes.</desc>
7548	</attribute>
7549
7550	<attribute name="recommendedHDD" type="unsigned long" readonly="yes">
7551	<desc>Recommended hard disk size in Megabytes.</desc>
7552	</attribute>
7553
7554	<attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
7555	<desc>Returns recommended network adapter for this OS type.</desc>
7556	</attribute>
7557
7558	<attribute name="recommendedPae" type="boolean" readonly="yes">
7559	<desc>Returns @c true if using PAE is recommended for this OS type.</desc>
7560	</attribute>
7561
7562	<attribute name="recommendedDvdStorageController" type="StorageControllerType" readonly="yes">
7563	<desc>Recommended storage controller type for DVD/CD drives.</desc>
7564	</attribute>
7565
7566	<attribute name="recommendedDvdStorageBus" type="StorageBus" readonly="yes">
7567	<desc>Recommended storage bus type for DVD/CD drives.</desc>
7568	</attribute>
7569
7570	<attribute name="recommendedHdStorageController" type="StorageControllerType" readonly="yes">
7571	<desc>Recommended storage controller type for HD drives.</desc>
7572	</attribute>
7573
7574	<attribute name="recommendedHdStorageBus" type="StorageBus" readonly="yes">
7575	<desc>Recommended storage bus type for HD drives.</desc>
7576	</attribute>
7577
7578	<attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
7579	<desc>Recommended firmware type.</desc>
7580	</attribute>
7581
7582	<attribute name="recommendedUsbHid" type="boolean" readonly="yes">
7583	<desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
7584	</attribute>
7585
7586	<attribute name="recommendedHpet" type="boolean" readonly="yes">
7587	<desc>Returns @c true if using HPET is recommended for this OS type.</desc>
7588	</attribute>
7589
7590	<attribute name="recommendedUsbTablet" type="boolean" readonly="yes">
7591	<desc>Returns @c true if using a USB Tablet is recommended.</desc>
7592	</attribute>
7593
7594	<attribute name="recommendedRtcUseUtc" type="boolean" readonly="yes">
7595	<desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
7596	</attribute>
7597
7598	</interface>
7599
7600	<interface
7601	name="IGuest" extends="$unknown"
7602	uuid="d915dff1-ed38-495a-91f1-ab6c53932468"
7603	wsmap="managed"
7604	>
7605	<desc>
7606	The IGuest interface represents information about the operating system
7607	running inside the virtual machine. Used in
7608	<link to="IConsole::guest"/>.
7609
7610	IGuest provides information about the guest operating system, whether
7611	Guest Additions are installed and other OS-specific virtual machine
7612	properties.
7613	</desc>
7614
7615	<attribute name="OSTypeId" type="wstring" readonly="yes">
7616	<desc>
7617	Identifier of the Guest OS type as reported by the Guest
7618	Additions.
7619	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
7620	an IGuestOSType object representing details about the given
7621	Guest OS type.
7622	<note>
7623	If Guest Additions are not installed, this value will be
7624	the same as <link to="IMachine::OSTypeId"/>.
7625	</note>
7626	</desc>
7627	</attribute>
7628
7629	<attribute name="additionsActive" type="boolean" readonly="yes">
7630	<desc>
7631	Flag whether the Guest Additions are installed and active
7632	in which case their version will be returned by the
7633	<link to="#additionsVersion"/> property.
7634	</desc>
7635	</attribute>
7636
7637	<attribute name="additionsVersion" type="wstring" readonly="yes">
7638	<desc>
7639	Version of the Guest Additions including the revision (3 decimal numbers
7640	separated by dots + revision number) installed on the guest or empty
7641	when the Additions are not installed.
7642	</desc>
7643	</attribute>
7644
7645	<attribute name="supportsSeamless" type="boolean" readonly="yes">
7646	<desc>
7647	Flag whether seamless guest display rendering (seamless desktop
7648	integration) is supported.
7649	</desc>
7650	</attribute>
7651
7652	<attribute name="supportsGraphics" type="boolean" readonly="yes">
7653	<desc>
7654	Flag whether the guest is in graphics mode. If it is not, then
7655	seamless rendering will not work, resize hints are not immediately
7656	acted on and guest display resizes are probably not initiated by
7657	the guest additions.
7658	</desc>
7659	</attribute>
7660
7661	<attribute name="memoryBalloonSize" type="unsigned long">
7662	<desc>Guest system memory balloon size in megabytes (transient property).</desc>
7663	</attribute>
7664
7665	<attribute name="pageFusionEnabled" type="boolean">
7666	<desc>Flag whether page fusion is enabled or not.</desc>
7667	</attribute>
7668
7669	<attribute name="statisticsUpdateInterval" type="unsigned long">
7670	<desc>Interval to update guest statistics in seconds.</desc>
7671	</attribute>
7672
7673	<method name="internalGetStatistics">
7674	<desc>
7675	Internal method; do not use as it might change at any time
7676	</desc>
7677	<param name="cpuUser" type="unsigned long" dir="out">
7678	<desc>Percentage of processor time spent in user mode as seen by the guest</desc>
7679	</param>
7680	<param name="cpuKernel" type="unsigned long" dir="out">
7681	<desc>Percentage of processor time spent in kernel mode as seen by the guest</desc>
7682	</param>
7683	<param name="cpuIdle" type="unsigned long" dir="out">
7684	<desc>Percentage of processor time spent idling as seen by the guest</desc>
7685	</param>
7686	<param name="memTotal" type="unsigned long" dir="out">
7687	<desc>Total amount of physical guest RAM</desc>
7688	</param>
7689	<param name="memFree" type="unsigned long" dir="out">
7690	<desc>Free amount of physical guest RAM</desc>
7691	</param>
7692	<param name="memBalloon" type="unsigned long" dir="out">
7693	<desc>Amount of ballooned physical guest RAM</desc>
7694	</param>
7695	<param name="memShared" type="unsigned long" dir="out">
7696	<desc>Amount of shared physical guest RAM</desc>
7697	</param>
7698	<param name="memCache" type="unsigned long" dir="out">
7699	<desc>Total amount of guest (disk) cache memory</desc>
7700	</param>
7701	<param name="pagedTotal" type="unsigned long" dir="out">
7702	<desc>Total amount of space in the page file</desc>
7703	</param>
7704	<param name="memAllocTotal" type="unsigned long" dir="out">
7705	<desc>Total amount of memory allocated by the hypervisor</desc>
7706	</param>
7707	<param name="memFreeTotal" type="unsigned long" dir="out">
7708	<desc>Total amount of free memory available in the hypervisor</desc>
7709	</param>
7710	<param name="memBalloonTotal" type="unsigned long" dir="out">
7711	<desc>Total amount of memory ballooned by the hypervisor</desc>
7712	</param>
7713	<param name="memSharedTotal" type="unsigned long" dir="out">
7714	<desc>Total amount of shared memory in the hypervisor</desc>
7715	</param>
7716	</method>
7717
7718	<method name="setCredentials">
7719	<desc>
7720	Store login credentials that can be queried by guest operating
7721	systems with Additions installed. The credentials are transient
7722	to the session and the guest may also choose to erase them. Note
7723	that the caller cannot determine whether the guest operating system
7724	has queried or made use of the credentials.
7725
7726	<result name="VBOX_E_VM_ERROR">
7727	VMM device is not available.
7728	</result>
7729
7730	</desc>
7731	<param name="userName" type="wstring" dir="in">
7732	<desc>User name string, can be empty</desc>
7733	</param>
7734	<param name="password" type="wstring" dir="in">
7735	<desc>Password string, can be empty</desc>
7736	</param>
7737	<param name="domain" type="wstring" dir="in">
7738	<desc>Domain name (guest logon scheme specific), can be empty</desc>
7739	</param>
7740	<param name="allowInteractiveLogon" type="boolean" dir="in">
7741	<desc>
7742	Flag whether the guest should alternatively allow the user to
7743	interactively specify different credentials. This flag might
7744	not be supported by all versions of the Additions.
7745	</desc>
7746	</param>
7747	</method>
7748
7749	<method name="executeProcess">
7750	<desc>
7751	Executes an existing program inside the guest VM.
7752
7753	<result name="VBOX_E_IPRT_ERROR">
7754	Could not execute process.
7755	</result>
7756
7757	</desc>
7758	<param name="execName" type="wstring" dir="in">
7759	<desc>
7760	Full path name of the command to execute on the guest; the
7761	commands has to exists in the guest VM in order to be executed.
7762	</desc>
7763	</param>
7764	<param name="flags" type="unsigned long" dir="in">
7765	<desc>
7766	Execution flags - currently not supported and therefore
7767	has to be set to 0.
7768	</desc>
7769	</param>
7770	<param name="arguments" type="wstring" safearray="yes" dir="in">
7771	<desc>
7772	Array of arguments passed to the execution command.
7773	</desc>
7774	</param>
7775	<param name="environment" type="wstring" safearray="yes" dir="in">
7776	<desc>
7777	Environment variables that can be set while the command is being
7778	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
7779	variable just set its name ("NAME") without a value.
7780	</desc>
7781	</param>
7782	<param name="userName" type="wstring" dir="in">
7783	<desc>
7784	User name under which the command will be executed; has to exist
7785	and have the appropriate rights to execute programs in the VM.
7786	</desc>
7787	</param>
7788	<param name="password" type="wstring" dir="in">
7789	<desc>
7790	Password of the user account specified.
7791	</desc>
7792	</param>
7793	<param name="timeoutMS" type="unsigned long" dir="in">
7794	<desc>
7795	The maximum timeout value (in msec) to wait for finished program
7796	execution. Pass 0 for an infinite timeout.
7797	</desc>
7798	</param>
7799	<param name="pid" type="unsigned long" dir="out">
7800	<desc>
7801	The PID (process ID) of the started command for later reference.
7802	</desc>
7803	</param>
7804	<param name="progress" type="IProgress" dir="return">
7805	<desc>Progress object to track the operation completion.</desc>
7806	</param>
7807	</method>
7808
7809	<method name="getProcessOutput">
7810	<desc>
7811	Retrieves output of a formerly started process.
7812
7813	<result name="VBOX_E_IPRT_ERROR">
7814	Could not retrieve output.
7815	</result>
7816
7817	</desc>
7818	<param name="pid" type="unsigned long" dir="in">
7819	<desc>
7820	Process id returned by earlier executeProcess() call.
7821	</desc>
7822	</param>
7823	<param name="flags" type="unsigned long" dir="in">
7824	<desc>
7825	Flags describing which output to retrieve.
7826	</desc>
7827	</param>
7828	<param name="timeoutMS" type="unsigned long" dir="in">
7829	<desc>
7830	The maximum timeout value (in msec) to wait for output
7831	data. Pass 0 for an infinite timeout.
7832	</desc>
7833	</param>
7834	<param name="size" type="unsigned long long" dir="in">
7835	<desc>
7836	Size in bytes to read in the buffer.
7837	</desc>
7838	</param>
7839	<param name="data" type="octet" dir="return" safearray="yes">
7840	<desc>
7841	Buffer for retrieving the actual output. A data size of 0 means end of file
7842	if the requested size was not 0. This is the unprocessed
7843	output data, i.e. the line ending style depends on the platform of
7844	the system the server is running on.
7845	</desc>
7846	</param>
7847	</method>
7848
7849	<method name="getProcessStatus">
7850	<desc>
7851	Retrieves status, exit code and the exit reason of a formerly started process.
7852
7853	<result name="VBOX_E_IPRT_ERROR">
7854	Process with specified PID was not found.
7855	</result>
7856
7857	</desc>
7858	<param name="pid" type="unsigned long" dir="in">
7859	<desc>
7860	Process id returned by earlier executeProcess() call.
7861	</desc>
7862	</param>
7863	<param name="exitcode" type="unsigned long" dir="out">
7864	<desc>
7865	The exit code (if available).
7866	</desc>
7867	</param>
7868	<param name="flags" type="unsigned long" dir="out">
7869	<desc>
7870	Additional flags of process status (not used at the moment).
7871	</desc>
7872	</param>
7873	<param name="reason" type="unsigned long" dir="return">
7874	<desc>
7875	The current process status.
7876	</desc>
7877	</param>
7878	</method>
7879
7880	</interface>
7881
7882
7883	<!--
7884	// IProgress
7885	/////////////////////////////////////////////////////////////////////////
7886	-->
7887
7888	<interface
7889	name="IProgress" extends="$unknown"
7890	uuid="856aa038-853f-42e2-acf7-6e7b02dbe294"
7891	wsmap="managed"
7892	>
7893	<desc>
7894	The IProgress interface is used to track and control
7895	asynchronous tasks within VirtualBox.
7896
7897	An instance of this is returned every time VirtualBox starts
7898	an asynchronous task (in other words, a separate thread) which
7899	continues to run after a method call returns. For example,
7900	<link to="IConsole::saveState" />, which saves the state of
7901	a running virtual machine, can take a long time to complete.
7902	To be able to display a progress bar, a user interface such as
7903	the VirtualBox graphical user interface can use the IProgress
7904	object returned by that method.
7905
7906	Note that IProgress is a "read-only" interface in the sense
7907	that only the VirtualBox internals behind the Main API can
7908	create and manipulate progress objects, whereas client code
7909	can only use the IProgress object to monitor a task's
7910	progress and, if <link to="#cancelable" /> is @c true,
7911	cancel the task by calling <link to="#cancel" />.
7912
7913	A task represented by IProgress consists of either one or
7914	several sub-operations that run sequentially, one by one (see
7915	<link to="#operation" /> and <link to="#operationCount" />).
7916	Every operation is identified by a number (starting from 0)
7917	and has a separate description.
7918
7919	You can find the individual percentage of completion of the current
7920	operation in <link to="#operationPercent" /> and the
7921	percentage of completion of the task as a whole
7922	in <link to="#percent" />.
7923
7924	Similarly, you can wait for the completion of a particular
7925	operation via <link to="#waitForOperationCompletion" /> or
7926	for the completion of the whole task via
7927	<link to="#waitForCompletion" />.
7928	</desc>
7929
7930	<attribute name="id" type="uuid" mod="string" readonly="yes">
7931	<desc>ID of the task.</desc>
7932	</attribute>
7933
7934	<attribute name="description" type="wstring" readonly="yes">
7935	<desc>Description of the task.</desc>
7936	</attribute>
7937
7938	<attribute name="initiator" type="$unknown" readonly="yes">
7939	<desc>Initiator of the task.</desc>
7940	</attribute>
7941
7942	<attribute name="cancelable" type="boolean" readonly="yes">
7943	<desc>Whether the task can be interrupted.</desc>
7944	</attribute>
7945
7946	<attribute name="percent" type="unsigned long" readonly="yes">
7947	<desc>
7948	Current progress value of the task as a whole, in percent.
7949	This value depends on how many operations are already complete.
7950	Returns 100 if <link to="#completed" /> is @c true.
7951	</desc>
7952	</attribute>
7953
7954	<attribute name="timeRemaining" type="long" readonly="yes">
7955	<desc>
7956	Estimated remaining time until the task completes, in
7957	seconds. Returns 0 once the task has completed; returns -1
7958	if the remaining time cannot be computed, in particular if
7959	the current progress is 0.
7960
7961	Even if a value is returned, the estimate will be unreliable
7962	for low progress values. It will become more reliable as the
7963	task progresses; it is not recommended to display an ETA
7964	before at least 20% of a task have completed.
7965	</desc>
7966	</attribute>
7967
7968	<attribute name="completed" type="boolean" readonly="yes">
7969	<desc>Whether the task has been completed.</desc>
7970	</attribute>
7971
7972	<attribute name="canceled" type="boolean" readonly="yes">
7973	<desc>Whether the task has been canceled.</desc>
7974	</attribute>
7975
7976	<attribute name="resultCode" type="long" readonly="yes">
7977	<desc>
7978	Result code of the progress task.
7979	Valid only if <link to="#completed"/> is @c true.
7980	</desc>
7981	</attribute>
7982
7983	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
7984	<desc>
7985	Extended information about the unsuccessful result of the
7986	progress operation. May be @c null if no extended information
7987	is available.
7988	Valid only if <link to="#completed"/> is @c true and
7989	<link to="#resultCode"/> indicates a failure.
7990	</desc>
7991	</attribute>
7992
7993	<attribute name="operationCount" type="unsigned long" readonly="yes">
7994	<desc>
7995	Number of sub-operations this task is divided into.
7996	Every task consists of at least one suboperation.
7997	</desc>
7998	</attribute>
7999
8000	<attribute name="operation" type="unsigned long" readonly="yes">
8001	<desc>Number of the sub-operation being currently executed.</desc>
8002	</attribute>
8003
8004	<attribute name="operationDescription" type="wstring" readonly="yes">
8005	<desc>
8006	Description of the sub-operation being currently executed.
8007	</desc>
8008	</attribute>
8009
8010	<attribute name="operationPercent" type="unsigned long" readonly="yes">
8011	<desc>Progress value of the current sub-operation only, in percent.</desc>
8012	</attribute>
8013
8014	<attribute name="timeout" type="unsigned long">
8015	<desc>
8016	When non-zero, this specifies the number of milliseconds after which
8017	the operation will automatically be canceled. This can only be set on
8018	cancelable objects.
8019	</desc>
8020	</attribute>
8021
8022	<method name="setCurrentOperationProgress">
8023	<desc>Internal method, not to be called externally.</desc>
8024	<param name="percent" type="unsigned long" dir="in" />
8025	</method>
8026	<method name="setNextOperation">
8027	<desc>Internal method, not to be called externally.</desc>
8028	<param name="nextOperationDescription" type="wstring" dir="in" />
8029	<param name="nextOperationsWeight" type="unsigned long" dir="in" />
8030	</method>
8031
8032	<method name="waitForCompletion">
8033	<desc>
8034	Waits until the task is done (including all sub-operations)
8035	with a given timeout in milliseconds; specify -1 for an indefinite wait.
8036
8037	Note that the VirtualBox/XPCOM/COM/native event queues of the calling
8038	thread are not processed while waiting. Neglecting event queues may
8039	have dire consequences (degrade performance, resource hogs,
8040	deadlocks, etc.), this is specially so for the main thread on
8041	platforms using XPCOM. Callers are adviced wait for short periods
8042	and service their event queues between calls, or to create a worker
8043	thread to do the waiting.
8044
8045	<result name="VBOX_E_IPRT_ERROR">
8046	Failed to wait for task completion.
8047	</result>
8048	</desc>
8049
8050	<param name="timeout" type="long" dir="in">
8051	<desc>
8052	Maximum time in milliseconds to wait or -1 to wait indefinitely.
8053	</desc>
8054	</param>
8055	</method>
8056
8057	<method name="waitForOperationCompletion">
8058	<desc>
8059	Waits until the given operation is done with a given timeout in
8060	milliseconds; specify -1 for an indefinite wait.
8061
8062	See <link to="#waitForCompletion"> for event queue considerations.</link>
8063
8064	<result name="VBOX_E_IPRT_ERROR">
8065	Failed to wait for operation completion.
8066	</result>
8067
8068	</desc>
8069	<param name="operation" type="unsigned long" dir="in">
8070	<desc>
8071	Number of the operation to wait for.
8072	Must be less than <link to="#operationCount"/>.
8073	</desc>
8074	</param>
8075	<param name="timeout" type="long" dir="in">
8076	<desc>
8077	Maximum time in milliseconds to wait or -1 to wait indefinitely.
8078	</desc>
8079	</param>
8080	</method>
8081
8082	<method name="cancel">
8083	<desc>
8084	Cancels the task.
8085	<note>
8086	If <link to="#cancelable"/> is @c false, then this method will fail.
8087	</note>
8088
8089	<result name="VBOX_E_INVALID_OBJECT_STATE">
8090	Operation cannot be canceled.
8091	</result>
8092
8093	</desc>
8094	</method>
8095
8096	</interface>
8097
8098	<!--
8099	// ISnapshot
8100	/////////////////////////////////////////////////////////////////////////
8101	-->
8102
8103	<interface
8104	name="ISnapshot" extends="$unknown"
8105	uuid="1a2d0551-58a4-4107-857e-ef414fc42ffc"
8106	wsmap="managed"
8107	>
8108	<desc>
8109	The ISnapshot interface represents a snapshot of the virtual
8110	machine.
8111
8112	Together with the differencing media that are created
8113	when a snapshot is taken, a machine can be brought back to
8114	the exact state it was in when the snapshot was taken.
8115
8116	The ISnapshot interface has no methods, only attributes; snapshots
8117	are controlled through methods of the <link to="IConsole" /> interface
8118	which also manage the media associated with the snapshot.
8119	The following operations exist:
8120
8121	<ul>
8122	<li><link to="IConsole::takeSnapshot"/>: creates a new snapshot
8123	by creating new, empty differencing images for the machine's
8124	media and saving the VM settings and (if the VM is running)
8125	the current VM state in the snapshot.
8126
8127	The differencing images will then receive all data written to
8128	the machine's media, while their parent (base) images
8129	remain unmodified after the snapshot has been taken (see
8130	<link to="IMedium" /> for details about differencing images).
8131	This simplifies restoring a machine to the state of a snapshot:
8132	only the differencing images need to be deleted.
8133
8134	The current machine state is not changed by taking a snapshot.
8135	If the machine is running, it will resume execution after the
8136	snapshot has been taken.
8137	</li>
8138
8139	<li><link to="IConsole::restoreSnapshot"/>: this goes back to
8140	a previous snapshot. This resets the machine's state to that of
8141	the previous snapshot by deleting the differencing image of each
8142	of the machine's media and setting the machine's settings
8143	and state to the state that was saved in the snapshot (if any).
8144
8145	This destroys the machine's current state.
8146	</li>
8147
8148	<li><link to="IConsole::deleteSnapshot"/>: deletes a snapshot
8149	without affecting the current machine state.
8150
8151	This does not change the machine, but instead frees the resources
8152	allocated when the snapshot was taken: the settings and machine state
8153	is deleted (if any), and the snapshot's differencing image for each
8154	of the machine's media gets merged with its parent image.
8155
8156	Neither the current machine state nor other snapshots are affected
8157	by this operation, except that parent media will be modified
8158	to contain the disk data associated with the snapshot being deleted.
8159	</li>
8160	</ul>
8161
8162	Each snapshot contains the settings of the virtual machine (hardware
8163	configuration etc.). In addition, if the machine was running when the
8164	snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
8165	the current VM state is saved in the snapshot (similarly to what happens
8166	when a VM's state is saved). The snapshot is then said to
8167	be <i>online</i> because when restoring it, the VM will be running.
8168
8169	If the machine is saved (<link to="MachineState_Saved"/>), the snapshot
8170	receives a copy of the execution state file (<link to="IMachine::stateFilePath"/>).
8171
8172	Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
8173	or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
8174	it then contains a so-called "zero execution state", representing a
8175	machine that is powered off.
8176
8177	<h3>Snapshot branches and the "current" snapshot</h3>
8178
8179	Snapshots can be chained, whereby every next snapshot is based on the
8180	previous one. This chaining is related to medium branching
8181	(see the <link to="IMedium"/> description) in that every time
8182	a new snapshot is created, a new differencing medium is implicitly
8183	created for all normal media attached to the machine.
8184
8185	Each virtual machine has a "current snapshot", identified by
8186	<link to="IMachine::currentSnapshot"/>. Presently, this is always set
8187	to the last snapshot in the chain. In a future version of VirtualBox,
8188	it will be possible to reset a machine's current state to that of an
8189	earlier snapshot without deleting the current state so that it will be
8190	possible to create alternative snapshot paths in a snapshot tree.
8191
8192	In the current implementation, multiple snapshot branches within one
8193	virtual machine are not allowed. Every machine has a single branch,
8194	and <link to="IConsole::takeSnapshot"/> operation adds a new
8195	snapshot to the top of that branch.
8196	</desc>
8197
8198	<attribute name="id" type="uuid" mod="string" readonly="yes">
8199	<desc>UUID of the snapshot.</desc>
8200	</attribute>
8201
8202	<attribute name="name" type="wstring">
8203	<desc>Short name of the snapshot.</desc>
8204	</attribute>
8205
8206	<attribute name="description" type="wstring">
8207	<desc>Optional description of the snapshot.</desc>
8208	</attribute>
8209
8210	<attribute name="timeStamp" type="long long" readonly="yes">
8211	<desc>
8212	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
8213	</desc>
8214	</attribute>
8215
8216	<attribute name="online" type="boolean" readonly="yes">
8217	<desc>
8218	@c true if this snapshot is an online snapshot and @c false otherwise.
8219
8220	When this attribute is @c true, the
8221	<link to="IMachine::stateFilePath"/> attribute of the
8222	<link to="#machine"/> object associated with this snapshot
8223	will point to the saved state file. Otherwise, it will be
8224	an empty string.
8225	</desc>
8226	</attribute>
8227
8228	<attribute name="machine" type="IMachine" readonly="yes">
8229	<desc>
8230	Virtual machine this snapshot is taken on. This object
8231	stores all settings the machine had when taking this snapshot.
8232	<note>
8233	The returned machine object is immutable, i.e. no
8234	any settings can be changed.
8235	</note>
8236	</desc>
8237	</attribute>
8238
8239	<attribute name="parent" type="ISnapshot" readonly="yes">
8240	<desc>
8241	Parent snapshot (a snapshot this one is based on), or
8242	@c null if the snapshot has no parent (i.e. is the first snapshot).
8243	</desc>
8244	</attribute>
8245
8246	<attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
8247	<desc>
8248	Child snapshots (all snapshots having this one as a parent).
8249	</desc>
8250	</attribute>
8251
8252	</interface>
8253
8254
8255	<!--
8256	// IMedium
8257	/////////////////////////////////////////////////////////////////////////
8258	-->
8259
8260	<enum
8261	name="MediumState"
8262	uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
8263	>
8264	<desc>
8265	Virtual medium state.
8266	<see>IMedium</see>
8267	</desc>
8268
8269	<const name="NotCreated" value="0">
8270	<desc>
8271	Associated medium storage does not exist (either was not created yet or
8272	was deleted).
8273	</desc>
8274	</const>
8275	<const name="Created" value="1">
8276	<desc>
8277	Associated storage exists and accessible; this gets set if the
8278	accessibility check performed by <link to="IMedium::refreshState" />
8279	was successful.
8280	</desc>
8281	</const>
8282	<const name="LockedRead" value="2">
8283	<desc>
8284	Medium is locked for reading (see <link to="IMedium::lockRead"/>),
8285	no data modification is possible.
8286	</desc>
8287	</const>
8288	<const name="LockedWrite" value="3">
8289	<desc>
8290	Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
8291	no concurrent data reading or modification is possible.
8292	</desc>
8293	</const>
8294	<const name="Inaccessible" value="4">
8295	<desc>
8296	Medium accessiblity check (see <link to="IMedium::refreshState" />) has
8297	not yet been performed, or else, associated medium storage is not
8298	accessible. In the first case, <link to="IMedium::lastAccessError"/>
8299	is empty, in the second case, it describes the error that occured.
8300	</desc>
8301	</const>
8302	<const name="Creating" value="5">
8303	<desc>
8304	Associated medium storage is being created.
8305	</desc>
8306	</const>
8307	<const name="Deleting" value="6">
8308	<desc>
8309	Associated medium storage is being deleted.
8310	</desc>
8311	</const>
8312	</enum>
8313
8314	<enum
8315	name="MediumType"
8316	uuid="46bf1fd4-ad86-4ded-8c49-28bd2d148e5a"
8317	>
8318	<desc>
8319	Virtual medium type.
8320	<see>IMedium</see>
8321	</desc>
8322
8323	<const name="Normal" value="0">
8324	<desc>
8325	Normal medium (attached directly or indirectly, preserved
8326	when taking snapshots).
8327	</desc>
8328	</const>
8329	<const name="Immutable" value="1">
8330	<desc>
8331	Immutable medium (attached indirectly, changes are wiped out
8332	the next time the virtual machine is started).
8333	</desc>
8334	</const>
8335	<const name="Writethrough" value="2">
8336	<desc>
8337	Write through medium (attached directly, ignored when
8338	taking snapshots).
8339	</desc>
8340	</const>
8341	<const name="Shareable" value="3">
8342	<desc>
8343	Allow using this medium concurrently by several machines.
8344	<note>Present since VirtualBox 3.2.0, and accepted since 3.2.8.</note>
8345	</desc>
8346	</const>
8347	</enum>
8348
8349	<enum
8350	name="MediumVariant"
8351	uuid="584ea502-143b-4ab0-ad14-d1028fdf0316"
8352	>
8353	<desc>
8354	Virtual medium image variant. More than one flag may be set.
8355	<see>IMedium</see>
8356	</desc>
8357
8358	<const name="Standard" value="0">
8359	<desc>
8360	No particular variant requested, results in using the backend default.
8361	</desc>
8362	</const>
8363	<const name="VmdkSplit2G" value="0x01">
8364	<desc>
8365	VMDK image split in chunks of less than 2GByte.
8366	</desc>
8367	</const>
8368	<const name="VmdkStreamOptimized" value="0x04">
8369	<desc>
8370	VMDK streamOptimized image. Special import/export format which is
8371	read-only/append-only.
8372	</desc>
8373	</const>
8374	<const name="VmdkESX" value="0x08">
8375	<desc>
8376	VMDK format variant used on ESX products.
8377	</desc>
8378	</const>
8379	<const name="Fixed" value="0x10000">
8380	<desc>
8381	Fixed image. Only allowed for base images.
8382	</desc>
8383	</const>
8384	<const name="Diff" value="0x20000">
8385	<desc>
8386	Differencing image. Only allowed for child images.
8387	</desc>
8388	</const>
8389	</enum>
8390
8391	<interface
8392	name="IMediumAttachment" extends="$unknown"
8393	uuid="c29452cc-ca72-404b-9261-cfc514f1e412"
8394	wsmap="struct"
8395	>
8396	<desc>
8397	The IMediumAttachment interface links storage media to virtual machines.
8398	For each medium (<link to="IMedium"/>) which has been attached to a
8399	storage controller (<link to="IStorageController"/>) of a machine
8400	(<link to="IMachine"/>) via the <link to="IMachine::attachDevice" />
8401	method, one instance of IMediumAttachment is added to the machine's
8402	<link to="IMachine::mediumAttachments"/> array attribute.
8403
8404	Each medium attachment specifies the storage controller as well as a
8405	port and device number and the IMedium instance representing a virtual
8406	hard disk or floppy or DVD image.
8407
8408	For removeable media (DVDs or floppies), there are two additional
8409	options. For one, the IMedium instance can be @c null to represent
8410	an empty drive with no media inserted (see <link to="IMachine::mountMedium" />);
8411	secondly, the medium can be one of the pseudo-media for host drives
8412	listed in <link to="IHost::DVDDrives"/> or <link to="IHost::floppyDrives"/>.
8413	</desc>
8414
8415	<attribute name="medium" type="IMedium" readonly="yes">
8416	<desc>Medium object associated with this attachment; it
8417	can be @c null for removable devices.</desc>
8418	</attribute>
8419
8420	<attribute name="controller" type="wstring" readonly="yes">
8421	<desc>Name of the storage controller of this attachment; this
8422	refers to one of the controllers in <link to="IMachine::storageControllers" />
8423	by name.</desc>
8424	</attribute>
8425
8426	<attribute name="port" type="long" readonly="yes">
8427	<desc>Port number of this attachment.
8428	See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
8429	</desc>
8430	</attribute>
8431
8432	<attribute name="device" type="long" readonly="yes">
8433	<desc>Device slot number of this attachment.
8434	See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
8435	</desc>
8436	</attribute>
8437
8438	<attribute name="type" type="DeviceType" readonly="yes">
8439	<desc>Device type of this attachment.</desc>
8440	</attribute>
8441
8442	<attribute name="passthrough" type="boolean" readonly="yes">
8443	<desc>Pass I/O requests through to a device on the host.</desc>
8444	</attribute>
8445
8446	<attribute name="bandwidthLimit" type="unsigned long">
8447	<desc>
8448	Maximum throughput allowed for this medium attachment, in units of 1 mbps.
8449	A zero value means uncapped/unlimited.
8450	</desc>
8451	</attribute>
8452
8453	</interface>
8454
8455	<interface
8456	name="IMedium" extends="$unknown"
8457	uuid="858ea9d3-9ade-4aa7-91b7-d8a40f8f9b16"
8458	wsmap="managed"
8459	>
8460	<desc>
8461	The IMedium interface represents virtual storage for a machine's
8462	hard disks, CD/DVD or floppy drives. It will typically represent
8463	a disk image on the host, for example a VDI or VMDK file representing
8464	a virtual hard disk, or an ISO or RAW file representing virtual
8465	removable media, but can also point to a network location (e.g.
8466	for iSCSI targets).
8467
8468	Instances of IMedium are connected to virtual machines by way of
8469	medium attachments (see <link to="IMediumAttachment" />), which link
8470	the storage medium to a particular device slot of a storage controller
8471	of the virtual machine.
8472	In the VirtualBox API, virtual storage is therefore always represented
8473	by the following chain of object links:
8474
8475	<ul>
8476	<li><link to="IMachine::storageControllers"/> contains an array of
8477	storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
8478	these are instances of <link to="IStorageController"/>).</li>
8479	<li><link to="IMachine::mediumAttachments"/> contains an array of
8480	medium attachments (instances of <link to="IMediumAttachment"/>),
8481	each containing a storage controller from the above array, a
8482	port/device specification, and an instance of IMedium representing
8483	the medium storage (image file).
8484
8485	For removable media, the storage medium is optional; a medium
8486	attachment with no medium represents a CD/DVD or floppy drive
8487	with no medium inserted. By contrast, hard disk attachments
8488	will always have an IMedium object attached.</li>
8489	<li>Each IMedium in turn points to a storage unit (such as a file
8490	on the host computer or a network resource) that holds actual
8491	data. This location is represented by the <link to="#location"/>
8492	attribute.</li>
8493	</ul>
8494
8495	Existing media are opened using <link to="IVirtualBox::openMedium"/>;
8496	new hard disk media can be created with the VirtualBox API using the
8497	<link to="IVirtualBox::createHardDisk"/> method.
8498
8499	CD/DVD and floppy images (ISO and RAW files) are usually created outside
8500	VirtualBox, e.g. by storing a copy of the real medium of the corresponding
8501	type in a regular file.
8502
8503	Only for CD/DVDs and floppies, an IMedium instance can also represent a host
8504	drive; in that case the <link to="#id" /> attribute contains the UUID of
8505	one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
8506
8507	<h3>Known media</h3>
8508
8509	When an existing medium is opened for the first time, it is automatically
8510	remembered by the given VirtualBox installation or, in other words, becomes
8511	a <i>known medium</i>. Known media are stored in the media
8512	registry transparently maintained by VirtualBox and stored in settings
8513	files so that this registry is preserved when VirtualBox is not running.
8514
8515	Newly created virtual media are remembered only when the associated
8516	storage unit is actually created.
8517
8518	All known media can be enumerated using
8519	<link to="IVirtualBox::hardDisks"/>,
8520	<link to="IVirtualBox::DVDImages"/> and
8521	<link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
8522	quickly found using the <link to="IVirtualBox::findMedium"/> method.
8523
8524	Only known media can be attached to virtual machines.
8525
8526	Removing known media from the media registry is performed when the given
8527	medium is closed using the <link to="#close"/> method or when its
8528	associated storage unit is deleted.
8529
8530	<h3>Accessibility checks</h3>
8531
8532	VirtualBox defers media accessibility checks until the <link to="#refreshState" />
8533	method is called explicitly on a medium. This is done to make the VirtualBox object
8534	ready for serving requests as fast as possible and let the end-user
8535	application decide if it needs to check media accessibility right away or not.
8536
8537	As a result, when VirtualBox starts up (e.g. the VirtualBox
8538	object gets created for the first time), all known media are in the
8539	"Inaccessible" state, but the value of the <link to="#lastAccessError"/>
8540	attribute is an empty string because no actual accessibility check has
8541	been made yet.
8542
8543	After calling <link to="#refreshState" />, a medium is considered
8544	<i>accessible</i> if its storage unit can be read. In that case, the
8545	<link to="#state"/> attribute has a value of "Created". If the storage
8546	unit cannot be read (for example, because it is located on a disconnected
8547	network resource, or was accidentally deleted outside VirtualBox),
8548	the medium is considered <i>inaccessible</i>, which is indicated by the
8549	"Inaccessible" state. The exact reason why the medium is inaccessible can be
8550	obtained by reading the <link to="#lastAccessError"/> attribute.
8551
8552	<h3>Medium types</h3>
8553
8554	There are four types of medium behavior (see <link to="MediumType" />):
8555	"normal", "immutable", "writethrough" and "shareable", represented by the
8556	<link to="#type"/> attribute. The type of the medium defines how the
8557	medium is attached to a virtual machine and what happens when a
8558	<link to="ISnapshot">snapshot</link> of the virtual machine with the
8559	attached medium is taken. At the moment DVD and floppy media are always
8560	of type "writethrough".
8561
8562	All media can be also divided in two groups: <i>base</i> media and
8563	<i>differencing</i> media. A base medium contains all sectors of the
8564	medium data in its own storage and therefore can be used independently.
8565	In contrast, a differencing mediun is a "delta" to some other medium and
8566	contains only those sectors which differ from that other medium, which is
8567	then called a <i>parent</i>. The differencing medium is said to be
8568	<i>linked to</i> that parent. The parent may be itself a differencing
8569	medium, thus forming a chain of linked media. The last element in that
8570	chain must always be a base medium. Note that several differencing
8571	media may be linked to the same parent medium.
8572
8573	Differencing media can be distinguished from base media by querying the
8574	<link to="#parent"/> attribute: base media do not have parents they would
8575	depend on, so the value of this attribute is always @c null for them.
8576	Using this attribute, it is possible to walk up the medium tree (from the
8577	child medium to its parent). It is also possible to walk down the tree
8578	using the <link to="#children"/> attribute.
8579
8580	Note that the type of all differencing media is "normal"; all other
8581	values are meaningless for them. Base media may be of any type.
8582
8583	<h3>Creating hard disks</h3>
8584
8585	New base hard disks are created using
8586	<link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
8587	opened using <link to="IVirtualBox::openMedium"/>. Differencing hard
8588	disks are usually implicitly created by VirtualBox when needed but may
8589	also be created explicitly using <link to="#createDiffStorage"/>.
8590
8591	After the hard disk is successfully created (including the storage unit)
8592	or opened, it becomes a known hard disk (remembered in the internal media
8593	registry). Known hard disks can be attached to a virtual machine, accessed
8594	through <link to="IVirtualBox::findMedium"/> or enumerated using the
8595	<link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
8596
8597	The following methods, besides <link to="IMedium::close"/>,
8598	automatically remove the hard disk from the media registry:
8599	<ul>
8600	<li><link to="#deleteStorage"/></li>
8601	<li><link to="#mergeTo"/></li>
8602	</ul>
8603
8604	If the storage unit of the hard disk is a regular file in the host's
8605	file system then the rules stated in the description of the
8606	<link to="IMedium::location"/> attribute apply when setting its value. In
8607	addition, a plain file name without any path may be given, in which case
8608	the <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
8609	folder</link> will be prepended to it.
8610
8611	<h4>Automatic composition of the file name part</h4>
8612
8613	Another extension to the <link to="IMedium::location"/> attribute is that
8614	there is a possibility to cause VirtualBox to compose a unique value for
8615	the file name part of the location using the UUID of the hard disk. This
8616	applies only to hard disks in <link to="MediumState_NotCreated"/> state,
8617	e.g. before the storage unit is created, and works as follows. You set the
8618	value of the <link to="IMedium::location"/> attribute to a location
8619	specification which only contains the path specification but not the file
8620	name part and ends with either a forward slash or a backslash character.
8621	In response, VirtualBox will generate a new UUID for the hard disk and
8622	compose the file name using the following pattern:
8623	<pre>
8624	<path>/{<uuid>}.<ext>
8625	</pre>
8626	where <tt><path></tt> is the supplied path specification,
8627	<tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
8628	is the default extension for the storage format of this hard disk. After
8629	that, you may call any of the methods that create a new hard disk storage
8630	unit and they will use the generated UUID and file name.
8631
8632	<h3>Attaching Hard Disks</h3>
8633
8634	Hard disks are attached to virtual machines using the
8635	<link to="IMachine::attachDevice"/> method and detached using the
8636	<link to="IMachine::detachDevice"/> method. Depending on their
8637	<link to="#type"/>, hard disks are attached either
8638	<i>directly</i> or <i>indirectly</i>.
8639
8640	When a hard disk is being attached directly, it is associated with the
8641	virtual machine and used for hard disk operations when the machine is
8642	running. When a hard disk is being attached indirectly, a new differencing
8643	hard disk linked to it is implicitly created and this differencing hard
8644	disk is associated with the machine and used for hard disk operations.
8645	This also means that if <link to="IMachine::attachDevice"/> performs
8646	a direct attachment then the same hard disk will be returned in response
8647	to the subsequent <link to="IMachine::getMedium"/> call; however if
8648	an indirect attachment is performed then
8649	<link to="IMachine::getMedium"/> will return the implicitly created
8650	differencing hard disk, not the original one passed to <link
8651	to="IMachine::attachDevice"/>. In detail:
8652
8653	<ul>
8654	<li><b>Normal base</b> hard disks that do not have children (i.e.
8655	differencing hard disks linked to them) and that are not already
8656	attached to virtual machines in snapshots are attached <b>directly</b>.
8657	Otherwise, they are attached <b>indirectly</b> because having
8658	dependent children or being part of the snapshot makes it impossible
8659	to modify hard disk contents without breaking the integrity of the
8660	dependent party. The <link to="#readOnly"/> attribute allows to
8661	quickly determine the kind of the attachment for the given hard
8662	disk. Note that if a normal base hard disk is to be indirectly
8663	attached to a virtual machine with snapshots then a special
8664	procedure called <i>smart attachment</i> is performed (see below).</li>
8665	<li><b>Normal differencing</b> hard disks are like normal base hard disks:
8666	they are attached <b>directly</b> if they do not have children and are
8667	not attached to virtual machines in snapshots, and <b>indirectly</b>
8668	otherwise. Note that the smart attachment procedure is never performed
8669	for differencing hard disks.</li>
8670	<li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
8671	they are designed to be non-writable. If an immutable hard disk is
8672	attached to a virtual machine with snapshots then a special
8673	procedure called smart attachment is performed (see below).</li>
8674	<li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
8675	also as designed. This also means that writethrough hard disks cannot
8676	have other hard disks linked to them at all.</li>
8677	<li><b>Shareable</b> hard disks are always attached <b>directly</b>,
8678	also as designed. This also means that shareable hard disks cannot
8679	have other hard disks linked to them at all. They behave almost
8680	like writethrough hard disks, except that shareable hard disks can
8681	be attached to several virtual machines which are running, allowing
8682	concurrent accesses. You need special cluster software running in
8683	the virtual machines to make use of such disks.</li>
8684	</ul>
8685
8686	Note that the same hard disk, regardless of its type, may be attached to
8687	more than one virtual machine at a time. In this case, the machine that is
8688	started first gains exclusive access to the hard disk and attempts to
8689	start other machines having this hard disk attached will fail until the
8690	first machine is powered down.
8691
8692	Detaching hard disks is performed in a <i>deferred</i> fashion. This means
8693	that the given hard disk remains associated with the given machine after a
8694	successful <link to="IMachine::detachDevice"/> call until
8695	<link to="IMachine::saveSettings"/> is called to save all changes to
8696	machine settings to disk. This deferring is necessary to guarantee that
8697	the hard disk configuration may be restored at any time by a call to
8698	<link to="IMachine::discardSettings"/> before the settings
8699	are saved (committed).
8700
8701	Note that if <link to="IMachine::discardSettings"/> is called after
8702	indirectly attaching some hard disks to the machine but before a call to
8703	<link to="IMachine::saveSettings"/> is made, it will implicitly delete
8704	all differencing hard disks implicitly created by
8705	<link to="IMachine::attachDevice"/> for these indirect attachments.
8706	Such implicitly created hard disks will also be immediately deleted when
8707	detached explicitly using the <link to="IMachine::detachDevice"/>
8708	call if it is made before <link to="IMachine::saveSettings"/>. This
8709	implicit deletion is safe because newly created differencing hard
8710	disks do not contain any user data.
8711
8712	However, keep in mind that detaching differencing hard disks that were
8713	implicitly created by <link to="IMachine::attachDevice"/>
8714	before the last <link to="IMachine::saveSettings"/> call will
8715	<b>not</b> implicitly delete them as they may already contain some data
8716	(for example, as a result of virtual machine execution). If these hard
8717	disks are no more necessary, the caller can always delete them explicitly
8718	using <link to="#deleteStorage"/> after they are actually de-associated
8719	from this machine by the <link to="IMachine::saveSettings"/> call.
8720
8721	<h3>Smart Attachment</h3>
8722
8723	When normal base or immutable hard disks are indirectly attached to a
8724	virtual machine then some additional steps are performed to make sure the
8725	virtual machine will have the most recent "view" of the hard disk being
8726	attached. These steps include walking through the machine's snapshots
8727	starting from the current one and going through ancestors up to the first
8728	snapshot. Hard disks attached to the virtual machine in all
8729	of the encountered snapshots are checked whether they are descendants of
8730	the given normal base or immutable hard disk. The first found child (which
8731	is the differencing hard disk) will be used instead of the normal base or
8732	immutable hard disk as a parent for creating a new differencing hard disk
8733	that will be actually attached to the machine. And only if no descendants
8734	are found or if the virtual machine does not have any snapshots then the
8735	normal base or immutable hard disk will be used itself as a parent for
8736	this differencing hard disk.
8737
8738	It is easier to explain what smart attachment does using the
8739	following example:
8740	<pre>
8741	BEFORE attaching B.vdi: AFTER attaching B.vdi:
8742
8743	Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
8744	Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
8745	Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
8746	Snapshot 4 (none) Snapshot 4 (none)
8747	CurState (none) CurState (D3->D2.vdi)
8748
8749	NOT
8750	...
8751	CurState (D3->B.vdi)
8752	</pre>
8753	The first column is the virtual machine configuration before the base hard
8754	disk <tt>B.vdi</tt> is attached, the second column shows the machine after
8755	this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
8756	mean that the hard disk that is actually attached to the machine is a
8757	differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
8758	another hard disk, <tt>B.vdi</tt>.
8759
8760	As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
8761	from the machine before taking Snapshot 4. Later, after Snapshot 4 was
8762	taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
8763	dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
8764	it cannot be attached directly and needs an indirect attachment (i.e.
8765	implicit creation of a new differencing hard disk). Due to the smart
8766	attachment procedure, the new differencing hard disk
8767	(<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
8768	<tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
8769	<tt>B.vdi</tt> existing for this snapshot branch of the given virtual
8770	machine.
8771
8772	Note that if there is more than one descendant hard disk of the given base
8773	hard disk found in a snapshot, and there is an exact device, channel and
8774	bus match, then this exact match will be used. Otherwise, the youngest
8775	descendant will be picked up.
8776
8777	There is one more important aspect of the smart attachment procedure which
8778	is not related to snapshots at all. Before walking through the snapshots
8779	as described above, the backup copy of the current list of hard disk
8780	attachment is searched for descendants. This backup copy is created when
8781	the hard disk configuration is changed for the first time after the last
8782	<link to="IMachine::saveSettings"/> call and used by
8783	<link to="IMachine::discardSettings"/> to undo the recent hard disk
8784	changes. When such a descendant is found in this backup copy, it will be
8785	simply re-attached back, without creating a new differencing hard disk for
8786	it. This optimization is necessary to make it possible to re-attach the
8787	base or immutable hard disk to a different bus, channel or device slot
8788	without losing the contents of the differencing hard disk actually
8789	attached to the machine in place of it.
8790	</desc>
8791
8792	<attribute name="id" type="uuid" mod="string" readonly="yes">
8793	<desc>
8794	UUID of the medium. For a newly created medium, this value is a randomly
8795	generated UUID.
8796
8797	<note>
8798	For media in one of MediumState_NotCreated, MediumState_Creating or
8799	MediumState_Deleting states, the value of this property is undefined
8800	and will most likely be an empty UUID.
8801	</note>
8802	</desc>
8803	</attribute>
8804
8805	<attribute name="description" type="wstring">
8806	<desc>
8807	Optional description of the medium. For a newly created medium the value
8808	of this attribute is an empty string.
8809
8810	Medium types that don't support this attribute will return E_NOTIMPL in
8811	attempt to get or set this attribute's value.
8812
8813	<note>
8814	For some storage types, reading this attribute may return an outdated
8815	(last known) value when <link to="#state"/> is <link
8816	to="MediumState_Inaccessible"/> or <link
8817	to="MediumState_LockedWrite"/> because the value of this attribute is
8818	stored within the storage unit itself. Also note that changing the
8819	attribute value is not possible in such case, as well as when the
8820	medium is the <link to="MediumState_LockedRead"/> state.
8821	</note>
8822	</desc>
8823	</attribute>
8824
8825	<attribute name="state" type="MediumState" readonly="yes">
8826	<desc>
8827	Returns the current medium state, which is the last state set by
8828	the accessibility check performed by <link to="#refreshState"/>.
8829	If that method has not yet been called on the medium, the state
8830	is "Inaccessible"; as opposed to truly inaccessible media, the
8831	value of <link to="#lastAccessError"/> will be an empty string in
8832	that case.
8833
8834	<note>As of version 3.1, this no longer performs an accessibility check
8835	automatically; call <link to="#refreshState"/> for that.
8836	</note>
8837	</desc>
8838	</attribute>
8839
8840	<attribute name="variant" type="MediumVariant" readonly="yes">
8841	<desc>
8842	Returns the storage format variant information for this medium.
8843	Before <link to="#refreshState"/> is called this method returns
8844	an undefined value.
8845	</desc>
8846	</attribute>
8847
8848	<attribute name="location" type="wstring">
8849	<desc>
8850	Location of the storage unit holding medium data.
8851
8852	The format of the location string is medium type specific. For medium
8853	types using regular files in a host's file system, the location
8854	string is the full file name.
8855
8856	Some medium types may support changing the storage unit location by
8857	simply changing the value of this property. If this operation is not
8858	supported, the implementation will return E_NOTIMPL in attempt to set
8859	this attribute's value.
8860
8861	When setting a value of the location attribute which is a regular file
8862	in the host's file system, the given file name may be either relative to
8863	the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
8864	absolute. Note that if the given location specification does not contain
8865	the file extension part then a proper default extension will be
8866	automatically appended by the implementation depending on the medium type.
8867	</desc>
8868	</attribute>
8869
8870	<attribute name="name" type="wstring" readonly="yes">
8871	<desc>
8872	Name of the storage unit holding medium data.
8873
8874	The returned string is a short version of the <link to="#location"/>
8875	attribute that is suitable for representing the medium in situations
8876	where the full location specification is too long (such as lists
8877	and comboboxes in GUI frontends). This string is also used by frontends
8878	to sort the media list alphabetically when needed.
8879
8880	For example, for locations that are regular files in the host's file
8881	system, the value of this attribute is just the file name (+ extension),
8882	without the path specification.
8883
8884	Note that as opposed to the <link to="#location"/> attribute, the name
8885	attribute will not necessary be unique for a list of media of the
8886	given type and format.
8887	</desc>
8888	</attribute>
8889
8890	<attribute name="deviceType" type="DeviceType" readonly="yes">
8891	<desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
8892	medium.</desc>
8893	</attribute>
8894
8895	<attribute name="hostDrive" type="boolean" readonly="yes">
8896	<desc>True if this corresponds to a drive on the host.</desc>
8897	</attribute>
8898
8899	<attribute name="size" type="unsigned long long" readonly="yes">
8900	<desc>
8901	Physical size of the storage unit used to hold medium data (in bytes).
8902
8903	<note>
8904	For media whose <link to="#state"/> is <link
8905	to="MediumState_Inaccessible"/>, the value of this property is the
8906	last known size. For <link to="MediumState_NotCreated"/> media,
8907	the returned value is zero.
8908	</note>
8909	</desc>
8910	</attribute>
8911
8912	<attribute name="format" type="wstring" readonly="yes">
8913	<desc>
8914	Storage format of this medium.
8915
8916	The value of this attribute is a string that specifies a backend used
8917	to store medium data. The storage format is defined when you create a
8918	new medium or automatically detected when you open an existing medium,
8919	and cannot be changed later.
8920
8921	The list of all storage formats supported by this VirtualBox
8922	installation can be obtained using
8923	<link to="ISystemProperties::mediumFormats"/>.
8924	</desc>
8925	</attribute>
8926
8927	<attribute name="mediumFormat" type="IMediumFormat" readonly="yes">
8928	<desc>
8929	Storage medium format object corresponding to this medium.
8930
8931	The value of this attribute is a reference to the medium format object
8932	that specifies the backend properties used to store medium data. The
8933	storage format is defined when you create a new medium or automatically
8934	detected when you open an existing medium, and cannot be changed later.
8935
8936	<note>@c null is returned if there is no associated medium format
8937	object. This can e.g. happen for medium objects representing host
8938	drives and other special medium objects.</note>
8939	</desc>
8940	</attribute>
8941
8942	<attribute name="type" type="MediumType">
8943	<desc>
8944	Type (role) of this medium.
8945
8946	The following constraints apply when changing the value of this
8947	attribute:
8948	<ul>
8949	<li>If a medium is attached to a virtual machine (either in the
8950	current state or in one of the snapshots), its type cannot be
8951	changed.
8952	</li>
8953	<li>As long as the medium has children, its type cannot be set
8954	to <link to="MediumType_Writethrough"/>.
8955	</li>
8956	<li>The type of all differencing media is
8957	<link to="MediumType_Normal"/> and cannot be changed.
8958	</li>
8959	</ul>
8960
8961	The type of a newly created or opened medium is set to
8962	<link to="MediumType_Normal"/>, except for DVD and floppy media,
8963	which have a type of <link to="MediumType_Writethrough"/>.
8964	</desc>
8965	</attribute>
8966
8967	<attribute name="parent" type="IMedium" readonly="yes">
8968	<desc>
8969	Parent of this medium (the medium this medium is directly based
8970	on).
8971
8972	Only differencing media have parents. For base (non-differencing)
8973	media, @c null is returned.
8974	</desc>
8975	</attribute>
8976
8977	<attribute name="children" type="IMedium" safearray="yes" readonly="yes">
8978	<desc>
8979	Children of this medium (all differencing media directly based
8980	on this medium). A @c null array is returned if this medium
8981	does not have any children.
8982	</desc>
8983	</attribute>
8984
8985	<attribute name="base" type="IMedium" readonly="yes">
8986	<desc>
8987	Base medium of this medium.
8988
8989	If this is a differencing medium, its base medium is the medium
8990	the given medium branch starts from. For all other types of media, this
8991	property returns the medium object itself (i.e. the same object this
8992	property is read on).
8993	</desc>
8994	</attribute>
8995
8996	<attribute name="readOnly" type="boolean" readonly="yes">
8997	<desc>
8998	Returns @c true if this medium is read-only and @c false otherwise.
8999
9000	A medium is considered to be read-only when its contents cannot be
9001	modified without breaking the integrity of other parties that depend on
9002	this medium such as its child media or snapshots of virtual machines
9003	where this medium is attached to these machines. If there are no
9004	children and no such snapshots then there is no dependency and the
9005	medium is not read-only.
9006
9007	The value of this attribute can be used to determine the kind of the
9008	attachment that will take place when attaching this medium to a
9009	virtual machine. If the value is @c false then the medium will
9010	be attached directly. If the value is @c true then the medium
9011	will be attached indirectly by creating a new differencing child
9012	medium for that. See the interface description for more information.
9013
9014	Note that all <link to="MediumType_Immutable">Immutable</link> media
9015	are always read-only while all
9016	<link to="MediumType_Writethrough">Writethrough</link> media are
9017	always not.
9018
9019	<note>
9020	The read-only condition represented by this attribute is related to
9021	the medium type and usage, not to the current
9022	<link to="IMedium::state">medium state</link> and not to the read-only
9023	state of the storage unit.
9024	</note>
9025	</desc>
9026	</attribute>
9027
9028	<attribute name="logicalSize" type="unsigned long long" readonly="yes">
9029	<desc>
9030	Logical size of this medium (in megabytes), as reported to the
9031	guest OS running inside the virtual machine this medium is
9032	attached to. The logical size is defined when the medium is created
9033	and cannot be changed later.
9034
9035	<note>
9036	Reading this property on a differencing medium will return the size
9037	of its <link to="#base"/> medium.
9038	</note>
9039	<note>
9040	For media whose state is <link to="#state"/> is <link
9041	to="MediumState_Inaccessible"/>, the value of this property is the
9042	last known logical size. For <link to="MediumState_NotCreated"/>
9043	media, the returned value is zero.
9044	</note>
9045	</desc>
9046	</attribute>
9047
9048	<attribute name="autoReset" type="boolean">
9049	<desc>
9050	Whether this differencing medium will be automatically reset each
9051	time a virtual machine it is attached to is powered up. This
9052	attribute is automatically set to @c true for the last
9053	differencing image of an "immutable" medium (see
9054	<link to="MediumType" />).
9055
9056	See <link to="#reset"/> for more information about resetting
9057	differencing media.
9058
9059	<note>
9060	Reading this property on a base (non-differencing) medium will
9061	always @c false. Changing the value of this property in this
9062	case is not supported.
9063	</note>
9064
9065	<result name="VBOX_E_NOT_SUPPORTED">
9066	This is not a differencing medium (when changing the attribute
9067	value).
9068	</result>
9069	</desc>
9070	</attribute>
9071
9072	<attribute name="lastAccessError" type="wstring" readonly="yes">
9073	<desc>
9074	Text message that represents the result of the last accessibility
9075	check performed by <link to="#refreshState"/>.
9076
9077	An empty string is returned if the last accessibility check
9078	was successful or has not yet been called. As a result, if
9079	<link to="#state" /> is "Inaccessible" and this attribute is empty,
9080	then <link to="#refreshState"/> has yet to be called; this is the
9081	default value of media after VirtualBox initialization.
9082	A non-empty string indicates a failure and should normally describe
9083	a reason of the failure (for example, a file read error).
9084	</desc>
9085	</attribute>
9086
9087	<attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
9088	<desc>
9089	Array of UUIDs of all machines this medium is attached to.
9090
9091	A @c null array is returned if this medium is not attached to any
9092	machine or to any machine's snapshot.
9093
9094	<note>
9095	The returned array will include a machine even if this medium is not
9096	attached to that machine in the current state but attached to it in
9097	one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
9098	details.
9099	</note>
9100	</desc>
9101	</attribute>
9102
9103	<method name="setIDs">
9104	<desc>
9105	Changes the UUID and parent UUID for a hard disk medium.
9106	</desc>
9107	<param name="setImageId" type="boolean" dir="in">
9108	<desc>
9109	Select whether a new image UUID is set or not.
9110	</desc>
9111	</param>
9112	<param name="imageId" type="uuid" mod="string" dir="in">
9113	<desc>
9114	New UUID for the image. If an empty string is passed, then a new
9115	UUID is automatically created, provided that @a setImageId is @c true.
9116	Specifying a zero UUID is not allowed.
9117	</desc>
9118	</param>
9119	<param name="setParentId" type="boolean" dir="in">
9120	<desc>
9121	Select whether a new parent UUID is set or not.
9122	</desc>
9123	</param>
9124	<param name="parentId" type="uuid" mod="string" dir="in">
9125	<desc>
9126	New parent UUID for the image. If an empty string is passed, then a
9127	new UUID is automatically created, provided @a setParentId is
9128	@c true. A zero UUID is valid.
9129	</desc>
9130	</param>
9131	<result name="E_INVALIDARG">
9132	Invalid parameter combination.
9133	</result>
9134	<result name="VBOX_E_NOT_SUPPORTED">
9135	Medium is not a hard disk medium.
9136	</result>
9137	</method>
9138
9139	<method name="refreshState">
9140	<desc>
9141	If the current medium state (see <link to="MediumState"/>) is one of
9142	"Created", "Inaccessible" or "LockedRead", then this performs an
9143	accessibility check on the medium and sets the value of the <link to="#state"/>
9144	attribute accordingly; that value is also returned for convenience.
9145
9146	For all other state values, this does not perform a refresh but returns
9147	the state only.
9148
9149	The refresh, if performed, may take a long time (several seconds or even
9150	minutes, depending on the storage unit location and format) because it performs an
9151	accessibility check of the storage unit. This check may cause a significant
9152	delay if the storage unit of the given medium is, for example, a file located
9153	on a network share which is not currently accessible due to connectivity
9154	problems. In that case, the call will not return until a timeout
9155	interval defined by the host OS for this operation expires. For this reason,
9156	it is recommended to never read this attribute on the main UI thread to avoid
9157	making the UI unresponsive.
9158
9159	If the last known state of the medium is "Created" and the accessibility
9160	check fails, then the state would be set to "Inaccessible", and
9161	<link to="#lastAccessError"/> may be used to get more details about the
9162	failure. If the state of the medium is "LockedRead", then it remains the
9163	same, and a non-empty value of <link to="#lastAccessError"/> will
9164	indicate a failed accessibility check in this case.
9165
9166	Note that not all medium states are applicable to all medium types.
9167	</desc>
9168	<param name="state" type="MediumState" dir="return">
9169	<desc>
9170	New medium state.
9171	</desc>
9172	</param>
9173	</method>
9174
9175	<method name="getSnapshotIds">
9176	<desc>
9177	Returns an array of UUIDs of all snapshots of the given machine where
9178	this medium is attached to.
9179
9180	If the medium is attached to the machine in the current state, then the
9181	first element in the array will always be the ID of the queried machine
9182	(i.e. the value equal to the @c machineId argument), followed by
9183	snapshot IDs (if any).
9184
9185	If the medium is not attached to the machine in the current state, then
9186	the array will contain only snapshot IDs.
9187
9188	The returned array may be @c null if this medium is not attached
9189	to the given machine at all, neither in the current state nor in one of
9190	the snapshots.
9191	</desc>
9192	<param name="machineId" type="uuid" mod="string" dir="in">
9193	<desc>
9194	UUID of the machine to query.
9195	</desc>
9196	</param>
9197	<param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
9198	<desc>
9199	Array of snapshot UUIDs of the given machine using this medium.
9200	</desc>
9201	</param>
9202	</method>
9203
9204	<method name="lockRead">
9205	<desc>
9206	Locks this medium for reading.
9207
9208	A read lock is shared: many clients can simultaneously lock the
9209	same medium for reading unless it is already locked for writing (see
9210	<link to="#lockWrite"/>) in which case an error is returned.
9211
9212	When the medium is locked for reading, it cannot be modified
9213	from within VirtualBox. This means that any method that changes
9214	the properties of this medium or contents of the storage unit
9215	will return an error (unless explicitly stated otherwise). That
9216	includes an attempt to start a virtual machine that wants to
9217	write to the the medium.
9218
9219	When the virtual machine is started up, it locks for reading all
9220	media it uses in read-only mode. If some medium cannot be locked
9221	for reading, the startup procedure will fail.
9222	A medium is typically locked for reading while it is used by a running
9223	virtual machine but has a depending differencing image that receives
9224	the actual write operations. This way one base medium can have
9225	multiple child differencing images which can be written to
9226	simultaneously. Read-only media such as DVD and floppy images are
9227	also locked for reading only (so they can be in use by multiple
9228	machines simultaneously).
9229
9230	A medium is also locked for reading when it is the source of a
9231	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
9232
9233	The medium locked for reading must be unlocked using the <link
9234	to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
9235	can be nested and must be followed by the same number of paired
9236	<link to="#unlockRead"/> calls.
9237
9238	This method sets the medium state (see <link to="#state"/>) to
9239	"LockedRead" on success. The medium's previous state must be
9240	one of "Created", "Inaccessible" or "LockedRead".
9241
9242	Locking an inaccessible medium is not an error; this method performs
9243	a logical lock that prevents modifications of this medium through
9244	the VirtualBox API, not a physical file-system lock of the underlying
9245	storage unit.
9246
9247	This method returns the current state of the medium
9248	<i>before</i> the operation.
9249
9250	<result name="VBOX_E_INVALID_OBJECT_STATE">
9251	Invalid medium state (e.g. not created, locked, inaccessible,
9252	creating, deleting).
9253	</result>
9254
9255	</desc>
9256	<param name="state" type="MediumState" dir="return">
9257	<desc>
9258	State of the medium after the operation.
9259	</desc>
9260	</param>
9261	</method>
9262
9263	<method name="unlockRead">
9264	<desc>
9265	Cancels the read lock previously set by <link to="#lockRead"/>.
9266
9267	For both success and failure, this method returns the current state
9268	of the medium <i>after</i> the operation.
9269
9270	See <link to="#lockRead"/> for more details.
9271
9272	<result name="VBOX_E_INVALID_OBJECT_STATE">
9273	Medium not locked for reading.
9274	</result>
9275
9276	</desc>
9277	<param name="state" type="MediumState" dir="return">
9278	<desc>
9279	State of the medium after the operation.
9280	</desc>
9281	</param>
9282	</method>
9283
9284	<method name="lockWrite">
9285	<desc>
9286	Locks this medium for writing.
9287
9288	A write lock, as opposed to <link to="#lockRead"/>, is
9289	exclusive: there may be only one client holding a write lock,
9290	and there may be no read locks while the write lock is held.
9291	As a result, read-locking fails if a write lock is held, and
9292	write-locking fails if either a read or another write lock is held.
9293
9294	When a medium is locked for writing, it cannot be modified
9295	from within VirtualBox, and it is not guaranteed that the values
9296	of its properties are up-to-date. Any method that changes the
9297	properties of this medium or contents of the storage unit will
9298	return an error (unless explicitly stated otherwise).
9299
9300	When a virtual machine is started up, it locks for writing all
9301	media it uses to write data to. If any medium could not be locked
9302	for writing, the startup procedure will fail. If a medium has
9303	differencing images, then while the machine is running, only
9304	the last ("leaf") differencing image is locked for writing,
9305	whereas its parents are locked for reading only.
9306
9307	A medium is also locked for writing when it is the target of a
9308	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
9309
9310	The medium locked for writing must be unlocked using the <link
9311	to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
9312
9313	This method sets the medium state (see <link to="#state"/>) to
9314	"LockedWrite" on success. The medium's previous state must be
9315	either "Created" or "Inaccessible".
9316
9317	Locking an inaccessible medium is not an error; this method performs
9318	a logical lock that prevents modifications of this medium through
9319	the VirtualBox API, not a physical file-system lock of the underlying
9320	storage unit.
9321
9322	For both, success and failure, this method returns the current
9323	state of the medium <i>before</i> the operation.
9324
9325	<result name="VBOX_E_INVALID_OBJECT_STATE">
9326	Invalid medium state (e.g. not created, locked, inaccessible,
9327	creating, deleting).
9328	</result>
9329
9330	</desc>
9331	<param name="state" type="MediumState" dir="return">
9332	<desc>
9333	State of the medium after the operation.
9334	</desc>
9335	</param>
9336	</method>
9337
9338	<method name="unlockWrite">
9339	<desc>
9340	Cancels the write lock previously set by <link to="#lockWrite"/>.
9341
9342	For both success and failure, this method returns the current
9343	state of the medium <i>after</i> the operation.
9344
9345	See <link to="#lockWrite"/> for more details.
9346
9347	<result name="VBOX_E_INVALID_OBJECT_STATE">
9348	Medium not locked for writing.
9349	</result>
9350
9351	</desc>
9352	<param name="state" type="MediumState" dir="return">
9353	<desc>
9354	State of the medium after the operation.
9355	</desc>
9356	</param>
9357	</method>
9358
9359	<method name="close">
9360	<desc>
9361	Closes this medium.
9362
9363	The medium must not be attached to any known virtual machine
9364	and must not have any known child media, otherwise the
9365	operation will fail.
9366
9367	When the medium is successfully closed, it is removed from
9368	the list of registered media, but its storage unit is not
9369	deleted. In particular, this means that this medium can
9370	later be opened again using the <link to="IVirtualBox::openMedium"/>
9371	call.
9372
9373	Note that after this method successfully returns, the given medium
9374	object becomes uninitialized. This means that any attempt
9375	to call any of its methods or attributes will fail with the
9376	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
9377
9378	<result name="VBOX_E_INVALID_OBJECT_STATE">
9379	Invalid medium state (other than not created, created or
9380	inaccessible).
9381	</result>
9382	<result name="VBOX_E_OBJECT_IN_USE">
9383	Medium attached to virtual machine.
9384	</result>
9385	<result name="VBOX_E_FILE_ERROR">
9386	Settings file not accessible.
9387	</result>
9388	<result name="VBOX_E_XML_ERROR">
9389	Could not parse the settings file.
9390	</result>
9391
9392	</desc>
9393	</method>
9394
9395	<!-- storage methods -->
9396
9397	<method name="getProperty">
9398	<desc>
9399	Returns the value of the custom medium property with the given name.
9400
9401	The list of all properties supported by the given medium format can
9402	be obtained with <link to="IMediumFormat::describeProperties"/>.
9403
9404	Note that if this method returns an empty string in @a value, the
9405	requested property is supported but currently not assigned any value.
9406
9407	<result name="VBOX_E_OBJECT_NOT_FOUND">
9408	Requested property does not exist (not supported by the format).
9409	</result>
9410	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
9411	</desc>
9412	<param name="name" type="wstring" dir="in">
9413	<desc>Name of the property to get.</desc>
9414	</param>
9415	<param name="value" type="wstring" dir="return">
9416	<desc>Current property value.</desc>
9417	</param>
9418	</method>
9419
9420	<method name="setProperty">
9421	<desc>
9422	Sets the value of the custom medium property with the given name.
9423
9424	The list of all properties supported by the given medium format can
9425	be obtained with <link to="IMediumFormat::describeProperties"/>.
9426
9427	Note that setting the property value to @c null or an empty string is
9428	equivalent to deleting the existing value. A default value (if it is
9429	defined for this property) will be used by the format backend in this
9430	case.
9431
9432	<result name="VBOX_E_OBJECT_NOT_FOUND">
9433	Requested property does not exist (not supported by the format).
9434	</result>
9435	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
9436	</desc>
9437	<param name="name" type="wstring" dir="in">
9438	<desc>Name of the property to set.</desc>
9439	</param>
9440	<param name="value" type="wstring" dir="in">
9441	<desc>Property value to set.</desc>
9442	</param>
9443	</method>
9444
9445	<method name="getProperties">
9446	<desc>
9447	Returns values for a group of properties in one call.
9448
9449	The names of the properties to get are specified using the @a names
9450	argument which is a list of comma-separated property names or
9451	an empty string if all properties are to be returned. Note that currently
9452	the value of this argument is ignored and the method always returns all
9453	existing properties.
9454
9455	The list of all properties supported by the given medium format can
9456	be obtained with <link to="IMediumFormat::describeProperties"/>.
9457
9458	The method returns two arrays, the array of property names corresponding
9459	to the @a names argument and the current values of these properties.
9460	Both arrays have the same number of elements with each elemend at the
9461	given index in the first array corresponds to an element at the same
9462	index in the second array.
9463
9464	Note that for properties that do not have assigned values,
9465	an empty string is returned at the appropriate index in the
9466	@a returnValues array.
9467
9468	</desc>
9469	<param name="names" type="wstring" dir="in">
9470	<desc>
9471	Names of properties to get.
9472	</desc>
9473	</param>
9474	<param name="returnNames" type="wstring" safearray="yes" dir="out">
9475	<desc>Names of returned properties.</desc>
9476	</param>
9477	<param name="returnValues" type="wstring" safearray="yes" dir="return">
9478	<desc>Values of returned properties.</desc>
9479	</param>
9480	</method>
9481
9482	<method name="setProperties">
9483	<desc>
9484	Sets values for a group of properties in one call.
9485
9486	The names of the properties to set are passed in the @a names
9487	array along with the new values for them in the @a values array. Both
9488	arrays have the same number of elements with each elemend at the given
9489	index in the first array corresponding to an element at the same index
9490	in the second array.
9491
9492	If there is at least one property name in @a names that is not valid,
9493	the method will fail before changing the values of any other properties
9494	from the @a names array.
9495
9496	Using this method over <link to="#setProperty"/> is preferred if you
9497	need to set several properties at once since it will result into less
9498	IPC calls.
9499
9500	The list of all properties supported by the given medium format can
9501	be obtained with <link to="IMediumFormat::describeProperties"/>.
9502
9503	Note that setting the property value to @c null or an empty string is
9504	equivalent to deleting the existing value. A default value (if it is
9505	defined for this property) will be used by the format backend in this
9506	case.
9507	</desc>
9508	<param name="names" type="wstring" safearray="yes" dir="in">
9509	<desc>Names of properties to set.</desc>
9510	</param>
9511	<param name="values" type="wstring" safearray="yes" dir="in">
9512	<desc>Values of properties to set.</desc>
9513	</param>
9514	</method>
9515
9516	<!-- storage methods -->
9517
9518	<method name="createBaseStorage">
9519	<desc>
9520	Starts creating a hard disk storage unit (fixed/dynamic, according
9521	to the variant flags) in in the background. The previous storage unit
9522	created for this object, if any, must first be deleted using
9523	<link to="#deleteStorage"/>, otherwise the operation will fail.
9524
9525	Before the operation starts, the medium is placed in
9526	<link to="MediumState_Creating"/> state. If the create operation
9527	fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
9528	state.
9529
9530	After the returned progress object reports that the operation has
9531	successfully completed, the medium state will be set to <link
9532	to="MediumState_Created"/>, the medium will be remembered by this
9533	VirtualBox installation and may be attached to virtual machines.
9534
9535	<result name="VBOX_E_NOT_SUPPORTED">
9536	The variant of storage creation operation is not supported. See <link
9537	to="IMediumFormat::capabilities"/>.
9538	</result>
9539	</desc>
9540	<param name="logicalSize" type="unsigned long long" dir="in">
9541	<desc>Maximum logical size of the medium in megabytes.</desc>
9542	</param>
9543	<param name="variant" type="MediumVariant" dir="in">
9544	<desc>Exact image variant which should be created.</desc>
9545	</param>
9546	<param name="progress" type="IProgress" dir="return">
9547	<desc>Progress object to track the operation completion.</desc>
9548	</param>
9549	</method>
9550
9551	<method name="deleteStorage">
9552	<desc>
9553	Starts deleting the storage unit of this medium.
9554
9555	The medium must not be attached to any known virtual machine and must
9556	not have any known child media, otherwise the operation will fail.
9557	It will also fail if there is no storage unit to delete or if deletion
9558	is already in progress, or if the medium is being in use (locked for
9559	read or for write) or inaccessible. Therefore, the only valid state for
9560	this operation to succeed is <link to="MediumState_Created"/>.
9561
9562	Before the operation starts, the medium is placed in
9563	<link to="MediumState_Deleting"/> state and gets removed from the list
9564	of remembered hard disks (media registry). If the delete operation
9565	fails, the medium will be remembered again and placed back to
9566	<link to="MediumState_Created"/> state.
9567
9568	After the returned progress object reports that the operation is
9569	complete, the medium state will be set to
9570	<link to="MediumState_NotCreated"/> and you will be able to use one of
9571	the storage creation methods to create it again.
9572
9573	<see>#close()</see>
9574
9575	<result name="VBOX_E_OBJECT_IN_USE">
9576	Medium is attached to a virtual machine.
9577	</result>
9578	<result name="VBOX_E_NOT_SUPPORTED">
9579	Storage deletion is not allowed because neither of storage creation
9580	operations are supported. See
9581	<link to="IMediumFormat::capabilities"/>.
9582	</result>
9583
9584	<note>
9585	If the deletion operation fails, it is not guaranteed that the storage
9586	unit still exists. You may check the <link to="IMedium::state"/> value
9587	to answer this question.
9588	</note>
9589	</desc>
9590	<param name="progress" type="IProgress" dir="return">
9591	<desc>Progress object to track the operation completion.</desc>
9592	</param>
9593	</method>
9594
9595	<!-- diff methods -->
9596
9597	<method name="createDiffStorage">
9598	<desc>
9599	Starts creating an empty differencing storage unit based on this
9600	medium in the format and at the location defined by the @a target
9601	argument.
9602
9603	The target medium must be in <link to="MediumState_NotCreated"/>
9604	state (i.e. must not have an existing storage unit). Upon successful
9605	completion, this operation will set the type of the target medium to
9606	<link to="MediumType_Normal"/> and create a storage unit necessary to
9607	represent the differencing medium data in the given format (according
9608	to the storage format of the target object).
9609
9610	After the returned progress object reports that the operation is
9611	successfully complete, the target medium gets remembered by this
9612	VirtualBox installation and may be attached to virtual machines.
9613
9614	<note>
9615	The medium will be set to <link to="MediumState_LockedRead"/>
9616	state for the duration of this operation.
9617	</note>
9618	<result name="VBOX_E_OBJECT_IN_USE">
9619	Medium not in @c NotCreated state.
9620	</result>
9621	</desc>
9622	<param name="target" type="IMedium" dir="in">
9623	<desc>Target medium.</desc>
9624	</param>
9625	<param name="variant" type="MediumVariant" dir="in">
9626	<desc>Exact image variant which should be created.</desc>
9627	</param>
9628	<param name="progress" type="IProgress" dir="return">
9629	<desc>Progress object to track the operation completion.</desc>
9630	</param>
9631	</method>
9632
9633	<method name="mergeTo">
9634	<desc>
9635	Starts merging the contents of this medium and all intermediate
9636	differencing media in the chain to the given target medium.
9637
9638	The target medium must be either a descendant of this medium or
9639	its ancestor (otherwise this method will immediately return a failure).
9640	It follows that there are two logical directions of the merge operation:
9641	from ancestor to descendant (<i>forward merge</i>) and from descendant to
9642	ancestor (<i>backward merge</i>). Let us consider the following medium
9643	chain:
9644
9645	<pre>Base <- Diff_1 <- Diff_2</pre>
9646
9647	Here, calling this method on the <tt>Base</tt> medium object with
9648	<tt>Diff_2</tt> as an argument will be a forward merge; calling it on
9649	<tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
9650	merge. Note that in both cases the contents of the resulting medium
9651	will be the same, the only difference is the medium object that takes
9652	the result of the merge operation. In case of the forward merge in the
9653	above example, the result will be written to <tt>Diff_2</tt>; in case of
9654	the backward merge, the result will be written to <tt>Base</tt>. In
9655	other words, the result of the operation is always stored in the target
9656	medium.
9657
9658	Upon successful operation completion, the storage units of all media in
9659	the chain between this (source) medium and the target medium, including
9660	the source medium itself, will be automatically deleted and the
9661	relevant medium objects (including this medium) will become
9662	uninitialized. This means that any attempt to call any of
9663	their methods or attributes will fail with the
9664	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
9665	example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
9666	delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
9667	Note that <tt>Diff_2</tt> in this case will become a base medium
9668	itself since it will no longer be based on any other medium.
9669
9670	Considering the above, all of the following conditions must be met in
9671	order for the merge operation to succeed:
9672	<ul>
9673	<li>
9674	Neither this (source) medium nor any intermediate
9675	differencing medium in the chain between it and the target
9676	medium is attached to any virtual machine.
9677	</li>
9678	<li>
9679	Neither the source medium nor the target medium is an
9680	<link to="MediumType_Immutable"/> medium.
9681	</li>
9682	<li>
9683	The part of the medium tree from the source medium to the
9684	target medium is a linear chain, i.e. all medium in this
9685	chain have exactly one child which is the next medium in this
9686	chain. The only exception from this rule is the target medium in
9687	the forward merge operation; it is allowed to have any number of
9688	child media because the merge operation will not change its
9689	logical contents (as it is seen by the guest OS or by children).
9690	</li>
9691	<li>
9692	None of the involved media are in
9693	<link to="MediumState_LockedRead"/> or
9694	<link to="MediumState_LockedWrite"/> state.
9695	</li>
9696	</ul>
9697
9698	<note>
9699	This (source) medium and all intermediates will be placed to <link
9700	to="MediumState_Deleting"/> state and the target medium will be
9701	placed to <link to="MediumState_LockedWrite"/> state and for the
9702	duration of this operation.
9703	</note>
9704	</desc>
9705	<param name="target" type="IMedium" dir="in">
9706	<desc>Target medium.</desc>
9707	</param>
9708	<param name="progress" type="IProgress" dir="return">
9709	<desc>Progress object to track the operation completion.</desc>
9710	</param>
9711	</method>
9712
9713	<!-- clone method -->
9714
9715	<method name="cloneTo">
9716	<desc>
9717	Starts creating a clone of this medium in the format and at the
9718	location defined by the @a target argument.
9719
9720	The target medium must be either in <link to="MediumState_NotCreated"/>
9721	state (i.e. must not have an existing storage unit) or in
9722	<link to="MediumState_Created"/> state (i.e. created and not locked, and
9723	big enough to hold the data or else the copy will be partial). Upon
9724	successful completion, the cloned medium will contain exactly the
9725	same sector data as the medium being cloned, except that in the
9726	first case a new UUID for the clone will be randomly generated, and in
9727	the second case the UUID will remain unchanged.
9728
9729	The @a parent argument defines which medium will be the parent
9730	of the clone. Passing a @c null reference indicates that the clone will
9731	be a base image, i.e. completely independent. It is possible to specify
9732	an arbitrary medium for this parameter, including the parent of the
9733	medium which is being cloned. Even cloning to a child of the source
9734	medium is possible. Note that when cloning to an existing image, the
9735	@a parent irgument is ignored.
9736
9737	After the returned progress object reports that the operation is
9738	successfully complete, the target medium gets remembered by this
9739	VirtualBox installation and may be attached to virtual machines.
9740
9741	<note>
9742	This medium will be placed to <link to="MediumState_LockedRead"/>
9743	state for the duration of this operation.
9744	</note>
9745	<result name="E_NOTIMPL">
9746	The specified cloning variant is not supported at the moment.
9747	</result>
9748	</desc>
9749	<param name="target" type="IMedium" dir="in">
9750	<desc>Target medium.</desc>
9751	</param>
9752	<param name="variant" type="MediumVariant" dir="in">
9753	<desc>Exact image variant which should be created.</desc>
9754	</param>
9755	<param name="parent" type="IMedium" dir="in">
9756	<desc>Parent of the cloned medium.</desc>
9757	</param>
9758	<param name="progress" type="IProgress" dir="return">
9759	<desc>Progress object to track the operation completion.</desc>
9760	</param>
9761	</method>
9762
9763	<!-- other methods -->
9764
9765	<method name="compact">
9766	<desc>
9767	Starts compacting of this medium. This means that the medium is
9768	transformed into a possibly more compact storage representation.
9769	This potentially creates temporary images, which can require a
9770	substantial amount of additional disk space.
9771
9772	This medium will be placed to <link to="MediumState_LockedWrite"/>
9773	state and all its parent media (if any) will be placed to
9774	<link to="MediumState_LockedRead"/> state for the duration of this
9775	operation.
9776
9777	Please note that the results can be either returned straight away,
9778	or later as the result of the background operation via the object
9779	returned via the @a progress parameter.
9780
9781	<result name="VBOX_E_NOT_SUPPORTED">
9782	Medium format does not support compacting (but potentially
9783	needs it).
9784	</result>
9785	</desc>
9786	<param name="progress" type="IProgress" dir="return">
9787	<desc>Progress object to track the operation completion.</desc>
9788	</param>
9789	</method>
9790
9791	<method name="resize">
9792	<desc>
9793	Starts resizing this medium. This means that the nominal size of the
9794	medium is set to the new value. Both increasing and decreasing the
9795	size is possible, and there are no safety checks, since VirtualBox
9796	does not make any assumptions about the medium contents.
9797
9798	Resizing usually needs additional disk space, and possibly also
9799	some temporary disk space. Note that resize does not create a full
9800	temporary copy of the medium, so the additional disk space requirement
9801	is usually much lower than using the clone operation.
9802
9803	This medium will be placed to <link to="MediumState_LockedWrite"/>
9804	state for the duration of this operation.
9805
9806	Please note that the results can be either returned straight away,
9807	or later as the result of the background operation via the object
9808	returned via the @a progress parameter.
9809
9810	<result name="VBOX_E_NOT_SUPPORTED">
9811	Medium format does not support resizing.
9812	</result>
9813	</desc>
9814	<param name="logicalSize" type="unsigned long long" dir="in">
9815	<desc>New nominal capacity of the medium in megabytes.</desc>
9816	</param>
9817	<param name="progress" type="IProgress" dir="return">
9818	<desc>Progress object to track the operation completion.</desc>
9819	</param>
9820	</method>
9821
9822	<method name="reset">
9823	<desc>
9824	Starts erasing the contents of this differencing medium.
9825
9826	This operation will reset the differencing medium to its initial
9827	state when it does not contain any sector data and any read operation is
9828	redirected to its parent medium. This automatically gets called
9829	during VM power-up for every medium whose <link to="#autoReset" />
9830	attribute is @c true.
9831
9832	The medium will be write-locked for the duration of this operation (see
9833	<link to="#lockWrite" />).
9834
9835	<result name="VBOX_E_NOT_SUPPORTED">
9836	This is not a differencing medium.
9837	</result>
9838	<result name="VBOX_E_INVALID_OBJECT_STATE">
9839	Medium is not in <link to="MediumState_Created"/> or
9840	<link to="MediumState_Inaccessible"/> state.
9841	</result>
9842	</desc>
9843	<param name="progress" type="IProgress" dir="return">
9844	<desc>Progress object to track the operation completion.</desc>
9845	</param>
9846	</method>
9847
9848	</interface>
9849
9850
9851	<!--
9852	// IMediumFormat
9853	/////////////////////////////////////////////////////////////////////////
9854	-->
9855
9856	<enum
9857	name="DataType"
9858	uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
9859	>
9860	<const name="Int32" value="0"/>
9861	<const name="Int8" value="1"/>
9862	<const name="String" value="2"/>
9863	</enum>
9864
9865	<enum
9866	name="DataFlags"
9867	uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
9868	>
9869	<const name="None" value="0x00"/>
9870	<const name="Mandatory" value="0x01"/>
9871	<const name="Expert" value="0x02"/>
9872	<const name="Array" value="0x04"/>
9873	<const name="FlagMask" value="0x07"/>
9874	</enum>
9875
9876	<enum
9877	name="MediumFormatCapabilities"
9878	uuid="70fcf810-99e8-4edc-aee4-7f51d489e657"
9879	>
9880	<desc>
9881	Medium format capability flags.
9882	</desc>
9883
9884	<const name="Uuid" value="0x01">
9885	<desc>
9886	Supports UUIDs as expected by VirtualBox code.
9887	</desc>
9888	</const>
9889
9890	<const name="CreateFixed" value="0x02">
9891	<desc>
9892	Supports creating fixed size images, allocating all space instantly.
9893	</desc>
9894	</const>
9895
9896	<const name="CreateDynamic" value="0x04">
9897	<desc>
9898	Supports creating dynamically growing images, allocating space on
9899	demand.
9900	</desc>
9901	</const>
9902
9903	<const name="CreateSplit2G" value="0x08">
9904	<desc>
9905	Supports creating images split in chunks of a bit less than 2 GBytes.
9906	</desc>
9907	</const>
9908
9909	<const name="Differencing" value="0x10">
9910	<desc>
9911	Supports being used as a format for differencing media (see <link
9912	to="IMedium::createDiffStorage"/>).
9913	</desc>
9914	</const>
9915
9916	<const name="Asynchronous" value="0x20">
9917	<desc>
9918	Supports asynchronous I/O operations for at least some configurations.
9919	</desc>
9920	</const>
9921
9922	<const name="File" value="0x40">
9923	<desc>
9924	The format backend operates on files (the <link to="IMedium::location"/>
9925	attribute of the medium specifies a file used to store medium
9926	data; for a list of supported file extensions see
9927	<link to="IMediumFormat::fileExtensions"/>).
9928	</desc>
9929	</const>
9930
9931	<const name="Properties" value="0x80">
9932	<desc>
9933	The format backend uses the property interface to configure the storage
9934	location and properties (the <link to="IMediumFormat::describeProperties"/>
9935	method is used to get access to properties supported by the given medium format).
9936	</desc>
9937	</const>
9938
9939	<const name="CapabilityMask" value="0xFF"/>
9940	</enum>
9941
9942	<interface
9943	name="IMediumFormat" extends="$unknown"
9944	uuid="89f52554-d469-4799-9fad-1705e86a08b1"
9945	wsmap="managed"
9946	>
9947	<desc>
9948	The IMediumFormat interface represents a medium format.
9949
9950	Each medium format has an associated backend which is used to handle
9951	media stored in this format. This interface provides information
9952	about the properties of the associated backend.
9953
9954	Each medium format is identified by a string represented by the
9955	<link to="#id"/> attribute. This string is used in calls like
9956	<link to="IVirtualBox::createHardDisk"/> to specify the desired
9957	format.
9958
9959	The list of all supported medium formats can be obtained using
9960	<link to="ISystemProperties::mediumFormats"/>.
9961
9962	<see>IMedium</see>
9963	</desc>
9964
9965	<attribute name="id" type="wstring" readonly="yes">
9966	<desc>
9967	Identifier of this format.
9968
9969	The format identifier is a non-@c null non-empty ASCII string. Note that
9970	this string is case-insensitive. This means that, for example, all of
9971	the following strings:
9972	<pre>
9973	"VDI"
9974	"vdi"
9975	"VdI"</pre>
9976	refer to the same medium format.
9977
9978	This string is used in methods of other interfaces where it is necessary
9979	to specify a medium format, such as
9980	<link to="IVirtualBox::createHardDisk"/>.
9981	</desc>
9982	</attribute>
9983
9984	<attribute name="name" type="wstring" readonly="yes">
9985	<desc>
9986	Human readable description of this format.
9987
9988	Mainly for use in file open dialogs.
9989	</desc>
9990	</attribute>
9991
9992	<attribute name="fileExtensions" type="wstring" safearray="yes" readonly="yes">
9993	<desc>
9994	Array of strings containing the supported file extensions.
9995
9996	The first extension in the array is the extension preferred by the
9997	backend. It is recommended to use this extension when specifying a
9998	location of the storage unit for a new medium.
9999
10000	Note that some backends do not work on files, so this array may be
10001	empty.
10002
10003	<see>IMediumFormat::capabilities</see>
10004	</desc>
10005	</attribute>
10006
10007	<attribute name="capabilities" type="unsigned long" readonly="yes">
10008	<desc>
10009	Capabilities of the format as a set of bit flags.
10010
10011	For the meaning of individual capability flags see
10012	<link to="MediumFormatCapabilities"/>.
10013	</desc>
10014	</attribute>
10015
10016	<method name="describeProperties">
10017	<desc>
10018	Returns several arrays describing the properties supported by this
10019	format.
10020
10021	An element with the given index in each array describes one
10022	property. Thus, the number of elements in each returned array is the
10023	same and corresponds to the number of supported properties.
10024
10025	The returned arrays are filled in only if the
10026	<link to="MediumFormatCapabilities_Properties"/> flag is set.
10027	All arguments must be non-@c null.
10028
10029	<see>DataType</see>
10030	<see>DataFlags</see>
10031	</desc>
10032
10033	<param name="names" type="wstring" safearray="yes" dir="out">
10034	<desc>Array of property names.</desc>
10035	</param>
10036	<param name="description" type="wstring" safearray="yes" dir="out">
10037	<desc>Array of property descriptions.</desc>
10038	</param>
10039	<param name="types" type="DataType" safearray="yes" dir="out">
10040	<desc>Array of property types.</desc>
10041	</param>
10042	<param name="flags" type="unsigned long" safearray="yes" dir="out">
10043	<desc>Array of property flags.</desc>
10044	</param>
10045	<param name="defaults" type="wstring" safearray="yes" dir="out">
10046	<desc>Array of default property values.</desc>
10047	</param>
10048	</method>
10049
10050	</interface>
10051
10052
10053	<!--
10054	// IKeyboard
10055	/////////////////////////////////////////////////////////////////////////
10056	-->
10057
10058	<interface
10059	name="IKeyboard" extends="$unknown"
10060	uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
10061	wsmap="managed"
10062	>
10063	<desc>
10064	The IKeyboard interface represents the virtual machine's keyboard. Used
10065	in <link to="IConsole::keyboard"/>.
10066
10067	Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
10068	to the virtual machine.
10069
10070	</desc>
10071	<method name="putScancode">
10072	<desc>Sends a scancode to the keyboard.
10073
10074	<result name="VBOX_E_IPRT_ERROR">
10075	Could not send scan code to virtual keyboard.
10076	</result>
10077
10078	</desc>
10079	<param name="scancode" type="long" dir="in"/>
10080	</method>
10081
10082	<method name="putScancodes">
10083	<desc>Sends an array of scancodes to the keyboard.
10084
10085	<result name="VBOX_E_IPRT_ERROR">
10086	Could not send all scan codes to virtual keyboard.
10087	</result>
10088
10089	</desc>
10090	<param name="scancodes" type="long" dir="in" safearray="yes"/>
10091	<param name="codesStored" type="unsigned long" dir="return"/>
10092	</method>
10093
10094	<method name="putCAD">
10095	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
10096	function is nothing special, it is just a convenience function
10097	calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
10098
10099	<result name="VBOX_E_IPRT_ERROR">
10100	Could not send all scan codes to virtual keyboard.
10101	</result>
10102
10103	</desc>
10104	</method>
10105
10106	</interface>
10107
10108
10109	<!--
10110	// IMouse
10111	/////////////////////////////////////////////////////////////////////////
10112	-->
10113
10114	<enum
10115	name="MouseButtonState"
10116	uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
10117	>
10118	<desc>
10119	Mouse button state.
10120	</desc>
10121
10122	<const name="LeftButton" value="0x01"/>
10123	<const name="RightButton" value="0x02"/>
10124	<const name="MiddleButton" value="0x04"/>
10125	<const name="WheelUp" value="0x08"/>
10126	<const name="WheelDown" value="0x10"/>
10127	<const name="XButton1" value="0x20"/>
10128	<const name="XButton2" value="0x40"/>
10129	<const name="MouseStateMask" value="0x7F"/>
10130	</enum>
10131
10132	<interface
10133	name="IMouse" extends="$unknown"
10134	uuid="7c0f2eae-f92d-498c-b802-e1a3763774dc"
10135	wsmap="managed"
10136	>
10137	<desc>
10138	The IMouse interface represents the virtual machine's mouse. Used in
10139	<link to="IConsole::mouse"/>.
10140
10141	Through this interface, the virtual machine's virtual mouse can be
10142	controlled.
10143	</desc>
10144
10145	<attribute name="absoluteSupported" type="boolean" readonly="yes">
10146	<desc>
10147	Whether the guest OS supports absolute mouse pointer positioning
10148	or not.
10149	<note>
10150	You can use the <link to="IMouseCapabilityChangedEvent"/>
10151	event to be instantly informed about changes of this attribute
10152	during virtual machine execution.
10153	</note>
10154	<see><link to="#putMouseEventAbsolute"/></see>
10155	</desc>
10156	</attribute>
10157
10158	<attribute name="relativeSupported" type="boolean" readonly="yes">
10159	<desc>
10160	Whether the guest OS supports relative mouse pointer positioning
10161	or not.
10162	<note>
10163	You can use the <link to="IMouseCapabilityChangedEvent"/>
10164	event to be instantly informed about changes of this attribute
10165	during virtual machine execution.
10166	</note>
10167	<see><link to="#putMouseEvent"/></see>
10168	</desc>
10169	</attribute>
10170
10171	<attribute name="needsHostCursor" type="boolean" readonly="yes">
10172	<desc>
10173	Whether the guest OS can currently switch to drawing it's own mouse
10174	cursor on demand.
10175	<note>
10176	You can use the <link to="IMouseCapabilityChangedEvent"/>
10177	event to be instantly informed about changes of this attribute
10178	during virtual machine execution.
10179	</note>
10180	<see><link to="#putMouseEvent"/></see>
10181	</desc>
10182	</attribute>
10183
10184	<method name="putMouseEvent">
10185	<desc>
10186	Initiates a mouse event using relative pointer movements
10187	along x and y axis.
10188
10189	<result name="E_ACCESSDENIED">
10190	Console not powered up.
10191	</result>
10192	<result name="VBOX_E_IPRT_ERROR">
10193	Could not send mouse event to virtual mouse.
10194	</result>
10195
10196	</desc>
10197
10198	<param name="dx" type="long" dir="in">
10199	<desc>
10200	Amount of pixels the mouse should move to the right.
10201	Negative values move the mouse to the left.
10202	</desc>
10203	</param>
10204	<param name="dy" type="long" dir="in">
10205	<desc>
10206	Amount of pixels the mouse should move downwards.
10207	Negative values move the mouse upwards.
10208	</desc>
10209	</param>
10210	<param name="dz" type="long" dir="in">
10211	<desc>
10212	Amount of mouse wheel moves.
10213	Positive values describe clockwise wheel rotations,
10214	negative values describe counterclockwise rotations.
10215	</desc>
10216	</param>
10217	<param name="dw" type="long" dir="in">
10218	<desc>
10219	Amount of horizontal mouse wheel moves.
10220	Positive values describe a movement to the left,
10221	negative values describe a movement to the right.
10222	</desc>
10223	</param>
10224	<param name="buttonState" type="long" dir="in">
10225	<desc>
10226	The current state of mouse buttons. Every bit represents
10227	a mouse button as follows:
10228	<table>
10229	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
10230	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
10231	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
10232	</table>
10233	A value of <tt>1</tt> means the corresponding button is pressed.
10234	otherwise it is released.
10235	</desc>
10236	</param>
10237	</method>
10238
10239	<method name="putMouseEventAbsolute">
10240	<desc>
10241	Positions the mouse pointer using absolute x and y coordinates.
10242	These coordinates are expressed in pixels and
10243	start from <tt>[1,1]</tt> which corresponds to the top left
10244	corner of the virtual display.
10245
10246	<result name="E_ACCESSDENIED">
10247	Console not powered up.
10248	</result>
10249	<result name="VBOX_E_IPRT_ERROR">
10250	Could not send mouse event to virtual mouse.
10251	</result>
10252
10253	<note>
10254	This method will have effect only if absolute mouse
10255	positioning is supported by the guest OS.
10256	</note>
10257
10258	<see><link to="#absoluteSupported"/></see>
10259	</desc>
10260
10261	<param name="x" type="long" dir="in">
10262	<desc>
10263	X coordinate of the pointer in pixels, starting from @c 1.
10264	</desc>
10265	</param>
10266	<param name="y" type="long" dir="in">
10267	<desc>
10268	Y coordinate of the pointer in pixels, starting from @c 1.
10269	</desc>
10270	</param>
10271	<param name="dz" type="long" dir="in">
10272	<desc>
10273	Amount of mouse wheel moves.
10274	Positive values describe clockwise wheel rotations,
10275	negative values describe counterclockwise rotations.
10276	</desc>
10277	</param>
10278	<param name="dw" type="long" dir="in">
10279	<desc>
10280	Amount of horizontal mouse wheel moves.
10281	Positive values describe a movement to the left,
10282	negative values describe a movement to the right.
10283	</desc>
10284	</param>
10285	<param name="buttonState" type="long" dir="in">
10286	<desc>
10287	The current state of mouse buttons. Every bit represents
10288	a mouse button as follows:
10289	<table>
10290	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
10291	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
10292	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
10293	</table>
10294	A value of @c 1 means the corresponding button is pressed.
10295	otherwise it is released.
10296	</desc>
10297	</param>
10298	</method>
10299
10300	</interface>
10301
10302	<!--
10303	// IDisplay
10304	/////////////////////////////////////////////////////////////////////////
10305	-->
10306
10307	<enum
10308	name="FramebufferPixelFormat"
10309	uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
10310	>
10311	<desc>
10312	Format of the video memory buffer. Constants represented by this enum can
10313	be used to test for particular values of <link
10314	to="IFramebuffer::pixelFormat"/>. See also <link
10315	to="IFramebuffer::requestResize"/>.
10316
10317	See also www.fourcc.org for more information about FOURCC pixel formats.
10318	</desc>
10319
10320	<const name="Opaque" value="0">
10321	<desc>
10322	Unknown buffer format (the user may not assume any particular format of
10323	the buffer).
10324	</desc>
10325	</const>
10326	<const name="FOURCC_RGB" value="0x32424752">
10327	<desc>
10328	Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
10329	bit layout).
10330	</desc>
10331	</const>
10332	</enum>
10333
10334	<interface
10335	name="IFramebuffer" extends="$unknown"
10336	uuid="b7ed347a-5765-40a0-ae1c-f543eb4ddeaf"
10337	wsmap="suppress"
10338	>
10339	<attribute name="address" type="octet" mod="ptr" readonly="yes">
10340	<desc>Address of the start byte of the frame buffer.</desc>
10341	</attribute>
10342
10343	<attribute name="width" type="unsigned long" readonly="yes">
10344	<desc>Frame buffer width, in pixels.</desc>
10345	</attribute>
10346
10347	<attribute name="height" type="unsigned long" readonly="yes">
10348	<desc>Frame buffer height, in pixels.</desc>
10349	</attribute>
10350
10351	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
10352	<desc>
10353	Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
10354	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
10355	are: 8, 15, 16, 24 and 32.
10356	</desc>
10357	</attribute>
10358
10359	<attribute name="bytesPerLine" type="unsigned long" readonly="yes">
10360	<desc>
10361	Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
10362	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
10363	size of the scan line must be aligned to 32 bits.
10364	</desc>
10365	</attribute>
10366
10367	<attribute name="pixelFormat" type="unsigned long" readonly="yes">
10368	<desc>
10369	Frame buffer pixel format. It's either one of the values defined by <link
10370	to="FramebufferPixelFormat"/> or a raw FOURCC code.
10371	<note>
10372	This attribute must never return <link
10373	to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
10374	<link to="#address"/> points to must be always known.
10375	</note>
10376	</desc>
10377	</attribute>
10378
10379	<attribute name="usesGuestVRAM" type="boolean" readonly="yes">
10380	<desc>
10381	Defines whether this frame buffer uses the virtual video card's memory
10382	buffer (guest VRAM) directly or not. See <link
10383	to="IFramebuffer::requestResize"/> for more information.
10384	</desc>
10385	</attribute>
10386
10387	<attribute name="heightReduction" type="unsigned long" readonly="yes">
10388	<desc>
10389	Hint from the frame buffer about how much of the standard
10390	screen height it wants to use for itself. This information is
10391	exposed to the guest through the VESA BIOS and VMMDev interface
10392	so that it can use it for determining its video mode table. It
10393	is not guaranteed that the guest respects the value.
10394	</desc>
10395	</attribute>
10396
10397	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
10398	<desc>
10399	An alpha-blended overlay which is superposed over the frame buffer.
10400	The initial purpose is to allow the display of icons providing
10401	information about the VM state, including disk activity, in front
10402	ends which do not have other means of doing that. The overlay is
10403	designed to controlled exclusively by IDisplay. It has no locking
10404	of its own, and any changes made to it are not guaranteed to be
10405	visible until the affected portion of IFramebuffer is updated. The
10406	overlay can be created lazily the first time it is requested. This
10407	attribute can also return @c null to signal that the overlay is not
10408	implemented.
10409	</desc>
10410	</attribute>
10411
10412	<attribute name="winId" type="unsigned long long" readonly="yes">
10413	<desc>
10414	Platform-dependent identifier of the window where context of this
10415	frame buffer is drawn, or zero if there's no such window.
10416	</desc>
10417	</attribute>
10418
10419	<method name="lock">
10420	<desc>
10421	Locks the frame buffer.
10422	Gets called by the IDisplay object where this frame buffer is
10423	bound to.
10424	</desc>
10425	</method>
10426
10427	<method name="unlock">
10428	<desc>
10429	Unlocks the frame buffer.
10430	Gets called by the IDisplay object where this frame buffer is
10431	bound to.
10432	</desc>
10433	</method>
10434
10435	<method name="notifyUpdate">
10436	<desc>
10437	Informs about an update.
10438	Gets called by the display object where this buffer is
10439	registered.
10440	</desc>
10441	<param name="x" type="unsigned long" dir="in"/>
10442	<param name="y" type="unsigned long" dir="in"/>
10443	<param name="width" type="unsigned long" dir="in"/>
10444	<param name="height" type="unsigned long" dir="in"/>
10445	</method>
10446
10447	<method name="requestResize">
10448	<desc>
10449	Requests a size and pixel format change.
10450
10451	There are two modes of working with the video buffer of the virtual
10452	machine. The <i>indirect</i> mode implies that the IFramebuffer
10453	implementation allocates a memory buffer for the requested display mode
10454	and provides it to the virtual machine. In <i>direct</i> mode, the
10455	IFramebuffer implementation uses the memory buffer allocated and owned
10456	by the virtual machine. This buffer represents the video memory of the
10457	emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
10458	usually faster because the implementation gets a raw pointer to the
10459	guest VRAM buffer which it can directly use for visualizing the contents
10460	of the virtual display, as opposed to the indirect mode where the
10461	contents of guest VRAM are copied to the memory buffer provided by
10462	the implementation every time a display update occurs.
10463
10464	It is important to note that the direct mode is really fast only when
10465	the implementation uses the given guest VRAM buffer directly, for
10466	example, by blitting it to the window representing the virtual machine's
10467	display, which saves at least one copy operation comparing to the
10468	indirect mode. However, using the guest VRAM buffer directly is not
10469	always possible: the format and the color depth of this buffer may be
10470	not supported by the target window, or it may be unknown (opaque) as in
10471	case of text or non-linear multi-plane VGA video modes. In this case,
10472	the indirect mode (that is always available) should be used as a
10473	fallback: when the guest VRAM contents are copied to the
10474	implementation-provided memory buffer, color and format conversion is
10475	done automatically by the underlying code.
10476
10477	The @a pixelFormat parameter defines whether the direct mode is
10478	available or not. If @a pixelFormat is <link
10479	to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
10480	VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
10481	@a bytesPerLine parameters must be ignored and the implementation must use
10482	the indirect mode (where it provides its own buffer in one of the
10483	supported formats). In all other cases, @a pixelFormat together with
10484	@a bitsPerPixel and @a bytesPerLine define the format of the video memory
10485	buffer pointed to by the @a VRAM parameter and the implementation is
10486	free to choose which mode to use. To indicate that this frame buffer uses
10487	the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
10488	attribute must return @c true and <link to="#address"/> must
10489	return exactly the same address that is passed in the @a VRAM parameter
10490	of this method; otherwise it is assumed that the indirect strategy is
10491	chosen.
10492
10493	The @a width and @a height parameters represent the size of the
10494	requested display mode in both modes. In case of indirect mode, the
10495	provided memory buffer should be big enough to store data of the given
10496	display mode. In case of direct mode, it is guaranteed that the given
10497	@a VRAM buffer contains enough space to represent the display mode of the
10498	given size. Note that this frame buffer's <link to="#width"/> and <link
10499	to="#height"/> attributes must return exactly the same values as
10500	passed to this method after the resize is completed (see below).
10501
10502	The @a finished output parameter determines if the implementation has
10503	finished resizing the frame buffer or not. If, for some reason, the
10504	resize cannot be finished immediately during this call, @a finished
10505	must be set to @c false, and the implementation must call
10506	<link to="IDisplay::resizeCompleted"/> after it has returned from
10507	this method as soon as possible. If @a finished is @c false, the
10508	machine will not call any frame buffer methods until
10509	<link to="IDisplay::resizeCompleted"/> is called.
10510
10511	Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
10512	<link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
10513	this frame buffer must return exactly the same values as specified in the
10514	parameters of this method, after the resize is completed. If the
10515	indirect mode is chosen, these attributes must return values describing
10516	the format of the implementation's own memory buffer <link
10517	to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
10518	value must always correlate with <link to="#pixelFormat"/>. Note that
10519	the <link to="#pixelFormat"/> attribute must never return <link
10520	to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
10521
10522	<note>
10523	This method is called by the IDisplay object under the
10524	<link to="#lock"/> provided by this IFramebuffer
10525	implementation. If this method returns @c false in @a finished, then
10526	this lock is not released until
10527	<link to="IDisplay::resizeCompleted"/> is called.
10528	</note>
10529	</desc>
10530	<param name="screenId" type="unsigned long" dir="in">
10531	<desc>
10532	Logical screen number. Must be used in the corresponding call to
10533	<link to="IDisplay::resizeCompleted"/> if this call is made.
10534	</desc>
10535	</param>
10536	<param name="pixelFormat" type="unsigned long" dir="in">
10537	<desc>
10538	Pixel format of the memory buffer pointed to by @a VRAM.
10539	See also <link to="FramebufferPixelFormat"/>.
10540	</desc>
10541	</param>
10542	<param name="VRAM" type="octet" mod="ptr" dir="in">
10543	<desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
10544	</param>
10545	<param name="bitsPerPixel" type="unsigned long" dir="in">
10546	<desc>Color depth, bits per pixel.</desc>
10547	</param>
10548	<param name="bytesPerLine" type="unsigned long" dir="in">
10549	<desc>Size of one scan line, in bytes.</desc>
10550	</param>
10551	<param name="width" type="unsigned long" dir="in">
10552	<desc>Width of the guest display, in pixels.</desc>
10553	</param>
10554	<param name="height" type="unsigned long" dir="in">
10555	<desc>Height of the guest display, in pixels.</desc>
10556	</param>
10557	<param name="finished" type="boolean" dir="return">
10558	<desc>
10559	Can the VM start using the new frame buffer immediately
10560	after this method returns or it should wait for
10561	<link to="IDisplay::resizeCompleted"/>.
10562	</desc>
10563	</param>
10564	</method>
10565
10566	<method name="videoModeSupported">
10567	<desc>
10568	Returns whether the frame buffer implementation is willing to
10569	support a given video mode. In case it is not able to render
10570	the video mode (or for some reason not willing), it should
10571	return @c false. Usually this method is called when the guest
10572	asks the VMM device whether a given video mode is supported
10573	so the information returned is directly exposed to the guest.
10574	It is important that this method returns very quickly.
10575	</desc>
10576	<param name="width" type="unsigned long" dir="in"/>
10577	<param name="height" type="unsigned long" dir="in"/>
10578	<param name="bpp" type="unsigned long" dir="in"/>
10579	<param name="supported" type="boolean" dir="return"/>
10580	</method>
10581
10582	<method name="getVisibleRegion">
10583	<desc>
10584	Returns the visible region of this frame buffer.
10585
10586	If the @a rectangles parameter is @c null then the value of the
10587	@a count parameter is ignored and the number of elements necessary to
10588	describe the current visible region is returned in @a countCopied.
10589
10590	If @a rectangles is not @c null but @a count is less
10591	than the required number of elements to store region data, the method
10592	will report a failure. If @a count is equal or greater than the
10593	required number of elements, then the actual number of elements copied
10594	to the provided array will be returned in @a countCopied.
10595
10596	<note>
10597	The address of the provided array must be in the process space of
10598	this IFramebuffer object.
10599	</note>
10600	<note>
10601	Method not yet implemented.
10602	</note>
10603	</desc>
10604	<param name="rectangles" type="octet" mod="ptr" dir="in">
10605	<desc>Pointer to the @c RTRECT array to receive region data.</desc>
10606	</param>
10607	<param name="count" type="unsigned long" dir="in">
10608	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
10609	</param>
10610	<param name="countCopied" type="unsigned long" dir="return">
10611	<desc>Number of elements copied to the @a rectangles array.</desc>
10612	</param>
10613	</method>
10614
10615	<method name="setVisibleRegion">
10616	<desc>
10617	Suggests a new visible region to this frame buffer. This region
10618	represents the area of the VM display which is a union of regions of
10619	all top-level windows of the guest operating system running inside the
10620	VM (if the Guest Additions for this system support this
10621	functionality). This information may be used by the frontends to
10622	implement the seamless desktop integration feature.
10623
10624	<note>
10625	The address of the provided array must be in the process space of
10626	this IFramebuffer object.
10627	</note>
10628	<note>
10629	The IFramebuffer implementation must make a copy of the provided
10630	array of rectangles.
10631	</note>
10632	<note>
10633	Method not yet implemented.
10634	</note>
10635	</desc>
10636	<param name="rectangles" type="octet" mod="ptr" dir="in">
10637	<desc>Pointer to the @c RTRECT array.</desc>
10638	</param>
10639	<param name="count" type="unsigned long" dir="in">
10640	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
10641	</param>
10642	</method>
10643
10644	<method name="processVHWACommand">
10645	<desc>
10646	Posts a Video HW Acceleration Command to the frame buffer for processing.
10647	The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color covnersion, overlaying, etc.)
10648	are posted from quest to the host to be processed by the host hardware.
10649
10650	<note>
10651	The address of the provided command must be in the process space of
10652	this IFramebuffer object.
10653	</note>
10654	</desc>
10655
10656	<param name="command" type="octet" mod="ptr" dir="in">
10657	<desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
10658	</param>
10659	</method>
10660
10661	</interface>
10662
10663	<interface
10664	name="IFramebufferOverlay" extends="IFramebuffer"
10665	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
10666	wsmap="suppress"
10667	>
10668	<desc>
10669	The IFramebufferOverlay interface represents an alpha blended overlay
10670	for displaying status icons above an IFramebuffer. It is always created
10671	not visible, so that it must be explicitly shown. It only covers a
10672	portion of the IFramebuffer, determined by its width, height and
10673	co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
10674	that order) format, and may be written to directly. Do re-read the
10675	width though, after setting it, as it may be adjusted (increased) to
10676	make it more suitable for the front end.
10677	</desc>
10678	<attribute name="x" type="unsigned long" readonly="yes">
10679	<desc>X position of the overlay, relative to the frame buffer.</desc>
10680	</attribute>
10681
10682	<attribute name="y" type="unsigned long" readonly="yes">
10683	<desc>Y position of the overlay, relative to the frame buffer.</desc>
10684	</attribute>
10685
10686	<attribute name="visible" type="boolean" readonly="no">
10687	<desc>
10688	Whether the overlay is currently visible.
10689	</desc>
10690	</attribute>
10691
10692	<attribute name="alpha" type="unsigned long" readonly="no">
10693	<desc>
10694	The global alpha value for the overlay. This may or may not be
10695	supported by a given front end.
10696	</desc>
10697	</attribute>
10698
10699	<method name="move">
10700	<desc>
10701	Changes the overlay's position relative to the IFramebuffer.
10702	</desc>
10703	<param name="x" type="unsigned long" dir="in"/>
10704	<param name="y" type="unsigned long" dir="in"/>
10705	</method>
10706
10707	</interface>
10708
10709	<interface
10710	name="IDisplay" extends="$unknown"
10711	uuid="1fa79e39-0cc9-4ab3-9df3-ed3e96b42496"
10712	wsmap="managed"
10713	>
10714	<desc>
10715	The IDisplay interface represents the virtual machine's display.
10716
10717	The object implementing this interface is contained in each
10718	<link to="IConsole::display"/> attribute and represents the visual
10719	output of the virtual machine.
10720
10721	The virtual display supports pluggable output targets represented by the
10722	IFramebuffer interface. Examples of the output target are a window on
10723	the host computer or an RDP session's display on a remote computer.
10724	</desc>
10725	<method name="getScreenResolution">
10726	<desc>Queries display width, height and color depth for given screen.</desc>
10727	<param name="screenId" type="unsigned long" dir="in"/>
10728	<param name="width" type="unsigned long" dir="out"/>
10729	<param name="height" type="unsigned long" dir="out"/>
10730	<param name="bitsPerPixel" type="unsigned long" dir="out"/>
10731	</method>
10732
10733	<method name="setFramebuffer">
10734	<desc>
10735	Sets the framebuffer for given screen.
10736	</desc>
10737	<param name="screenId" type="unsigned long" dir="in"/>
10738	<param name="framebuffer" type="IFramebuffer" dir="in"/>
10739	</method>
10740
10741	<method name="getFramebuffer">
10742	<desc>
10743	Queries the framebuffer for given screen.
10744	</desc>
10745	<param name="screenId" type="unsigned long" dir="in"/>
10746	<param name="framebuffer" type="IFramebuffer" dir="out"/>
10747	<param name="xOrigin" type="long" dir="out"/>
10748	<param name="yOrigin" type="long" dir="out"/>
10749	</method>
10750
10751	<method name="setVideoModeHint">
10752	<desc>
10753	Asks VirtualBox to request the given video mode from
10754	the guest. This is just a hint and it cannot be guaranteed
10755	that the requested resolution will be used. Guest Additions
10756	are required for the request to be seen by guests. The caller
10757	should issue the request and wait for a resolution change and
10758	after a timeout retry.
10759
10760	Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
10761	parameters means that the corresponding values should be taken from the
10762	current video mode (i.e. left unchanged).
10763
10764	If the guest OS supports multi-monitor configuration then the @a display
10765	parameter specifies the number of the guest display to send the hint to:
10766	@c 0 is the primary display, @c 1 is the first secondary and
10767	so on. If the multi-monitor configuration is not supported, @a display
10768	must be @c 0.
10769
10770	<result name="E_INVALIDARG">
10771	The @a display is not associated with any monitor.
10772	</result>
10773
10774	</desc>
10775	<param name="width" type="unsigned long" dir="in"/>
10776	<param name="height" type="unsigned long" dir="in"/>
10777	<param name="bitsPerPixel" type="unsigned long" dir="in"/>
10778	<param name="display" type="unsigned long" dir="in"/>
10779	</method>
10780
10781	<method name="setSeamlessMode">
10782	<desc>
10783	Enables or disables seamless guest display rendering (seamless desktop
10784	integration) mode.
10785	<note>
10786	Calling this method has no effect if <link
10787	to="IGuest::supportsSeamless"/> returns @c false.
10788	</note>
10789	</desc>
10790	<param name="enabled" type="boolean" dir="in"/>
10791	</method>
10792
10793	<method name="takeScreenShot">
10794	<desc>
10795	Takes a screen shot of the requested size and copies it to the
10796	32-bpp buffer allocated by the caller and pointed to by @a address.
10797	A pixel consists of 4 bytes in order: B, G, R, 0.
10798
10799	<note>This API can be used only by the COM/XPCOM C++ API as it
10800	requires pointer support. Use <link to="#takeScreenShotToArray" />
10801	with other language bindings.
10802	</note>
10803
10804	<result name="E_NOTIMPL">
10805	Feature not implemented.
10806	</result>
10807	<result name="VBOX_E_IPRT_ERROR">
10808	Could not take a screenshot.
10809	</result>
10810
10811	</desc>
10812	<param name="screenId" type="unsigned long" dir="in"/>
10813	<param name="address" type="octet" mod="ptr" dir="in"/>
10814	<param name="width" type="unsigned long" dir="in"/>
10815	<param name="height" type="unsigned long" dir="in"/>
10816	</method>
10817
10818	<method name="takeScreenShotToArray">
10819	<desc>
10820	Takes a guest screen shot of the requested size and returns it as
10821	an array of bytes in uncompressed 32-bit RGBA format.
10822	A pixel consists of 4 bytes in order: R, G, B, 0xFF.
10823
10824	This API is slow, but could be the only option to get guest screenshot
10825	for scriptable languages not allowed to manipulate with addresses
10826	directly.
10827
10828	<result name="E_NOTIMPL">
10829	Feature not implemented.
10830	</result>
10831	<result name="VBOX_E_IPRT_ERROR">
10832	Could not take a screenshot.
10833	</result>
10834	</desc>
10835	<param name="screenId" type="unsigned long" dir="in">
10836	<desc>
10837	Monitor to take screenshot from.
10838	</desc>
10839	</param>
10840	<param name="width" type="unsigned long" dir="in">
10841	<desc>
10842	Desired image width.
10843	</desc>
10844	</param>
10845	<param name="height" type="unsigned long" dir="in">
10846	<desc>
10847	Desired image height.
10848	</desc>
10849	</param>
10850	<param name="screenData" type="octet" dir="return" safearray="yes">
10851	<desc>
10852	Array with resulting screen data.
10853	</desc>
10854	</param>
10855	</method>
10856
10857	<method name="drawToScreen">
10858	<desc>
10859	Draws a 32-bpp image of the specified size from the given buffer
10860	to the given point on the VM display.
10861
10862	<result name="E_NOTIMPL">
10863	Feature not implemented.
10864	</result>
10865	<result name="VBOX_E_IPRT_ERROR">
10866	Could not draw to screen.
10867	</result>
10868
10869	</desc>
10870	<param name="screenId" type="unsigned long" dir="in"/>
10871	<param name="address" type="octet" mod="ptr" dir="in"/>
10872	<param name="x" type="unsigned long" dir="in">
10873	<desc>Relative to the screen top left corner.</desc>
10874	</param>
10875	<param name="y" type="unsigned long" dir="in">
10876	<desc>Relative to the screen top left corner.</desc>
10877	</param>
10878	<param name="width" type="unsigned long" dir="in"/>
10879	<param name="height" type="unsigned long" dir="in"/>
10880	</method>
10881
10882	<method name="invalidateAndUpdate">
10883	<desc>
10884	Does a full invalidation of the VM display and instructs the VM
10885	to update it.
10886
10887	<result name="VBOX_E_IPRT_ERROR">
10888	Could not invalidate and update screen.
10889	</result>
10890
10891	</desc>
10892	</method>
10893
10894	<method name="resizeCompleted">
10895	<desc>
10896	Signals that a framebuffer has completed the resize operation.
10897
10898	<result name="VBOX_E_NOT_SUPPORTED">
10899	Operation only valid for external frame buffers.
10900	</result>
10901
10902	</desc>
10903	<param name="screenId" type="unsigned long" dir="in"/>
10904	</method>
10905
10906	<method name="completeVHWACommand">
10907	<desc>
10908	Signals that the Video HW Acceleration command has completed.
10909	</desc>
10910
10911	<param name="command" type="octet" mod="ptr" dir="in">
10912	<desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
10913	</param>
10914	</method>
10915
10916	</interface>
10917
10918	<!--
10919	// INetworkAdapter
10920	/////////////////////////////////////////////////////////////////////////
10921	-->
10922
10923	<enum
10924	name="NetworkAttachmentType"
10925	uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
10926	>
10927	<desc>
10928	Network attachment type.
10929	</desc>
10930
10931	<const name="Null" value="0">
10932	<desc>Null value, also means "not attached".</desc>
10933	</const>
10934	<const name="NAT" value="1"/>
10935	<const name="Bridged" value="2"/>
10936	<const name="Internal" value="3"/>
10937	<const name="HostOnly" value="4"/>
10938	<const name="VDE" value="5"/>
10939	</enum>
10940
10941	<enum
10942	name="NetworkAdapterType"
10943	uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
10944	>
10945	<desc>
10946	Network adapter type.
10947	</desc>
10948
10949	<const name="Null" value="0">
10950	<desc>Null value (never used by the API).</desc>
10951	</const>
10952	<const name="Am79C970A" value="1">
10953	<desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
10954	</const>
10955	<const name="Am79C973" value="2">
10956	<desc>AMD PCNet-FAST III network card (Am79C973).</desc>
10957	</const>
10958	<const name="I82540EM" value="3">
10959	<desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
10960	</const>
10961	<const name="I82543GC" value="4">
10962	<desc>Intel PRO/1000 T Server network card (82543GC).</desc>
10963	</const>
10964	<const name="I82545EM" value="5">
10965	<desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
10966	</const>
10967	<const name="Virtio" value="6">
10968	<desc>Virtio network device.</desc>
10969	</const>
10970	</enum>
10971
10972	<interface
10973	name="INetworkAdapter" extends="$unknown"
10974	uuid="9bf58a46-c3f7-4f31-80fa-dde9a5dc0b7b"
10975	wsmap="managed"
10976	>
10977	<desc>
10978	Represents a virtual network adapter that is attached to a virtual machine.
10979	Each virtual machine has a fixed number of network adapter slots with one
10980	instance of this attached to each of them. Call
10981	<link to="IMachine::getNetworkAdapter" /> to get the network adapter that
10982	is attached to a given slot in a given machine.
10983
10984	Each network adapter can be in one of five attachment modes, which are
10985	represented by the <link to="NetworkAttachmentType" /> enumeration;
10986	see the <link to="#attachmentType" /> attribute.
10987	</desc>
10988
10989	<attribute name="adapterType" type="NetworkAdapterType">
10990	<desc>
10991	Type of the virtual network adapter. Depending on this value,
10992	VirtualBox will provide a different virtual network hardware
10993	to the guest.
10994	</desc>
10995	</attribute>
10996
10997	<attribute name="slot" type="unsigned long" readonly="yes">
10998	<desc>
10999	Slot number this adapter is plugged into. Corresponds to
11000	the value you pass to <link to="IMachine::getNetworkAdapter"/>
11001	to obtain this instance.
11002	</desc>
11003	</attribute>
11004
11005	<attribute name="enabled" type="boolean">
11006	<desc>
11007	Flag whether the network adapter is present in the
11008	guest system. If disabled, the virtual guest hardware will
11009	not contain this network adapter. Can only be changed when
11010	the VM is not running.
11011	</desc>
11012	</attribute>
11013
11014	<attribute name="MACAddress" type="wstring">
11015	<desc>
11016	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
11017	it to @c null or an empty string, VirtualBox will generate a unique MAC address.
11018	</desc>
11019	</attribute>
11020
11021	<attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
11022
11023	<attribute name="hostInterface" type="wstring">
11024	<desc>
11025	Name of the host network interface the VM is attached to.
11026	</desc>
11027	</attribute>
11028
11029	<attribute name="internalNetwork" type="wstring">
11030	<desc>
11031	Name of the internal network the VM is attached to.
11032	</desc>
11033	</attribute>
11034
11035	<attribute name="NATNetwork" type="wstring">
11036	<desc>
11037	Name of the NAT network the VM is attached to.
11038	</desc>
11039	</attribute>
11040
11041	<attribute name="VDENetwork" type="wstring">
11042	<desc>
11043	Name of the VDE switch the VM is attached to.
11044	</desc>
11045	</attribute>
11046
11047	<attribute name="cableConnected" type="boolean">
11048	<desc>
11049	Flag whether the adapter reports the cable as connected or not.
11050	It can be used to report offline situations to a VM.
11051	</desc>
11052	</attribute>
11053
11054	<attribute name="lineSpeed" type="unsigned long">
11055	<desc>
11056	Line speed reported by custom drivers, in units of 1 kbps.
11057	</desc>
11058	</attribute>
11059
11060	<attribute name="traceEnabled" type="boolean">
11061	<desc>
11062	Flag whether network traffic from/to the network card should be traced.
11063	Can only be toggled when the VM is turned off.
11064	</desc>
11065	</attribute>
11066
11067	<attribute name="traceFile" type="wstring">
11068	<desc>
11069	Filename where a network trace will be stored. If not set, VBox-pid.pcap
11070	will be used.
11071	</desc>
11072	</attribute>
11073
11074	<attribute name="natDriver" type="INATEngine" readonly="yes">
11075	<desc>
11076	Points to the NAT engine which handles the network address translation
11077	for this interface. This is active only when the interface actually uses
11078	NAT (see <link to="#attachToNAT" />).
11079	</desc>
11080	</attribute>
11081
11082	<attribute name="bootPriority" type="unsigned long">
11083	<desc>
11084	Network boot priority of the adapter. Priority 1 is highest. If not set,
11085	the priority is considered to be at the lowest possible setting.
11086	</desc>
11087	</attribute>
11088
11089	<attribute name="bandwidthLimit" type="unsigned long">
11090	<desc>
11091	Maximum throughput allowed for this network adapter, in units of 1 mbps.
11092	A zero value means uncapped/unlimited.
11093	</desc>
11094	</attribute>
11095
11096	<method name="attachToNAT">
11097	<desc>
11098	Attach the network adapter to the Network Address Translation (NAT) interface.
11099	</desc>
11100	</method>
11101
11102	<method name="attachToBridgedInterface">
11103	<desc>
11104	Attach the network adapter to a bridged host interface.
11105	</desc>
11106	</method>
11107
11108	<method name="attachToInternalNetwork">
11109	<desc>
11110	Attach the network adapter to an internal network.
11111	</desc>
11112	</method>
11113
11114	<method name="attachToHostOnlyInterface">
11115	<desc>
11116	Attach the network adapter to the host-only network.
11117	</desc>
11118	</method>
11119
11120	<method name="attachToVDE">
11121	<desc>
11122	Attach the network adapter to a VDE network.
11123	</desc>
11124	</method>
11125
11126	<method name="detach">
11127	<desc>
11128	Detach the network adapter
11129	</desc>
11130	</method>
11131	</interface>
11132
11133
11134	<!--
11135	// ISerialPort
11136	/////////////////////////////////////////////////////////////////////////
11137	-->
11138
11139	<enum
11140	name="PortMode"
11141	uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
11142	>
11143	<desc>
11144	The PortMode enumeration represents possible communication modes for
11145	the virtual serial port device.
11146	</desc>
11147
11148	<const name="Disconnected" value="0">
11149	<desc>Virtual device is not attached to any real host device.</desc>
11150	</const>
11151	<const name="HostPipe" value="1">
11152	<desc>Virtual device is attached to a host pipe.</desc>
11153	</const>
11154	<const name="HostDevice" value="2">
11155	<desc>Virtual device is attached to a host device.</desc>
11156	</const>
11157	<const name="RawFile" value="3">
11158	<desc>Virtual device is attached to a raw file.</desc>
11159	</const>
11160	</enum>
11161
11162	<interface
11163	name="ISerialPort" extends="$unknown"
11164	uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
11165	wsmap="managed"
11166	>
11167
11168	<desc>
11169	The ISerialPort interface represents the virtual serial port device.
11170
11171	The virtual serial port device acts like an ordinary serial port
11172	inside the virtual machine. This device communicates to the real
11173	serial port hardware in one of two modes: host pipe or host device.
11174
11175	In host pipe mode, the #path attribute specifies the path to the pipe on
11176	the host computer that represents a serial port. The #server attribute
11177	determines if this pipe is created by the virtual machine process at
11178	machine startup or it must already exist before starting machine
11179	execution.
11180
11181	In host device mode, the #path attribute specifies the name of the
11182	serial port device on the host computer.
11183
11184	There is also a third communication mode: the disconnected mode. In this
11185	mode, the guest OS running inside the virtual machine will be able to
11186	detect the serial port, but all port write operations will be discarded
11187	and all port read operations will return no data.
11188
11189	<see>IMachine::getSerialPort</see>
11190	</desc>
11191
11192	<attribute name="slot" type="unsigned long" readonly="yes">
11193	<desc>
11194	Slot number this serial port is plugged into. Corresponds to
11195	the value you pass to <link to="IMachine::getSerialPort"/>
11196	to obtain this instance.
11197	</desc>
11198	</attribute>
11199
11200	<attribute name="enabled" type="boolean">
11201	<desc>
11202	Flag whether the serial port is enabled. If disabled,
11203	the serial port will not be reported to the guest OS.
11204	</desc>
11205	</attribute>
11206
11207	<attribute name="IOBase" type="unsigned long">
11208	<desc>Base I/O address of the serial port.</desc>
11209	</attribute>
11210
11211	<attribute name="IRQ" type="unsigned long">
11212	<desc>IRQ number of the serial port.</desc>
11213	</attribute>
11214
11215	<attribute name="hostMode" type="PortMode">
11216	<desc>
11217	How is this port connected to the host.
11218	<note>
11219	Changing this attribute may fail if the conditions for
11220	<link to="#path"/> are not met.
11221	</note>
11222	</desc>
11223	</attribute>
11224
11225	<attribute name="server" type="boolean">
11226	<desc>
11227	Flag whether this serial port acts as a server (creates a new pipe on
11228	the host) or as a client (uses the existing pipe). This attribute is
11229	used only when <link to="#hostMode"/> is PortMode_HostPipe.
11230	</desc>
11231	</attribute>
11232
11233	<attribute name="path" type="wstring">
11234	<desc>
11235	Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
11236	PortMode_HostPipe, or the host serial device name when
11237	<link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
11238	cases, setting a @c null or empty string as the attribute's value
11239	is an error. Otherwise, the value of this property is ignored.
11240	</desc>
11241	</attribute>
11242
11243	</interface>
11244
11245	<!--
11246	// IParallelPort
11247	/////////////////////////////////////////////////////////////////////////
11248	-->
11249
11250	<interface
11251	name="IParallelPort" extends="$unknown"
11252	uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
11253	wsmap="managed"
11254	>
11255
11256	<desc>
11257	The IParallelPort interface represents the virtual parallel port device.
11258
11259	The virtual parallel port device acts like an ordinary parallel port
11260	inside the virtual machine. This device communicates to the real
11261	parallel port hardware using the name of the parallel device on the host
11262	computer specified in the #path attribute.
11263
11264	Each virtual parallel port device is assigned a base I/O address and an
11265	IRQ number that will be reported to the guest operating system and used
11266	to operate the given parallel port from within the virtual machine.
11267
11268	<see>IMachine::getParallelPort</see>
11269	</desc>
11270
11271	<attribute name="slot" type="unsigned long" readonly="yes">
11272	<desc>
11273	Slot number this parallel port is plugged into. Corresponds to
11274	the value you pass to <link to="IMachine::getParallelPort"/>
11275	to obtain this instance.
11276	</desc>
11277	</attribute>
11278
11279	<attribute name="enabled" type="boolean">
11280	<desc>
11281	Flag whether the parallel port is enabled. If disabled,
11282	the parallel port will not be reported to the guest OS.
11283	</desc>
11284	</attribute>
11285
11286	<attribute name="IOBase" type="unsigned long">
11287	<desc>Base I/O address of the parallel port.</desc>
11288	</attribute>
11289
11290	<attribute name="IRQ" type="unsigned long">
11291	<desc>IRQ number of the parallel port.</desc>
11292	</attribute>
11293
11294	<attribute name="path" type="wstring">
11295	<desc>
11296	Host parallel device name. If this parallel port is enabled, setting a
11297	@c null or an empty string as this attribute's value will result into
11298	an error.
11299	</desc>
11300	</attribute>
11301
11302	</interface>
11303
11304
11305	<!--
11306	// IMachineDebugger
11307	/////////////////////////////////////////////////////////////////////////
11308	-->
11309
11310	<interface
11311	name="IMachineDebugger" extends="$unknown"
11312	uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
11313	wsmap="suppress"
11314	>
11315	<method name="resetStats">
11316	<desc>
11317	Reset VM statistics.
11318	</desc>
11319	<param name="pattern" type="wstring" dir="in">
11320	<desc>The selection pattern. A bit similar to filename globbing.</desc>
11321	</param>
11322	</method>
11323
11324	<method name="dumpStats">
11325	<desc>
11326	Dumps VM statistics.
11327	</desc>
11328	<param name="pattern" type="wstring" dir="in">
11329	<desc>The selection pattern. A bit similar to filename globbing.</desc>
11330	</param>
11331	</method>
11332
11333	<method name="getStats">
11334	<desc>
11335	Get the VM statistics in a XMLish format.
11336	</desc>
11337	<param name="pattern" type="wstring" dir="in">
11338	<desc>The selection pattern. A bit similar to filename globbing.</desc>
11339	</param>
11340	<param name="withDescriptions" type="boolean" dir="in">
11341	<desc>Whether to include the descriptions.</desc>
11342	</param>
11343	<param name="stats" type="wstring" dir="out">
11344	<desc>The XML document containing the statistics.</desc>
11345	</param>
11346	</method>
11347
11348	<method name="injectNMI">
11349	<desc>
11350	Inject an NMI into a running VT-x/AMD-V VM.
11351	</desc>
11352	</method>
11353
11354	<attribute name="singlestep" type="boolean">
11355	<desc>Switch for enabling singlestepping.</desc>
11356	</attribute>
11357
11358	<attribute name="recompileUser" type="boolean">
11359	<desc>Switch for forcing code recompilation for user mode code.</desc>
11360	</attribute>
11361
11362	<attribute name="recompileSupervisor" type="boolean">
11363	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
11364	</attribute>
11365
11366	<attribute name="PATMEnabled" type="boolean">
11367	<desc>Switch for enabling and disabling the PATM component.</desc>
11368	</attribute>
11369
11370	<attribute name="CSAMEnabled" type="boolean">
11371	<desc>Switch for enabling and disabling the CSAM component.</desc>
11372	</attribute>
11373
11374	<attribute name="logEnabled" type="boolean">
11375	<desc>Switch for enabling and disabling logging.</desc>
11376	</attribute>
11377
11378	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
11379	<desc>
11380	Flag indicating whether the VM is currently making use of CPU hardware
11381	virtualization extensions.
11382	</desc>
11383	</attribute>
11384
11385	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
11386	<desc>
11387	Flag indicating whether the VM is currently making use of the nested paging
11388	CPU hardware virtualization extension.
11389	</desc>
11390	</attribute>
11391
11392	<attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
11393	<desc>
11394	Flag indicating whether the VM is currently making use of the VPID
11395	VT-x extension.
11396	</desc>
11397	</attribute>
11398
11399	<attribute name="PAEEnabled" type="boolean" readonly="yes">
11400	<desc>
11401	Flag indicating whether the VM is currently making use of the Physical
11402	Address Extension CPU feature.
11403	</desc>
11404	</attribute>
11405
11406	<attribute name="virtualTimeRate" type="unsigned long">
11407	<desc>
11408	The rate at which the virtual time runs expressed as a percentage.
11409	The accepted range is 2% to 20000%.
11410	</desc>
11411	</attribute>
11412
11413	<!-- @todo method for setting log flags, groups and destination! -->
11414
11415	<attribute name="VM" type="unsigned long long" readonly="yes">
11416	<desc>
11417	Gets the VM handle. This is only for internal use while
11418	we carve the details of this interface.
11419	</desc>
11420	</attribute>
11421
11422	</interface>
11423
11424	<!--
11425	// IUSBController
11426	/////////////////////////////////////////////////////////////////////////
11427	-->
11428
11429	<interface
11430	name="IUSBController" extends="$unknown"
11431	uuid="6fdcccc5-abd3-4fec-9387-2ad3914fc4a8"
11432	wsmap="managed"
11433	>
11434	<attribute name="enabled" type="boolean">
11435	<desc>
11436	Flag whether the USB controller is present in the
11437	guest system. If disabled, the virtual guest hardware will
11438	not contain any USB controller. Can only be changed when
11439	the VM is powered off.
11440	</desc>
11441	</attribute>
11442
11443	<attribute name="enabledEhci" type="boolean">
11444	<desc>
11445	Flag whether the USB EHCI controller is present in the
11446	guest system. If disabled, the virtual guest hardware will
11447	not contain a USB EHCI controller. Can only be changed when
11448	the VM is powered off.
11449	</desc>
11450	</attribute>
11451
11452	<attribute name="proxyAvailable" type="boolean" readonly="yes">
11453	<desc>
11454	Flag whether there is an USB proxy available.
11455	</desc>
11456	</attribute>
11457
11458	<attribute name="USBStandard" type="unsigned short" readonly="yes">
11459	<desc>
11460	USB standard version which the controller implements.
11461	This is a BCD which means that the major version is in the
11462	high byte and minor version is in the low byte.
11463	</desc>
11464	</attribute>
11465
11466	<attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
11467	<desc>
11468	List of USB device filters associated with the machine.
11469
11470	If the machine is currently running, these filters are activated
11471	every time a new (supported) USB device is attached to the host
11472	computer that was not ignored by global filters
11473	(<link to="IHost::USBDeviceFilters"/>).
11474
11475	These filters are also activated when the machine is powered up.
11476	They are run against a list of all currently available USB
11477	devices (in states
11478	<link to="USBDeviceState_Available"/>,
11479	<link to="USBDeviceState_Busy"/>,
11480	<link to="USBDeviceState_Held"/>) that were not previously
11481	ignored by global filters.
11482
11483	If at least one filter matches the USB device in question, this
11484	device is automatically captured (attached to) the virtual USB
11485	controller of this machine.
11486
11487	<see>IUSBDeviceFilter, ::IUSBController</see>
11488	</desc>
11489	</attribute>
11490
11491	<method name="createDeviceFilter">
11492	<desc>
11493	Creates a new USB device filter. All attributes except
11494	the filter name are set to empty (any match),
11495	<i>active</i> is @c false (the filter is not active).
11496
11497	The created filter can then be added to the list of filters using
11498	<link to="#insertDeviceFilter"/>.
11499
11500	<result name="VBOX_E_INVALID_VM_STATE">
11501	The virtual machine is not mutable.
11502	</result>
11503
11504	<see>#deviceFilters</see>
11505	</desc>
11506	<param name="name" type="wstring" dir="in">
11507	<desc>
11508	Filter name. See <link to="IUSBDeviceFilter::name"/>
11509	for more info.
11510	</desc>
11511	</param>
11512	<param name="filter" type="IUSBDeviceFilter" dir="return">
11513	<desc>Created filter object.</desc>
11514	</param>
11515	</method>
11516
11517	<method name="insertDeviceFilter">
11518	<desc>
11519	Inserts the given USB device to the specified position
11520	in the list of filters.
11521
11522	Positions are numbered starting from <tt>0</tt>. If the specified
11523	position is equal to or greater than the number of elements in
11524	the list, the filter is added to the end of the collection.
11525
11526	<note>
11527	Duplicates are not allowed, so an attempt to insert a
11528	filter that is already in the collection, will return an
11529	error.
11530	</note>
11531
11532	<result name="VBOX_E_INVALID_VM_STATE">
11533	Virtual machine is not mutable.
11534	</result>
11535	<result name="E_INVALIDARG">
11536	USB device filter not created within this VirtualBox instance.
11537	</result>
11538	<result name="VBOX_E_INVALID_OBJECT_STATE">
11539	USB device filter already in list.
11540	</result>
11541
11542	<see>#deviceFilters</see>
11543	</desc>
11544	<param name="position" type="unsigned long" dir="in">
11545	<desc>Position to insert the filter to.</desc>
11546	</param>
11547	<param name="filter" type="IUSBDeviceFilter" dir="in">
11548	<desc>USB device filter to insert.</desc>
11549	</param>
11550	</method>
11551
11552	<method name="removeDeviceFilter">
11553	<desc>
11554	Removes a USB device filter from the specified position in the
11555	list of filters.
11556
11557	Positions are numbered starting from <tt>0</tt>. Specifying a
11558	position equal to or greater than the number of elements in
11559	the list will produce an error.
11560
11561	<see>#deviceFilters</see>
11562
11563	<result name="VBOX_E_INVALID_VM_STATE">
11564	Virtual machine is not mutable.
11565	</result>
11566	<result name="E_INVALIDARG">
11567	USB device filter list empty or invalid @a position.
11568	</result>
11569
11570	</desc>
11571	<param name="position" type="unsigned long" dir="in">
11572	<desc>Position to remove the filter from.</desc>
11573	</param>
11574	<param name="filter" type="IUSBDeviceFilter" dir="return">
11575	<desc>Removed USB device filter.</desc>
11576	</param>
11577	</method>
11578
11579	</interface>
11580
11581
11582	<!--
11583	// IUSBDevice
11584	/////////////////////////////////////////////////////////////////////////
11585	-->
11586
11587	<interface
11588	name="IUSBDevice" extends="$unknown"
11589	uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
11590	wsmap="managed"
11591	>
11592	<desc>
11593	The IUSBDevice interface represents a virtual USB device attached to the
11594	virtual machine.
11595
11596	A collection of objects implementing this interface is stored in the
11597	<link to="IConsole::USBDevices"/> attribute which lists all USB devices
11598	attached to a running virtual machine's USB controller.
11599	</desc>
11600
11601	<attribute name="id" type="uuid" mod="string" readonly="yes">
11602	<desc>
11603	Unique USB device ID. This ID is built from #vendorId,
11604	#productId, #revision and #serialNumber.
11605	</desc>
11606	</attribute>
11607
11608	<attribute name="vendorId" type="unsigned short" readonly="yes">
11609	<desc>Vendor ID.</desc>
11610	</attribute>
11611
11612	<attribute name="productId" type="unsigned short" readonly="yes">
11613	<desc>Product ID.</desc>
11614	</attribute>
11615
11616	<attribute name="revision" type="unsigned short" readonly="yes">
11617	<desc>
11618	Product revision number. This is a packed BCD represented as
11619	unsigned short. The high byte is the integer part and the low
11620	byte is the decimal.
11621	</desc>
11622	</attribute>
11623
11624	<attribute name="manufacturer" type="wstring" readonly="yes">
11625	<desc>Manufacturer string.</desc>
11626	</attribute>
11627
11628	<attribute name="product" type="wstring" readonly="yes">
11629	<desc>Product string.</desc>
11630	</attribute>
11631
11632	<attribute name="serialNumber" type="wstring" readonly="yes">
11633	<desc>Serial number string.</desc>
11634	</attribute>
11635
11636	<attribute name="address" type="wstring" readonly="yes">
11637	<desc>Host specific address of the device.</desc>
11638	</attribute>
11639
11640	<attribute name="port" type="unsigned short" readonly="yes">
11641	<desc>
11642	Host USB port number the device is physically
11643	connected to.
11644	</desc>
11645	</attribute>
11646
11647	<attribute name="version" type="unsigned short" readonly="yes">
11648	<desc>
11649	The major USB version of the device - 1 or 2.
11650	</desc>
11651	</attribute>
11652
11653	<attribute name="portVersion" type="unsigned short" readonly="yes">
11654	<desc>
11655	The major USB version of the host USB port the device is
11656	physically connected to - 1 or 2. For devices not connected to
11657	anything this will have the same value as the version attribute.
11658	</desc>
11659	</attribute>
11660
11661	<attribute name="remote" type="boolean" readonly="yes">
11662	<desc>
11663	Whether the device is physically connected to a remote VRDP
11664	client or to a local host machine.
11665	</desc>
11666	</attribute>
11667
11668	</interface>
11669
11670
11671	<!--
11672	// IUSBDeviceFilter
11673	/////////////////////////////////////////////////////////////////////////
11674	-->
11675
11676	<interface
11677	name="IUSBDeviceFilter" extends="$unknown"
11678	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
11679	wsmap="managed"
11680	>
11681	<desc>
11682	The IUSBDeviceFilter interface represents an USB device filter used
11683	to perform actions on a group of USB devices.
11684
11685	This type of filters is used by running virtual machines to
11686	automatically capture selected USB devices once they are physically
11687	attached to the host computer.
11688
11689	A USB device is matched to the given device filter if and only if all
11690	attributes of the device match the corresponding attributes of the
11691	filter (that is, attributes are joined together using the logical AND
11692	operation). On the other hand, all together, filters in the list of
11693	filters carry the semantics of the logical OR operation. So if it is
11694	desirable to create a match like "this vendor id OR this product id",
11695	one needs to create two filters and specify "any match" (see below)
11696	for unused attributes.
11697
11698	All filter attributes used for matching are strings. Each string
11699	is an expression representing a set of values of the corresponding
11700	device attribute, that will match the given filter. Currently, the
11701	following filtering expressions are supported:
11702
11703	<ul>
11704	<li><i>Interval filters</i>. Used to specify valid intervals for
11705	integer device attributes (Vendor ID, Product ID and Revision).
11706	The format of the string is:
11707
11708	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
11709
11710	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
11711	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
11712	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
11713	is omitted before a dash (<tt>-</tt>), the minimum possible integer
11714	is assumed; if <tt>n</tt> is omitted after a dash, the maximum
11715	possible integer is assumed.
11716	</li>
11717	<li><i>Boolean filters</i>. Used to specify acceptable values for
11718	boolean device attributes. The format of the string is:
11719
11720	<tt>true\|false\|yes\|no\|0\|1</tt>
11721
11722	</li>
11723	<li><i>Exact match</i>. Used to specify a single value for the given
11724	device attribute. Any string that doesn't start with <tt>int:</tt>
11725	represents the exact match. String device attributes are compared to
11726	this string including case of symbols. Integer attributes are first
11727	converted to a string (see individual filter attributes) and then
11728	compared ignoring case.
11729
11730	</li>
11731	<li><i>Any match</i>. Any value of the corresponding device attribute
11732	will match the given filter. An empty or @c null string is
11733	used to construct this type of filtering expressions.
11734
11735	</li>
11736	</ul>
11737
11738	<note>
11739	On the Windows host platform, interval filters are not currently
11740	available. Also all string filter attributes
11741	(<link to="#manufacturer"/>, <link to="#product"/>,
11742	<link to="#serialNumber"/>) are ignored, so they behave as
11743	<i>any match</i> no matter what string expression is specified.
11744	</note>
11745
11746	<see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
11747	</desc>
11748
11749	<attribute name="name" type="wstring">
11750	<desc>
11751	Visible name for this filter.
11752	This name is used to visually distinguish one filter from another,
11753	so it can neither be @c null nor an empty string.
11754	</desc>
11755	</attribute>
11756
11757	<attribute name="active" type="boolean">
11758	<desc>Whether this filter active or has been temporarily disabled.</desc>
11759	</attribute>
11760
11761	<attribute name="vendorId" type="wstring">
11762	<desc>
11763	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
11764	The string representation for the <i>exact matching</i>
11765	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
11766	(including leading zeroes).
11767	</desc>
11768	</attribute>
11769
11770	<attribute name="productId" type="wstring">
11771	<desc>
11772	<link to="IUSBDevice::productId">Product ID</link> filter.
11773	The string representation for the <i>exact matching</i>
11774	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
11775	(including leading zeroes).
11776	</desc>
11777	</attribute>
11778
11779	<attribute name="revision" type="wstring">
11780	<desc>
11781	<link to="IUSBDevice::productId">Product revision number</link>
11782	filter. The string representation for the <i>exact matching</i>
11783	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
11784	of the integer part of the revision, and <tt>F</tt> is the
11785	decimal digit of its fractional part (including leading and
11786	trailing zeros).
11787	Note that for interval filters, it's best to use the hexadecimal
11788	form, because the revision is stored as a 16 bit packed BCD value;
11789	so the expression <tt>int:0x0100-0x0199</tt> will match any
11790	revision from <tt>1.0</tt> to <tt>1.99</tt>.
11791	</desc>
11792	</attribute>
11793
11794	<attribute name="manufacturer" type="wstring">
11795	<desc>
11796	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
11797	</desc>
11798	</attribute>
11799
11800	<attribute name="product" type="wstring">
11801	<desc>
11802	<link to="IUSBDevice::product">Product</link> filter.
11803	</desc>
11804	</attribute>
11805
11806	<attribute name="serialNumber" type="wstring">
11807	<desc>
11808	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
11809	</desc>
11810	</attribute>
11811
11812	<attribute name="port" type="wstring">
11813	<desc>
11814	<link to="IUSBDevice::port">Host USB port</link> filter.
11815	</desc>
11816	</attribute>
11817
11818	<attribute name="remote" type="wstring">
11819	<desc>
11820	<link to="IUSBDevice::remote">Remote state</link> filter.
11821	<note>
11822	This filter makes sense only for machine USB filters,
11823	i.e. it is ignored by IHostUSBDeviceFilter objects.
11824	</note>
11825	</desc>
11826	</attribute>
11827
11828	<attribute name="maskedInterfaces" type="unsigned long">
11829	<desc>
11830	This is an advanced option for hiding one or more USB interfaces
11831	from the guest. The value is a bit mask where the bits that are set
11832	means the corresponding USB interface should be hidden, masked off
11833	if you like.
11834	This feature only works on Linux hosts.
11835	</desc>
11836	</attribute>
11837
11838	</interface>
11839
11840
11841	<!--
11842	// IHostUSBDevice
11843	/////////////////////////////////////////////////////////////////////////
11844	-->
11845
11846	<enum
11847	name="USBDeviceState"
11848	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
11849	>
11850	<desc>
11851	USB device state. This enumeration represents all possible states
11852	of the USB device physically attached to the host computer regarding
11853	its state on the host computer and availability to guest computers
11854	(all currently running virtual machines).
11855
11856	Once a supported USB device is attached to the host, global USB
11857	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
11858	either ignore the device, or put it to USBDeviceState_Held state, or do
11859	nothing. Unless the device is ignored by global filters, filters of all
11860	currently running guests (<link to="IUSBController::deviceFilters"/>) are
11861	activated that can put it to USBDeviceState_Captured state.
11862
11863	If the device was ignored by global filters, or didn't match
11864	any filters at all (including guest ones), it is handled by the host
11865	in a normal way. In this case, the device state is determined by
11866	the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
11867	or USBDeviceState_Available, depending on the current device usage.
11868
11869	Besides auto-capturing based on filters, the device can be manually
11870	captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
11871	state is USBDeviceState_Busy, USBDeviceState_Available or
11872	USBDeviceState_Held.
11873
11874	<note>
11875	Due to differences in USB stack implementations in Linux and Win32,
11876	states USBDeviceState_Busy and USBDeviceState_vailable are applicable
11877	only to the Linux version of the product. This also means that (<link
11878	to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
11879	device state is USBDeviceState_Held.
11880	</note>
11881
11882	<see>IHostUSBDevice, IHostUSBDeviceFilter</see>
11883	</desc>
11884
11885	<const name="NotSupported" value="0">
11886	<desc>
11887	Not supported by the VirtualBox server, not available to guests.
11888	</desc>
11889	</const>
11890	<const name="Unavailable" value="1">
11891	<desc>
11892	Being used by the host computer exclusively,
11893	not available to guests.
11894	</desc>
11895	</const>
11896	<const name="Busy" value="2">
11897	<desc>
11898	Being used by the host computer, potentially available to guests.
11899	</desc>
11900	</const>
11901	<const name="Available" value="3">
11902	<desc>
11903	Not used by the host computer, available to guests (the host computer
11904	can also start using the device at any time).
11905	</desc>
11906	</const>
11907	<const name="Held" value="4">
11908	<desc>
11909	Held by the VirtualBox server (ignored by the host computer),
11910	available to guests.
11911	</desc>
11912	</const>
11913	<const name="Captured" value="5">
11914	<desc>
11915	Captured by one of the guest computers, not available
11916	to anybody else.
11917	</desc>
11918	</const>
11919	</enum>
11920
11921	<interface
11922	name="IHostUSBDevice" extends="IUSBDevice"
11923	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
11924	wsmap="managed"
11925	>
11926	<desc>
11927	The IHostUSBDevice interface represents a physical USB device attached
11928	to the host computer.
11929
11930	Besides properties inherited from IUSBDevice, this interface adds the
11931	<link to="#state"/> property that holds the current state of the USB
11932	device.
11933
11934	<see>IHost::USBDevices, IHost::USBDeviceFilters</see>
11935	</desc>
11936
11937	<attribute name="state" type="USBDeviceState" readonly="yes">
11938	<desc>
11939	Current state of the device.
11940	</desc>
11941	</attribute>
11942
11943	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
11944
11945	</interface>
11946
11947
11948	<!--
11949	// IHostUSBDeviceFilter
11950	/////////////////////////////////////////////////////////////////////////
11951	-->
11952
11953	<enum
11954	name="USBDeviceFilterAction"
11955	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
11956	>
11957	<desc>
11958	Actions for host USB device filters.
11959	<see>IHostUSBDeviceFilter, USBDeviceState</see>
11960	</desc>
11961
11962	<const name="Null" value="0">
11963	<desc>Null value (never used by the API).</desc>
11964	</const>
11965	<const name="Ignore" value="1">
11966	<desc>Ignore the matched USB device.</desc>
11967	</const>
11968	<const name="Hold" value="2">
11969	<desc>Hold the matched USB device.</desc>
11970	</const>
11971	</enum>
11972
11973	<interface
11974	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
11975	uuid="4cc70246-d74a-400f-8222-3900489c0374"
11976	wsmap="managed"
11977	>
11978	<desc>
11979	The IHostUSBDeviceFilter interface represents a global filter for a
11980	physical USB device used by the host computer. Used indirectly in
11981	<link to="IHost::USBDeviceFilters"/>.
11982
11983	Using filters of this type, the host computer determines the initial
11984	state of the USB device after it is physically attached to the
11985	host's USB controller.
11986
11987	<note>
11988	The <link to="IUSBDeviceFilter::remote"/> attribute is ignored by this type of
11989	filters, because it makes sense only for
11990	<link to="IUSBController::deviceFilters">machine USB filters</link>.
11991	</note>
11992
11993	<see>IHost::USBDeviceFilters</see>
11994	</desc>
11995
11996	<attribute name="action" type="USBDeviceFilterAction">
11997	<desc>
11998	Action performed by the host when an attached USB device
11999	matches this filter.
12000	</desc>
12001	</attribute>
12002
12003	</interface>
12004
12005	<!--
12006	// IAudioAdapter
12007	/////////////////////////////////////////////////////////////////////////
12008	-->
12009
12010	<enum
12011	name="AudioDriverType"
12012	uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
12013	>
12014	<desc>
12015	Host audio driver type.
12016	</desc>
12017
12018	<const name="Null" value="0">
12019	<desc>Null value, also means "dummy audio driver".</desc>
12020	</const>
12021	<const name="WinMM" value="1">
12022	<desc>Windows multimedia (Windows hosts only).</desc>
12023	</const>
12024	<const name="OSS" value="2">
12025	<desc>Open Sound System (Linux hosts only).</desc>
12026	</const>
12027	<const name="ALSA" value="3">
12028	<desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
12029	</const>
12030	<const name="DirectSound" value="4">
12031	<desc>DirectSound (Windows hosts only).</desc>
12032	</const>
12033	<const name="CoreAudio" value="5">
12034	<desc>CoreAudio (Mac hosts only).</desc>
12035	</const>
12036	<const name="MMPM" value="6">
12037	<desc>Reserved for historical reasons.</desc>
12038	</const>
12039	<const name="Pulse" value="7">
12040	<desc>PulseAudio (Linux hosts only).</desc>
12041	</const>
12042	<const name="SolAudio" value="8">
12043	<desc>Solaris audio (Solaris hosts only).</desc>
12044	</const>
12045	</enum>
12046
12047	<enum
12048	name="AudioControllerType"
12049	uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
12050	>
12051	<desc>
12052	Virtual audio controller type.
12053	</desc>
12054
12055	<const name="AC97" value="0"/>
12056	<const name="SB16" value="1"/>
12057	<const name="HDA" value="2"/>
12058	</enum>
12059
12060	<interface
12061	name="IAudioAdapter" extends="$unknown"
12062	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
12063	wsmap="managed"
12064	>
12065	<desc>
12066	The IAudioAdapter interface represents the virtual audio adapter of
12067	the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
12068	</desc>
12069	<attribute name="enabled" type="boolean">
12070	<desc>
12071	Flag whether the audio adapter is present in the
12072	guest system. If disabled, the virtual guest hardware will
12073	not contain any audio adapter. Can only be changed when
12074	the VM is not running.
12075	</desc>
12076	</attribute>
12077	<attribute name="audioController" type="AudioControllerType">
12078	<desc>
12079	The audio hardware we emulate.
12080	</desc>
12081	</attribute>
12082	<attribute name="audioDriver" type="AudioDriverType">
12083	<desc>
12084	Audio driver the adapter is connected to. This setting
12085	can only be changed when the VM is not running.
12086	</desc>
12087	</attribute>
12088	</interface>
12089
12090	<!--
12091	// IVRDPServer
12092	/////////////////////////////////////////////////////////////////////////
12093	-->
12094
12095	<enum
12096	name="VRDPAuthType"
12097	uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
12098	>
12099	<desc>
12100	VRDP authentication type.
12101	</desc>
12102
12103	<const name="Null" value="0">
12104	<desc>Null value, also means "no authentication".</desc>
12105	</const>
12106	<const name="External" value="1"/>
12107	<const name="Guest" value="2"/>
12108	</enum>
12109
12110	<interface
12111	name="IVRDPServer" extends="$unknown"
12112	uuid="7aeeb530-0b08-41fe-835d-9be9ec1dbe5c"
12113	wsmap="managed"
12114	>
12115	<attribute name="enabled" type="boolean">
12116	<desc>VRDP server status.</desc>
12117	</attribute>
12118
12119	<attribute name="ports" type="wstring">
12120	<desc>
12121	VRDP server port numbers. The server will try to bind to one of free ports from the list.
12122	<note>
12123	This is a string of comma separated TCP port numbers or port number ranges.
12124	Example <tt>5000,5010-5012,5015</tt>
12125	</note>
12126	</desc>
12127	</attribute>
12128
12129	<attribute name="netAddress" type="wstring">
12130	<desc>VRDP server address.</desc>
12131	</attribute>
12132
12133	<attribute name="authType" type="VRDPAuthType">
12134	<desc>VRDP authentication method.</desc>
12135	</attribute>
12136
12137	<attribute name="authTimeout" type="unsigned long">
12138	<desc>Timeout for guest authentication. Milliseconds.</desc>
12139	</attribute>
12140
12141	<attribute name="allowMultiConnection" type="boolean">
12142	<desc>
12143	Flag whether multiple simultaneous connections to the VM are permitted.
12144	Note that this will be replaced by a more powerful mechanism in the future.
12145	</desc>
12146	</attribute>
12147
12148	<attribute name="reuseSingleConnection" type="boolean">
12149	<desc>
12150	Flag whether the existing connection must be dropped and a new connection
12151	must be established by the VRDP server, when a new client connects in single
12152	connection mode.
12153	</desc>
12154	</attribute>
12155
12156	<attribute name="videoChannel" type="boolean">
12157	<desc>
12158	Flag whether RDP video channel is supported.
12159	</desc>
12160	</attribute>
12161
12162	<attribute name="videoChannelQuality" type="unsigned long">
12163	<desc>
12164	Image quality in percents.
12165	</desc>
12166	</attribute>
12167
12168	</interface>
12169
12170
12171	<!--
12172	// ISharedFolder
12173	/////////////////////////////////////////////////////////////////////////
12174	-->
12175
12176	<interface
12177	name="ISharedFolder" extends="$unknown"
12178	uuid="8388da11-b559-4574-a5b7-2bd7acd5cef8"
12179	wsmap="struct"
12180	>
12181	<desc>
12182	The ISharedFolder interface represents a folder in the host computer's
12183	file system accessible from the guest OS running inside a virtual
12184	machine using an associated logical name.
12185
12186	There are three types of shared folders:
12187	<ul>
12188	<li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
12189	folders available to all virtual machines.</li>
12190	<li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
12191	VM-specific shared folders available to the given virtual machine at
12192	startup.</li>
12193	<li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
12194	VM-specific shared folders created in the session context (for
12195	example, when the virtual machine is running) and automatically
12196	discarded when the session is closed (the VM is powered off).</li>
12197	</ul>
12198
12199	Logical names of shared folders must be unique within the given scope
12200	(global, permanent or transient). However, they do not need to be unique
12201	across scopes. In this case, the definition of the shared folder in a
12202	more specific scope takes precedence over definitions in all other
12203	scopes. The order of precedence is (more specific to more general):
12204	<ol>
12205	<li>Transient definitions</li>
12206	<li>Permanent definitions</li>
12207	<li>Global definitions</li>
12208	</ol>
12209
12210	For example, if MyMachine has a shared folder named
12211	<tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
12212	transient shared folder named <tt>C_DRIVE</tt> (that points
12213	to <tt>C:\\\\WINDOWS</tt>) will change the definition
12214	of <tt>C_DRIVE</tt> in the guest OS so
12215	that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
12216	to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
12217	PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
12218	the previous (permanent) definition of <tt>C_DRIVE</tt> that points
12219	to <tt>C:\\</tt> if it still exists.
12220
12221	Note that permanent and transient shared folders of different machines
12222	are in different name spaces, so they don't overlap and don't need to
12223	have unique logical names.
12224
12225	<note>
12226	Global shared folders are not implemented in the current version of the
12227	product.
12228	</note>
12229	</desc>
12230
12231	<attribute name="name" type="wstring" readonly="yes">
12232	<desc>Logical name of the shared folder.</desc>
12233	</attribute>
12234
12235	<attribute name="hostPath" type="wstring" readonly="yes">
12236	<desc>Full path to the shared folder in the host file system.</desc>
12237	</attribute>
12238
12239	<attribute name="accessible" type="boolean" readonly="yes">
12240	<desc>
12241	Whether the folder defined by the host path is currently
12242	accessible or not.
12243	For example, the folder can be unaccessible if it is placed
12244	on the network share that is not available by the time
12245	this property is read.
12246	</desc>
12247	</attribute>
12248
12249	<attribute name="writable" type="boolean" readonly="yes">
12250	<desc>
12251	Whether the folder defined by the host path is writable or
12252	not.
12253	</desc>
12254	</attribute>
12255
12256	<attribute name="autoMount" type="boolean" readonly="yes">
12257	<desc>
12258	Whether the folder gets automatically mounted by the guest or not.
12259	</desc>
12260	</attribute>
12261
12262	<attribute name="lastAccessError" type="wstring" readonly="yes">
12263	<desc>
12264	Text message that represents the result of the last accessibility
12265	check.
12266
12267	Accessibility checks are performed each time the <link to="#accessible"/>
12268	attribute is read. An empty string is returned if the last
12269	accessibility check was successful. A non-empty string indicates a
12270	failure and should normally describe a reason of the failure (for
12271	example, a file read error).
12272	</desc>
12273	</attribute>
12274
12275	</interface>
12276
12277	<!--
12278	// ISession
12279	/////////////////////////////////////////////////////////////////////////
12280	-->
12281
12282	<interface
12283	name="IInternalSessionControl" extends="$unknown"
12284	uuid="ef059f1d-2273-4f81-9342-c152a0d2cd40"
12285	internal="yes"
12286	wsmap="suppress"
12287	>
12288	<method name="getPID">
12289	<desc>PID of the process that has created this Session object.
12290	</desc>
12291	<param name="pid" type="unsigned long" dir="return"/>
12292	</method>
12293
12294	<method name="getRemoteConsole">
12295	<desc>
12296	Returns the console object suitable for remote control.
12297
12298	<result name="VBOX_E_INVALID_VM_STATE">
12299	Session state prevents operation.
12300	</result>
12301	<result name="VBOX_E_INVALID_OBJECT_STATE">
12302	Session type prevents operation.
12303	</result>
12304
12305	</desc>
12306	<param name="console" type="IConsole" dir="return"/>
12307	</method>
12308
12309	<method name="assignMachine">
12310	<desc>
12311	Assigns the machine object associated with this direct-type
12312	session or informs the session that it will be a remote one
12313	(if @a machine == @c null).
12314
12315	<result name="VBOX_E_INVALID_VM_STATE">
12316	Session state prevents operation.
12317	</result>
12318	<result name="VBOX_E_INVALID_OBJECT_STATE">
12319	Session type prevents operation.
12320	</result>
12321
12322	</desc>
12323	<param name="machine" type="IMachine" dir="in"/>
12324	</method>
12325
12326	<method name="assignRemoteMachine">
12327	<desc>
12328	Assigns the machine and the (remote) console object associated with
12329	this remote-type session.
12330
12331	<result name="VBOX_E_INVALID_VM_STATE">
12332	Session state prevents operation.
12333	</result>
12334
12335	</desc>
12336	<param name="machine" type="IMachine" dir="in"/>
12337	<param name="console" type="IConsole" dir="in"/>
12338	</method>
12339
12340	<method name="updateMachineState">
12341	<desc>
12342	Updates the machine state in the VM process.
12343	Must be called only in certain cases
12344	(see the method implementation).
12345
12346	<result name="VBOX_E_INVALID_VM_STATE">
12347	Session state prevents operation.
12348	</result>
12349	<result name="VBOX_E_INVALID_OBJECT_STATE">
12350	Session type prevents operation.
12351	</result>
12352
12353	</desc>
12354	<param name="aMachineState" type="MachineState" dir="in"/>
12355	</method>
12356
12357	<method name="uninitialize">
12358	<desc>
12359	Uninitializes (closes) this session. Used by VirtualBox to close
12360	the corresponding remote session when the direct session dies
12361	or gets closed.
12362
12363	<result name="VBOX_E_INVALID_VM_STATE">
12364	Session state prevents operation.
12365	</result>
12366
12367	</desc>
12368	</method>
12369
12370	<method name="onNetworkAdapterChange">
12371	<desc>
12372	Triggered when settings of a network adapter of the
12373	associated virtual machine have changed.
12374
12375	<result name="VBOX_E_INVALID_VM_STATE">
12376	Session state prevents operation.
12377	</result>
12378	<result name="VBOX_E_INVALID_OBJECT_STATE">
12379	Session type prevents operation.
12380	</result>
12381
12382	</desc>
12383	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
12384	<param name="changeAdapter" type="boolean" dir="in"/>
12385	</method>
12386
12387	<method name="onSerialPortChange">
12388	<desc>
12389	Triggered when settings of a serial port of the
12390	associated virtual machine have changed.
12391
12392	<result name="VBOX_E_INVALID_VM_STATE">
12393	Session state prevents operation.
12394	</result>
12395	<result name="VBOX_E_INVALID_OBJECT_STATE">
12396	Session type prevents operation.
12397	</result>
12398
12399	</desc>
12400	<param name="serialPort" type="ISerialPort" dir="in"/>
12401	</method>
12402
12403	<method name="onParallelPortChange">
12404	<desc>
12405	Triggered when settings of a parallel port of the
12406	associated virtual machine have changed.
12407
12408	<result name="VBOX_E_INVALID_VM_STATE">
12409	Session state prevents operation.
12410	</result>
12411	<result name="VBOX_E_INVALID_OBJECT_STATE">
12412	Session type prevents operation.
12413	</result>
12414
12415	</desc>
12416	<param name="parallelPort" type="IParallelPort" dir="in"/>
12417	</method>
12418
12419	<method name="onStorageControllerChange">
12420	<desc>
12421	Triggered when settings of a storage controller of the
12422	associated virtual machine have changed.
12423
12424	<result name="VBOX_E_INVALID_VM_STATE">
12425	Session state prevents operation.
12426	</result>
12427	<result name="VBOX_E_INVALID_OBJECT_STATE">
12428	Session type prevents operation.
12429	</result>
12430
12431	</desc>
12432	</method>
12433
12434	<method name="onMediumChange">
12435	<desc>
12436	Triggered when attached media of the
12437	associated virtual machine have changed.
12438
12439	<result name="VBOX_E_INVALID_VM_STATE">
12440	Session state prevents operation.
12441	</result>
12442	<result name="VBOX_E_INVALID_OBJECT_STATE">
12443	Session type prevents operation.
12444	</result>
12445
12446	</desc>
12447
12448	<param name="mediumAttachment" type="IMediumAttachment" dir="in"/>
12449	<param name="force" type="boolean" dir="in"/>
12450	</method>
12451
12452	<method name="onCPUChange">
12453	<desc>
12454	Notification when a CPU changes.
12455	</desc>
12456	<param name="cpu" type="unsigned long" dir="in">
12457	<desc>The CPU which changed</desc>
12458	</param>
12459	<param name="add" type="boolean" dir="in">
12460	<desc>Flag whether the CPU was added or removed</desc>
12461	</param>
12462	</method>
12463
12464	<method name="onCPUPriorityChange">
12465	<desc>
12466	Notification when the CPU priority changes.
12467	</desc>
12468	<param name="priority" type="unsigned long" dir="in">
12469	<desc>The new CPU priority value. (1-100)</desc>
12470	</param>
12471	</method>
12472
12473	<method name="onVRDPServerChange">
12474	<desc>
12475	Triggered when settings of the VRDP server object of the
12476	associated virtual machine have changed.
12477
12478	<result name="VBOX_E_INVALID_VM_STATE">
12479	Session state prevents operation.
12480	</result>
12481	<result name="VBOX_E_INVALID_OBJECT_STATE">
12482	Session type prevents operation.
12483	</result>
12484
12485	</desc>
12486	<param name="restart" type="boolean" dir="in">
12487	<desc>Flag whether the server must be restarted</desc>
12488	</param>
12489	</method>
12490
12491	<method name="onUSBControllerChange">
12492	<desc>
12493	Triggered when settings of the USB controller object of the
12494	associated virtual machine have changed.
12495
12496	<result name="VBOX_E_INVALID_VM_STATE">
12497	Session state prevents operation.
12498	</result>
12499	<result name="VBOX_E_INVALID_OBJECT_STATE">
12500	Session type prevents operation.
12501	</result>
12502
12503	</desc>
12504	</method>
12505
12506	<method name="onSharedFolderChange">
12507	<desc>
12508	Triggered when a permanent (global or machine) shared folder has been
12509	created or removed.
12510	<note>
12511	We don't pass shared folder parameters in this notification because
12512	the order in which parallel notifications are delivered is not defined,
12513	therefore it could happen that these parameters were outdated by the
12514	time of processing this notification.
12515	</note>
12516
12517	<result name="VBOX_E_INVALID_VM_STATE">
12518	Session state prevents operation.
12519	</result>
12520	<result name="VBOX_E_INVALID_OBJECT_STATE">
12521	Session type prevents operation.
12522	</result>
12523
12524	</desc>
12525	<param name="global" type="boolean" dir="in"/>
12526	</method>
12527
12528	<method name="onUSBDeviceAttach">
12529	<desc>
12530	Triggered when a request to capture a USB device (as a result
12531	of matched USB filters or direct call to
12532	<link to="IConsole::attachUSBDevice"/>) has completed.
12533	A @c null @a error object means success, otherwise it
12534	describes a failure.
12535
12536	<result name="VBOX_E_INVALID_VM_STATE">
12537	Session state prevents operation.
12538	</result>
12539	<result name="VBOX_E_INVALID_OBJECT_STATE">
12540	Session type prevents operation.
12541	</result>
12542
12543	</desc>
12544	<param name="device" type="IUSBDevice" dir="in"/>
12545	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
12546	<param name="maskedInterfaces" type="unsigned long" dir="in"/>
12547	</method>
12548
12549	<method name="onUSBDeviceDetach">
12550	<desc>
12551	Triggered when a request to release the USB device (as a result
12552	of machine termination or direct call to
12553	<link to="IConsole::detachUSBDevice"/>) has completed.
12554	A @c null @a error object means success, otherwise it
12555	describes a failure.
12556
12557	<result name="VBOX_E_INVALID_VM_STATE">
12558	Session state prevents operation.
12559	</result>
12560	<result name="VBOX_E_INVALID_OBJECT_STATE">
12561	Session type prevents operation.
12562	</result>
12563
12564	</desc>
12565	<param name="id" type="uuid" mod="string" dir="in"/>
12566	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
12567	</method>
12568
12569	<method name="onShowWindow">
12570	<desc>
12571	Called by <link to="IMachine::canShowConsoleWindow"/> and by
12572	<link to="IMachine::showConsoleWindow"/> in order to notify
12573	console listeners
12574	<link to="ICanShowWindowEvent"/>
12575	and <link to="IShowWindowEvent"/>.
12576
12577	<result name="VBOX_E_INVALID_OBJECT_STATE">
12578	Session type prevents operation.
12579	</result>
12580
12581	</desc>
12582	<param name="check" type="boolean" dir="in"/>
12583	<param name="canShow" type="boolean" dir="out"/>
12584	<param name="winId" type="unsigned long long" dir="out"/>
12585	</method>
12586
12587	<method name="accessGuestProperty">
12588	<desc>
12589	Called by <link to="IMachine::getGuestProperty"/> and by
12590	<link to="IMachine::setGuestProperty"/> in order to read and
12591	modify guest properties.
12592
12593	<result name="VBOX_E_INVALID_VM_STATE">
12594	Machine session is not open.
12595	</result>
12596	<result name="VBOX_E_INVALID_OBJECT_STATE">
12597	Session type is not direct.
12598	</result>
12599
12600	</desc>
12601	<param name="name" type="wstring" dir="in"/>
12602	<param name="value" type="wstring" dir="in"/>
12603	<param name="flags" type="wstring" dir="in"/>
12604	<param name="isSetter" type="boolean" dir="in"/>
12605	<param name="retValue" type="wstring" dir="out"/>
12606	<param name="retTimestamp" type="unsigned long long" dir="out"/>
12607	<param name="retFlags" type="wstring" dir="out"/>
12608	</method>
12609
12610	<method name="enumerateGuestProperties">
12611	<desc>
12612	Return a list of the guest properties matching a set of patterns along
12613	with their values, time stamps and flags.
12614
12615	<result name="VBOX_E_INVALID_VM_STATE">
12616	Machine session is not open.
12617	</result>
12618	<result name="VBOX_E_INVALID_OBJECT_STATE">
12619	Session type is not direct.
12620	</result>
12621
12622	</desc>
12623	<param name="patterns" type="wstring" dir="in">
12624	<desc>
12625	The patterns to match the properties against as a comma-separated
12626	string. If this is empty, all properties currently set will be
12627	returned.
12628	</desc>
12629	</param>
12630	<param name="key" type="wstring" dir="out" safearray="yes">
12631	<desc>
12632	The key names of the properties returned.
12633	</desc>
12634	</param>
12635	<param name="value" type="wstring" dir="out" safearray="yes">
12636	<desc>
12637	The values of the properties returned. The array entries match the
12638	corresponding entries in the @a key array.
12639	</desc>
12640	</param>
12641	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
12642	<desc>
12643	The time stamps of the properties returned. The array entries match
12644	the corresponding entries in the @a key array.
12645	</desc>
12646	</param>
12647	<param name="flags" type="wstring" dir="out" safearray="yes">
12648	<desc>
12649	The flags of the properties returned. The array entries match the
12650	corresponding entries in the @a key array.
12651	</desc>
12652	</param>
12653	</method>
12654
12655	<method name="onlineMergeMedium">
12656	<desc>
12657	Triggers online merging of a hard disk. Used internally when deleting
12658	a snapshot while a VM referring to the same hard disk chain is running.
12659
12660	<result name="VBOX_E_INVALID_VM_STATE">
12661	Machine session is not open.
12662	</result>
12663	<result name="VBOX_E_INVALID_OBJECT_STATE">
12664	Session type is not direct.
12665	</result>
12666
12667	</desc>
12668	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
12669	<desc>The medium attachment to identify the medium chain.</desc>
12670	</param>
12671	<param name="sourceIdx" type="unsigned long" dir="in">
12672	<desc>The index of the source image in the chain.
12673	Redundant, but drastically reduces IPC.</desc>
12674	</param>
12675	<param name="targetIdx" type="unsigned long" dir="in">
12676	<desc>The index of the target image in the chain.
12677	Redundant, but drastically reduces IPC.</desc>
12678	</param>
12679	<param name="source" type="IMedium" dir="in">
12680	<desc>Merge source medium.</desc>
12681	</param>
12682	<param name="target" type="IMedium" dir="in">
12683	<desc>Merge target medium.</desc>
12684	</param>
12685	<param name="mergeForward" type="boolean" dir="in">
12686	<desc>Merge direction.</desc>
12687	</param>
12688	<param name="parentForTarget" type="IMedium" dir="in">
12689	<desc>For forward merges: new parent for target medium.</desc>
12690	</param>
12691	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
12692	<desc>For backward merges: list of media which need their parent UUID
12693	updated.</desc>
12694	</param>
12695	<param name="progress" type="IProgress" dir="in">
12696	<desc>
12697	Progress object for this operation.
12698	</desc>
12699	</param>
12700	</method>
12701
12702	</interface>
12703
12704	<interface
12705	name="ISession" extends="$unknown"
12706	uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
12707	wsmap="managed"
12708	>
12709	<desc>
12710	The ISession interface represents a client process and allows for locking
12711	virtual machines (represented by IMachine objects) to prevent conflicting
12712	changes to the machine.
12713
12714	Any caller wishing to manipulate a virtual machine needs to create a session
12715	object first, which lives in its own process space. Such session objects are
12716	then associated with <link to="IMachine" /> objects living in the VirtualBox
12717	server process to coordinate such changes.
12718
12719	There are two typical scenarios in which sessions are used:
12720
12721	<ul>
12722	<li>To alter machine settings or control a running virtual machine, one
12723	needs to lock a machine for a given session (client process) by calling
12724	<link to="IMachine::lockMachine"/>.
12725
12726	Whereas multiple sessions may control a running virtual machine, only
12727	one process can obtain a write lock on the machine to prevent conflicting
12728	changes. A write lock is also needed if a process wants to actually run a
12729	virtual machine in its own context, such as the VirtualBox GUI or
12730	VBoxHeadless front-ends. They must also lock a machine for their own
12731	sessions before they are allowed to power up the virtual machine.
12732
12733	As a result, no machine settings can be altered while another process is
12734	already using it, either because that process is modifying machine settings
12735	or because the machine is running.
12736	</li>
12737	<li>
12738	To start a VM using one of the existing VirtualBox front-ends (e.g. the
12739	VirtualBox GUI or VBoxHeadless), one would use
12740	<link to="IMachine::launchVMProcess"/>, which also takes a session object
12741	as its first parameter. This session then identifies the caller and lets the
12742	caller control the started machine (for example, pause machine execution or
12743	power it down) as well as be notified about machine execution state changes.
12744	</li>
12745	</ul>
12746
12747	How sessions objects are created in a client process depends on whether you use
12748	the Main API via COM or via the webservice:
12749
12750	<ul>
12751	<li>When using the COM API directly, an object of the Session class from the
12752	VirtualBox type library needs to be created. In regular COM C++ client code,
12753	this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
12754	This object will then act as a local session object in further calls to open
12755	a session.
12756	</li>
12757
12758	<li>In the webservice, the session manager (IWebsessionManager) instead creates
12759	a session object automatically whenever <link to="IWebsessionManager::logon" />
12760	is called. A managed object reference to that session object can be retrieved by
12761	calling <link to="IWebsessionManager::getSessionObject" />.
12762	</li>
12763	</ul>
12764	</desc>
12765
12766	<attribute name="state" type="SessionState" readonly="yes">
12767	<desc>Current state of this session.</desc>
12768	</attribute>
12769
12770	<attribute name="type" type="SessionType" readonly="yes">
12771	<desc>
12772	Type of this session. The value of this attribute is valid only
12773	if the session currently has a machine locked (i.e. its
12774	<link to="#state" /> is Locked), otherwise an error will be returned.
12775	</desc>
12776	</attribute>
12777
12778	<attribute name="machine" type="IMachine" readonly="yes">
12779	<desc>Machine object associated with this session.</desc>
12780	</attribute>
12781
12782	<attribute name="console" type="IConsole" readonly="yes">
12783	<desc>Console object associated with this session.</desc>
12784	</attribute>
12785
12786	<method name="unlockMachine">
12787	<desc>
12788	Unlocks a machine that was previously locked for the current session.
12789
12790	Calling this method is required every time a machine has been locked
12791	for a particular session using the <link to="IMachine::launchVMProcess" />
12792	or <link to="IMachine::lockMachine" /> calls. Otherwise the state of
12793	the machine will be set to <link to="MachineState_Aborted" /> on the
12794	server, and changes made to the machine settings will be lost.
12795
12796	Generally, it is recommended to unlock all machines explicitly
12797	before terminating the application (regardless of the reason for
12798	the termination).
12799
12800	<note>
12801	Do not expect the session state (<link to="ISession::state" />
12802	to return to "Unlocked" immediately after you invoke this method,
12803	particularly if you have started a new VM process. The session
12804	state will automatically return to "Unlocked" once the VM is no
12805	longer executing, which can of course take a very long time.
12806	</note>
12807
12808	<result name="E_UNEXPECTED">
12809	Session is not locked.
12810	</result>
12811
12812	</desc>
12813	</method>
12814
12815	</interface>
12816
12817	<!--
12818	// IStorageController
12819	/////////////////////////////////////////////////////////////////////////
12820	-->
12821
12822	<enum
12823	name="StorageBus"
12824	uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
12825	>
12826	<desc>
12827	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy);
12828	see <link to="IStorageController::bus" />.
12829	</desc>
12830	<const name="Null" value="0">
12831	<desc>@c null value. Never used by the API.</desc>
12832	</const>
12833	<const name="IDE" value="1"/>
12834	<const name="SATA" value="2"/>
12835	<const name="SCSI" value="3"/>
12836	<const name="Floppy" value="4"/>
12837	<const name="SAS" value="5"/>
12838	</enum>
12839
12840	<enum
12841	name="StorageControllerType"
12842	uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
12843	>
12844	<desc>
12845	The exact variant of storage controller hardware presented
12846	to the guest; see <link to="IStorageController::controllerType" />.
12847	</desc>
12848
12849	<const name="Null" value="0">
12850	<desc>@c null value. Never used by the API.</desc>
12851	</const>
12852	<const name="LsiLogic" value="1">
12853	<desc>A SCSI controller of the LsiLogic variant.</desc>
12854	</const>
12855	<const name="BusLogic" value="2">
12856	<desc>A SCSI controller of the BusLogic variant.</desc>
12857	</const>
12858	<const name="IntelAhci" value="3">
12859	<desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
12860	</const>
12861	<const name="PIIX3" value="4">
12862	<desc>An IDE controller of the PIIX3 variant.</desc>
12863	</const>
12864	<const name="PIIX4" value="5">
12865	<desc>An IDE controller of the PIIX4 variant.</desc>
12866	</const>
12867	<const name="ICH6" value="6">
12868	<desc>An IDE controller of the ICH6 variant.</desc>
12869	</const>
12870	<const name="I82078" value="7">
12871	<desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
12872	</const>
12873	<const name="LsiLogicSas" value="8">
12874	<desc>A variant of the LsiLogic controller using SAS.</desc>
12875	</const>
12876	</enum>
12877
12878	<interface
12879	name="IStorageController" extends="$unknown"
12880	uuid="fd93adc0-bbaa-4256-9e6e-00e29f9151c9"
12881	wsmap="managed"
12882	>
12883	<desc>
12884	Represents a storage controller that is attached to a virtual machine
12885	(<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
12886	attached to storage controllers in a real computer, virtual drives
12887	(represented by <link to="IMediumAttachment" />) are attached to virtual
12888	storage controllers, represented by this interface.
12889
12890	As opposed to physical hardware, VirtualBox has a very generic concept
12891	of a storage controller, and for purposes of the Main API, all virtual
12892	storage is attached to virtual machines via instances of this interface.
12893	There are five types of such virtual storage controllers: IDE, SCSI, SATA,
12894	SAS and Floppy (see <link to="#bus" />). Depending on which of these four
12895	is used, certain sub-types may be available and can be selected in
12896	<link to="#controllerType" />.
12897
12898	Depending on these settings, the guest operating system might see
12899	significantly different virtual hardware.
12900	</desc>
12901
12902	<attribute name="name" type="wstring" readonly="yes">
12903	<desc>
12904	Name of the storage controller, as originally specified with
12905	<link to="IMachine::addStorageController" />. This then uniquely
12906	identifies this controller with other method calls such as
12907	<link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
12908	</desc>
12909	</attribute>
12910
12911	<attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
12912	<desc>
12913	Maximum number of devices which can be attached to one port.
12914	</desc>
12915	</attribute>
12916
12917	<attribute name="minPortCount" type="unsigned long" readonly="yes">
12918	<desc>
12919	Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
12920	</desc>
12921	</attribute>
12922
12923	<attribute name="maxPortCount" type="unsigned long" readonly="yes">
12924	<desc>
12925	Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
12926	</desc>
12927	</attribute>
12928
12929	<attribute name="instance" type="unsigned long">
12930	<desc>
12931	The instance number of the device in the running VM.
12932	</desc>
12933	</attribute>
12934
12935	<attribute name="portCount" type="unsigned long">
12936	<desc>
12937	The number of currently usable ports on the controller.
12938	The minimum and maximum number of ports for one controller are
12939	stored in <link to="IStorageController::minPortCount"/>
12940	and <link to="IStorageController::maxPortCount"/>.
12941	</desc>
12942	</attribute>
12943
12944	<attribute name="bus" type="StorageBus" readonly="yes">
12945	<desc>
12946	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).
12947	</desc>
12948	</attribute>
12949
12950	<attribute name="controllerType" type="StorageControllerType">
12951	<desc>
12952	The exact variant of storage controller hardware presented
12953	to the guest.
12954	Depending on this value, VirtualBox will provide a different
12955	virtual storage controller hardware to the guest.
12956	For SATA, SAS and floppy controllers, only one variant is
12957	available, but for IDE and SCSI, there are several.
12958
12959	For SCSI controllers, the default type is LsiLogic.
12960	</desc>
12961	</attribute>
12962
12963	<attribute name="useHostIOCache" type="boolean">
12964	<desc>
12965	If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O
12966	caches and use synchronous file APIs on the host. This was the only option in the API before
12967	VirtualBox 3.2 and is still the default for IDE controllers.
12968
12969	If false, the host I/O cache will be disabled for image files attached to this storage controller.
12970	Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes
12971	it possible to turn off the host I/O caches because the emulation can handle unaligned access to
12972	the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many
12973	virtual machines are running at the same time to prevent I/O cache related hangs.
12974	This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.
12975	</desc>
12976	</attribute>
12977
12978	<method name="getIDEEmulationPort">
12979	<desc>
12980	Gets the corresponding port number which is emulated as an IDE device.
12981	Works only with SATA controllers.
12982
12983	<result name="E_INVALIDARG">
12984	The @a devicePosition is not in the range 0 to 3.
12985	</result>
12986	<result name="E_NOTIMPL">
12987	The storage controller type is not SATAIntelAhci.
12988	</result>
12989
12990	</desc>
12991	<param name="devicePosition" type="long" dir="in"/>
12992	<param name="portNumber" type="long" dir="return"/>
12993	</method>
12994
12995	<method name="setIDEEmulationPort">
12996	<desc>
12997	Sets the port number which is emulated as an IDE device.
12998	Works only with SATA controllers.
12999
13000	<result name="E_INVALIDARG">
13001	The @a devicePosition is not in the range 0 to 3 or the
13002	@a portNumber is not in the range 0 to 29.
13003	</result>
13004	<result name="E_NOTIMPL">
13005	The storage controller type is not SATAIntelAhci.
13006	</result>
13007
13008	</desc>
13009	<param name="devicePosition" type="long" dir="in"/>
13010	<param name="portNumber" type="long" dir="in"/>
13011	</method>
13012
13013	</interface>
13014
13015	<if target="wsdl">
13016
13017	<!--
13018	// IManagedObjectRef
13019	/////////////////////////////////////////////////////////////////////////
13020	-->
13021
13022	<interface
13023	name="IManagedObjectRef" extends="$unknown"
13024	uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
13025	internal="yes"
13026	wsmap="managed"
13027	wscpp="hardcoded"
13028	>
13029	<desc>
13030	Managed object reference.
13031
13032	Only within the webservice, a managed object reference (which is really
13033	an opaque number) allows a webservice client to address an object
13034	that lives in the address space of the webservice server.
13035
13036	Behind each managed object reference, there is a COM object that lives
13037	in the webservice server's address space. The COM object is not freed
13038	until the managed object reference is released, either by an explicit
13039	call to <link to="IManagedObjectRef::release" /> or by logging off from
13040	the webservice (<link to="IWebsessionManager::logoff" />), which releases
13041	all objects created during the webservice session.
13042
13043	Whenever a method call of the VirtualBox API returns a COM object, the
13044	webservice representation of that method will instead return a
13045	managed object reference, which can then be used to invoke methods
13046	on that object.
13047	</desc>
13048
13049	<method name="getInterfaceName">
13050	<desc>
13051	Returns the name of the interface that this managed object represents,
13052	for example, "IMachine", as a string.
13053	</desc>
13054	<param name="return" type="wstring" dir="return"/>
13055	</method>
13056
13057	<method name="release">
13058	<desc>
13059	Releases this managed object reference and frees the resources that
13060	were allocated for it in the webservice server process. After calling
13061	this method, the identifier of the reference can no longer be used.
13062	</desc>
13063	</method>
13064
13065	</interface>
13066
13067	<!--
13068	// IWebsessionManager
13069	/////////////////////////////////////////////////////////////////////////
13070	-->
13071
13072	<interface
13073	name="IWebsessionManager" extends="$unknown"
13074	uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
13075	internal="yes"
13076	wsmap="global"
13077	wscpp="hardcoded"
13078	>
13079	<desc>
13080	Websession manager. This provides essential services
13081	to webservice clients.
13082	</desc>
13083	<method name="logon">
13084	<desc>
13085	Logs a new client onto the webservice and returns a managed object reference to
13086	the IVirtualBox instance, which the client can then use as a basis to further
13087	queries, since all calls to the VirtualBox API are based on the IVirtualBox
13088	interface, in one way or the other.
13089	</desc>
13090	<param name="username" type="wstring" dir="in"/>
13091	<param name="password" type="wstring" dir="in"/>
13092	<param name="return" type="IVirtualBox" dir="return"/>
13093	</method>
13094
13095	<method name="getSessionObject">
13096	<desc>
13097	Returns a managed object reference to the internal ISession object that was created
13098	for this web service session when the client logged on.
13099
13100	<see>ISession</see>
13101	</desc>
13102	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
13103	<param name="return" type="ISession" dir="return"/>
13104	</method>
13105
13106	<method name="logoff">
13107	<desc>
13108	Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
13109	and destroys all resources associated with the session (most importantly, all
13110	managed objects created in the server while the session was active).
13111	</desc>
13112	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
13113	</method>
13114
13115	</interface>
13116
13117	</if>
13118
13119	<!--
13120	// IPerformanceCollector & friends
13121	/////////////////////////////////////////////////////////////////////////
13122	-->
13123
13124	<interface
13125	name="IPerformanceMetric" extends="$unknown"
13126	uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
13127	>
13128	<desc>
13129	The IPerformanceMetric interface represents parameters of the given
13130	performance metric.
13131	</desc>
13132
13133	<attribute name="metricName" type="wstring" readonly="yes">
13134	<desc>
13135	Name of the metric.
13136	</desc>
13137	</attribute>
13138
13139	<attribute name="object" type="$unknown" readonly="yes">
13140	<desc>
13141	Object this metric belongs to.
13142	</desc>
13143	</attribute>
13144
13145	<attribute name="description" type="wstring" readonly="yes">
13146	<desc>
13147	Textual description of the metric.
13148	</desc>
13149	</attribute>
13150
13151	<attribute name="period" type="unsigned long" readonly="yes">
13152	<desc>
13153	Time interval between samples, measured in seconds.
13154	</desc>
13155	</attribute>
13156
13157	<attribute name="count" type="unsigned long" readonly="yes">
13158	<desc>
13159	Number of recent samples retained by the performance collector for this
13160	metric.
13161
13162	When the collected sample count exceeds this number, older samples
13163	are discarded.
13164	</desc>
13165	</attribute>
13166
13167	<attribute name="unit" type="wstring" readonly="yes">
13168	<desc>
13169	Unit of measurement.
13170	</desc>
13171	</attribute>
13172
13173	<attribute name="minimumValue" type="long" readonly="yes">
13174	<desc>
13175	Minimum possible value of this metric.
13176	</desc>
13177	</attribute>
13178
13179	<attribute name="maximumValue" type="long" readonly="yes">
13180	<desc>
13181	Maximum possible value of this metric.
13182	</desc>
13183	</attribute>
13184	</interface>
13185
13186	<interface
13187	name="IPerformanceCollector" extends="$unknown"
13188	uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
13189	wsmap="managed"
13190	>
13191	<desc>
13192	The IPerformanceCollector interface represents a service that collects
13193	and stores performance metrics data.
13194
13195	Performance metrics are associated with objects of interfaces like IHost
13196	and IMachine. Each object has a distinct set of performance metrics. The
13197	set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
13198
13199	Metric data is collected at the specified intervals and is retained
13200	internally. The interval and the number of retained samples can be set
13201	with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
13202	and collection settings are not persistent, they are discarded as soon as
13203	VBoxSVC process terminates. Moreover, metric settings and data associated
13204	with a particular VM only exist while VM is running. They disappear as
13205	soon as VM shuts down. It is not possible to set up metrics for machines
13206	that are powered off. One needs to start VM first, then set up metric
13207	collection parameters.
13208
13209	Metrics are organized hierarchically, with each level separated by a
13210	slash (/) character. Generally, the scheme for metric names is like this:
13211
13212	<tt>Category/Metric[/SubMetric][:aggregation]</tt>
13213
13214	"Category/Metric" together form the base metric name. A base metric is
13215	the smallest unit for which a sampling interval and the number of
13216	retained samples can be set. Only base metrics can be enabled and
13217	disabled. All sub-metrics are collected when their base metric is
13218	collected. Collected values for any set of sub-metrics can be queried
13219	with <link to="IPerformanceCollector::queryMetricsData" />.
13220
13221	For example "CPU/Load/User:avg" metric name stands for the "CPU"
13222	category, "Load" metric, "User" submetric, "average" aggregate. An
13223	aggregate function is computed over all retained data. Valid aggregate
13224	functions are:
13225
13226	<ul>
13227	<li>avg -- average</li>
13228	<li>min -- minimum</li>
13229	<li>max -- maximum</li>
13230	</ul>
13231
13232	When setting up metric parameters, querying metric data, enabling or
13233	disabling metrics wildcards can be used in metric names to specify a
13234	subset of metrics. For example, to select all CPU-related metrics
13235	use <tt>CPU/</tt>, all averages can be queried using <tt>:avg</tt> and
13236	so on. To query metric values without aggregates <tt>*:</tt> can be used.
13237
13238	The valid names for base metrics are:
13239
13240	<ul>
13241	<li>CPU/Load</li>
13242	<li>CPU/MHz</li>
13243	<li>RAM/Usage</li>
13244	</ul>
13245
13246	The general sequence for collecting and retrieving the metrics is:
13247	<ul>
13248	<li>
13249	Obtain an instance of IPerformanceCollector with
13250	<link to="IVirtualBox::performanceCollector" />
13251	</li>
13252	<li>
13253	Allocate and populate an array with references to objects the metrics
13254	will be collected for. Use references to IHost and IMachine objects.
13255	</li>
13256	<li>
13257	Allocate and populate an array with base metric names the data will
13258	be collected for.
13259	</li>
13260	<li>
13261	Call <link to="IPerformanceCollector::setupMetrics" />. From now on
13262	the metric data will be collected and stored.
13263	</li>
13264	<li>
13265	Wait for the data to get collected.
13266	</li>
13267	<li>
13268	Allocate and populate an array with references to objects the metric
13269	values will be queried for. You can re-use the object array used for
13270	setting base metrics.
13271	</li>
13272	<li>
13273	Allocate and populate an array with metric names the data will be
13274	collected for. Note that metric names differ from base metric names.
13275	</li>
13276	<li>
13277	Call <link to="IPerformanceCollector::queryMetricsData" />. The data
13278	that have been collected so far are returned. Note that the values
13279	are still retained internally and data collection continues.
13280	</li>
13281	</ul>
13282
13283	For an example of usage refer to the following files in VirtualBox SDK:
13284	<ul>
13285	<li>
13286	Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
13287	</li>
13288	<li>
13289	Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
13290	</li>
13291	</ul>
13292	</desc>
13293
13294	<attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
13295	<desc>
13296	Array of unique names of metrics.
13297
13298	This array represents all metrics supported by the performance
13299	collector. Individual objects do not necessarily support all of them.
13300	<link to="IPerformanceCollector::getMetrics"/> can be used to get the
13301	list of supported metrics for a particular object.
13302	</desc>
13303	</attribute>
13304
13305	<method name="getMetrics">
13306	<desc>
13307	Returns parameters of specified metrics for a set of objects.
13308	<note>
13309	@c Null metrics array means all metrics. @c Null object array means
13310	all existing objects.
13311	</note>
13312	</desc>
13313	<param name="metricNames" type="wstring" dir="in" safearray="yes">
13314	<desc>
13315	Metric name filter. Currently, only a comma-separated list of metrics
13316	is supported.
13317	</desc>
13318	</param>
13319	<param name="objects" type="$unknown" dir="in" safearray="yes">
13320	<desc>
13321	Set of objects to return metric parameters for.
13322	</desc>
13323	</param>
13324	<param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
13325	<desc>
13326	Array of returned metric parameters.
13327	</desc>
13328	</param>
13329	</method>
13330
13331	<method name="setupMetrics">
13332	<desc>
13333	Sets parameters of specified base metrics for a set of objects. Returns
13334	an array of <link to="IPerformanceMetric" /> describing the metrics
13335	have been affected.
13336	<note>
13337	@c Null or empty metric name array means all metrics. @c Null or
13338	empty object array means all existing objects. If metric name array
13339	contains a single element and object array contains many, the single
13340	metric name array element is applied to each object array element to
13341	form metric/object pairs.
13342	</note>
13343	</desc>
13344	<param name="metricNames" type="wstring" dir="in" safearray="yes">
13345	<desc>
13346	Metric name filter. Comma-separated list of metrics with wildcard
13347	support.
13348	</desc>
13349	</param>
13350	<param name="objects" type="$unknown" dir="in" safearray="yes">
13351	<desc>
13352	Set of objects to setup metric parameters for.
13353	</desc>
13354	</param>
13355	<param name="period" type="unsigned long" dir="in">
13356	<desc>
13357	Time interval in seconds between two consecutive samples of
13358	performance data.
13359	</desc>
13360	</param>
13361	<param name="count" type="unsigned long" dir="in">
13362	<desc>
13363	Number of samples to retain in performance data history. Older
13364	samples get discarded.
13365	</desc>
13366	</param>
13367	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13368	<desc>
13369	Array of metrics that have been modified by the call to this method.
13370	</desc>
13371	</param>
13372	</method>
13373
13374	<method name="enableMetrics">
13375	<desc>
13376	Turns on collecting specified base metrics. Returns an array of
13377	<link to="IPerformanceMetric" /> describing the metrics have been
13378	affected.
13379	<note>
13380	@c Null or empty metric name array means all metrics. @c Null or
13381	empty object array means all existing objects. If metric name array
13382	contains a single element and object array contains many, the single
13383	metric name array element is applied to each object array element to
13384	form metric/object pairs.
13385	</note>
13386	</desc>
13387	<param name="metricNames" type="wstring" dir="in" safearray="yes">
13388	<desc>
13389	Metric name filter. Comma-separated list of metrics with wildcard
13390	support.
13391	</desc>
13392	</param>
13393	<param name="objects" type="$unknown" dir="in" safearray="yes">
13394	<desc>
13395	Set of objects to enable metrics for.
13396	</desc>
13397	</param>
13398	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13399	<desc>
13400	Array of metrics that have been modified by the call to this method.
13401	</desc>
13402	</param>
13403	</method>
13404
13405	<method name="disableMetrics">
13406	<desc>
13407	Turns off collecting specified base metrics. Returns an array of
13408	<link to="IPerformanceMetric" /> describing the metrics have been
13409	affected.
13410	<note>
13411	@c Null or empty metric name array means all metrics. @c Null or
13412	empty object array means all existing objects. If metric name array
13413	contains a single element and object array contains many, the single
13414	metric name array element is applied to each object array element to
13415	form metric/object pairs.
13416	</note>
13417	</desc>
13418	<param name="metricNames" type="wstring" dir="in" safearray="yes">
13419	<desc>
13420	Metric name filter. Comma-separated list of metrics with wildcard
13421	support.
13422	</desc>
13423	</param>
13424	<param name="objects" type="$unknown" dir="in" safearray="yes">
13425	<desc>
13426	Set of objects to disable metrics for.
13427	</desc>
13428	</param>
13429	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13430	<desc>
13431	Array of metrics that have been modified by the call to this method.
13432	</desc>
13433	</param>
13434	</method>
13435
13436	<method name="queryMetricsData">
13437	<desc>
13438	Queries collected metrics data for a set of objects.
13439
13440	The data itself and related metric information are returned in seven
13441	parallel and one flattened array of arrays. Elements of
13442	<tt>returnMetricNames, returnObjects, returnUnits, returnScales,
13443	returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
13444	the same index describe one set of values corresponding to a single
13445	metric.
13446
13447	The <tt>returnData</tt> parameter is a flattened array of arrays. Each
13448	start and length of a sub-array is indicated by
13449	<tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
13450	value for metric <tt>metricNames[i]</tt> is at
13451	<tt>returnData[returnIndices[i]]</tt>.
13452
13453	<note>
13454	@c Null or empty metric name array means all metrics. @c Null or
13455	empty object array means all existing objects. If metric name array
13456	contains a single element and object array contains many, the single
13457	metric name array element is applied to each object array element to
13458	form metric/object pairs.
13459	</note>
13460	<note>
13461	Data collection continues behind the scenes after call to @c
13462	queryMetricsData. The return data can be seen as the snapshot of the
13463	current state at the time of @c queryMetricsData call. The internally
13464	kept metric values are not cleared by the call. This makes possible
13465	querying different subsets of metrics or aggregates with subsequent
13466	calls. If periodic querying is needed it is highly suggested to query
13467	the values with @c interval*count period to avoid confusion. This way
13468	a completely new set of data values will be provided by each query.
13469	</note>
13470	</desc>
13471	<param name="metricNames" type="wstring" dir="in" safearray="yes">
13472	<desc>
13473	Metric name filter. Comma-separated list of metrics with wildcard
13474	support.
13475	</desc>
13476	</param>
13477	<param name="objects" type="$unknown" dir="in" safearray="yes">
13478	<desc>
13479	Set of objects to query metrics for.
13480	</desc>
13481	</param>
13482	<param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
13483	<desc>
13484	Names of metrics returned in @c returnData.
13485	</desc>
13486	</param>
13487	<param name="returnObjects" type="$unknown" dir="out" safearray="yes">
13488	<desc>
13489	Objects associated with metrics returned in @c returnData.
13490	</desc>
13491	</param>
13492	<param name="returnUnits" type="wstring" dir="out" safearray="yes">
13493	<desc>
13494	Units of measurement for each returned metric.
13495	</desc>
13496	</param>
13497	<param name="returnScales" type="unsigned long" dir="out" safearray="yes">
13498	<desc>
13499	Divisor that should be applied to return values in order to get
13500	floating point values. For example:
13501	<tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
13502	will retrieve the floating point value of i-th sample of the first
13503	metric.
13504	</desc>
13505	</param>
13506	<param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
13507	<desc>
13508	Sequence numbers of the first elements of value sequences of
13509	particular metrics returned in @c returnData. For aggregate metrics
13510	it is the sequence number of the sample the aggregate started
13511	calculation from.
13512	</desc>
13513	</param>
13514	<param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
13515	<desc>
13516	Indices of the first elements of value sequences of particular
13517	metrics returned in @c returnData.
13518	</desc>
13519	</param>
13520	<param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
13521	<desc>
13522	Lengths of value sequences of particular metrics.
13523	</desc>
13524	</param>
13525	<param name="returnData" type="long" dir="return" safearray="yes">
13526	<desc>
13527	Flattened array of all metric data containing sequences of values for
13528	each metric.
13529	</desc>
13530	</param>
13531	</method>
13532
13533	</interface>
13534	<enum
13535	name="NATAliasMode"
13536	uuid="67772168-50d9-11df-9669-7fb714ee4fa1">
13537	<desc></desc>
13538	<const name="AliasLog" value="0x1">
13539	<desc></desc>
13540	</const>
13541	<const name="AliasProxyOnly" value="0x02">
13542	<desc></desc>
13543	</const>
13544	<const name="AliasUseSamePorts" value="0x04">
13545	<desc></desc>
13546	</const>
13547	</enum>
13548	<enum
13549	name="NATProtocol"
13550	uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
13551	>
13552	<desc>Protocol definitions used with NAT port-forwarding rules.</desc>
13553	<const name="UDP" value="0">
13554	<desc>Port-forwarding uses UDP protocol.</desc>
13555	</const>
13556	<const name="TCP" value="1">
13557	<desc>Port-forwarding uses TCP protocol.</desc>
13558	</const>
13559	</enum>
13560
13561	<interface
13562	name="INATEngine" extends="$unknown"
13563	uuid="4b286616-eb03-11de-b0fb-1701eca42246"
13564	wsmap="managed"
13565	>
13566	<desc>Interface for managing a NAT engine which is used with a virtual machine. This
13567	allows for changing NAT behavior such as port-forwarding rules. This interface is
13568	used in the <link to="INetworkAdapter::natDriver" /> attribute.</desc>
13569	<attribute name="network" type="wstring">
13570	<desc>The network attribute of the NAT engine (the same value is used with built-in
13571	DHCP server to fill corresponding fields of DHCP leases).</desc>
13572	</attribute>
13573	<attribute name="hostIP" type="wstring">
13574	<desc>IP of host interface to bind all opened sockets to.
13575	<note>Changing this does not change binding of port forwarding.</note>
13576	</desc>
13577	</attribute>
13578	<attribute name="tftpPrefix" type="wstring">
13579	<desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
13580	the corresponding fields of DHCP leases.</desc>
13581	</attribute>
13582	<attribute name="tftpBootFile" type="wstring">
13583	<desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
13584	the corresponding fields of DHCP leases.</desc>
13585	</attribute>
13586	<attribute name="tftpNextServer" type="wstring">
13587	<desc>TFTP server attribute which is used with the built-in DHCP server to fill
13588	the corresponding fields of DHCP leases.
13589	<note>The preferred form is IPv4 addresses.</note>
13590	</desc>
13591	</attribute>
13592	<attribute name="aliasMode" type="unsigned long">
13593	<desc></desc>
13594	</attribute>
13595	<attribute name="dnsPassDomain" type="boolean">
13596	<desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
13597	</attribute>
13598	<attribute name="dnsProxy" type="boolean">
13599	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
13600	of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
13601	</attribute>
13602	<attribute name="dnsUseHostResolver" type="boolean">
13603	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
13604	of the DNS proxy and process traffic using the host resolver mechanism.</desc>
13605	</attribute>
13606	<attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
13607	<desc>Array of NAT port-forwarding rules in string representation, in the following
13608	format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
13609	</attribute>
13610	<method name="setNetworkSettings">
13611	<desc>Sets network configuration of the NAT engine.</desc>
13612	<param name="mtu" type="unsigned long" dir="in">
13613	<desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
13614	</param>
13615	<param name="sockSnd" type="unsigned long" dir="in">
13616	<desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
13617	</param>
13618	<param name="sockRcv" type="unsigned long" dir="in">
13619	<desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
13620	</param>
13621	<param name="TcpWndSnd" type="unsigned long" dir="in">
13622	<desc>Initial size of the NAT engine's sending TCP window in bytes when
13623	establishing a new TCP connection.</desc>
13624	</param>
13625	<param name="TcpWndRcv" type="unsigned long" dir="in">
13626	<desc>Initial size of the NAT engine's receiving TCP window in bytes when
13627	establishing a new TCP connection.</desc>
13628	</param>
13629	</method>
13630	<method name="getNetworkSettings">
13631	<desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
13632	for parameter descriptions.</desc>
13633	<param name="mtu" type="unsigned long" dir="out" />
13634	<param name="sockSnd" type="unsigned long" dir="out" />
13635	<param name="sockRcv" type="unsigned long" dir="out" />
13636	<param name="TcpWndSnd" type="unsigned long" dir="out" />
13637	<param name="TcpWndRcv" type="unsigned long" dir="out" />
13638	</method>
13639	<method name="addRedirect">
13640	<desc>Adds a new NAT port-forwarding rule.</desc>
13641	<param name="name" type="wstring" dir="in">
13642	<desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
13643	auto-generates one using the other parameters.</desc>
13644	</param>
13645	<param name="proto" type="NATProtocol" dir="in">
13646	<desc>Protocol handled with the rule.</desc>
13647	</param>
13648	<param name="hostIp" type="wstring" dir="in">
13649	<desc>IP of the host interface to which the rule should apply. An empty ip address is
13650	acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
13651	</param>
13652	<param name="hostPort" type="unsigned short" dir="in">
13653	<desc>The port number to listen on.</desc>
13654	</param>
13655	<param name="guestIp" type="wstring" dir="in">
13656	<desc>The IP address of the guest which the NAT engine will forward matching packets
13657	to. An empty IP address is acceptable, in which case the NAT engine will forward
13658	packets to the first DHCP lease (x.x.x.15).</desc>
13659	</param>
13660	<param name="guestPort" type="unsigned short" dir="in">
13661	<desc>The port number to forward.</desc>
13662	</param>
13663	</method>
13664	<method name="removeRedirect">
13665	<desc>Removes a port-forwarding rule that was previously registered.</desc>
13666	<param name="name" type="wstring" dir="in">
13667	<desc>The name of the rule to delete.</desc>
13668	</param>
13669	</method>
13670	</interface>
13671
13672	<enum
13673	name="VBoxEventType"
13674	uuid="2c76667e-6981-4122-a71a-cdfd6a6eb575">
13675
13676	<desc>
13677	Type of an event.
13678	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
13679	</desc>
13680
13681	<const name="Invalid" value="0">
13682	<desc>
13683	Invalid event, must be first.
13684	</desc>
13685	</const>
13686
13687	<const name="Any" value="1">
13688	<desc>
13689	Wildcard for all events.
13690	Events of this type are never delivered, and only used in
13691	registerListener() call to simplify registration.
13692	</desc>
13693	</const>
13694
13695	<const name="Vetoable" value="2">
13696	<desc>
13697	Wildcard for all vetoable events. Events of this type are never delivered, and only
13698	used in registerListener() call to simplify registration.
13699	</desc>
13700	</const>
13701
13702	<const name="MachineEvent" value="3">
13703	<desc>
13704	Wildcard for all machine events. Events of this type are never delivered, and only used in
13705	registerListener() call to simplify registration.
13706	</desc>
13707	</const>
13708
13709	<const name="SnapshotEvent" value="4">
13710	<desc>
13711	Wildcard for all snapshot events. Events of this type are never delivered, and only used in
13712	registerListener() call to simplify registration.
13713	</desc>
13714	</const>
13715
13716	<const name="InputEvent" value="5">
13717	<desc>
13718	Wildcard for all input device (keyboard, mouse) events.
13719	Events of this type are never delivered, and only used in
13720	registerListener() call to simplify registration.
13721	</desc>
13722	</const>
13723
13724	<const name="LastWildcard" value="31">
13725	<desc>
13726	Last wildcard.
13727	</desc>
13728	</const>
13729
13730	<const name="OnMachineStateChanged" value="32">
13731	<desc>
13732	See <link to="IMachineStateChangedEvent">IMachineStateChangedEvent</link>.
13733	</desc>
13734	</const>
13735	<const name="OnMachineDataChanged" value="33">
13736	<desc>
13737	See <link to="IMachineDataChangedEvent">IMachineDataChangedEvent</link>.
13738	</desc>
13739	</const>
13740	<const name="OnExtraDataChanged" value="34">
13741	<desc>
13742	See <link to="IExtraDataChangedEvent">IExtraDataChangedEvent</link>.
13743	</desc>
13744	</const>
13745	<const name="OnExtraDataCanChange" value="35">
13746	<desc>
13747	See <link to="IExtraDataCanChangeEvent">IExtraDataCanChangeEvent</link>.
13748	</desc>
13749	</const>
13750	<const name="OnMediumRegistered" value="36">
13751	<desc>
13752	See <link to="IMediumRegisteredEvent">IMediumRegisteredEvent</link>.
13753	</desc>
13754	</const>
13755	<const name="OnMachineRegistered" value="37">
13756	<desc>
13757	See <link to="IMachineRegisteredEvent">IMachineRegisteredEvent</link>.
13758	</desc>
13759	</const>
13760	<const name="OnSessionStateChanged" value="38">
13761	<desc>
13762	See <link to="ISessionStateChangedEvent">ISessionStateChangedEvent</link>.
13763	</desc>
13764	</const>
13765	<const name="OnSnapshotTaken" value="39">
13766	<desc>
13767	See <link to="ISnapshotTakenEvent">ISnapshotTakenEvent</link>.
13768	</desc>
13769	</const>
13770	<const name="OnSnapshotDeleted" value="40">
13771	<desc>
13772	See <link to="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>.
13773	</desc>
13774	</const>
13775	<const name="OnSnapshotChanged" value="41">
13776	<desc>
13777	See <link to="ISnapshotChangedEvent">ISnapshotChangedEvent</link>.
13778	</desc>
13779	</const>
13780	<const name="OnGuestPropertyChanged" value="42">
13781	<desc>
13782	See <link to="IGuestPropertyChangedEvent">IGuestPropertyChangedEvent</link>.
13783	</desc>
13784	</const>
13785	<!-- Console events -->
13786	<const name="OnMousePointerShapeChanged" value="43">
13787	<desc>
13788	See <link to="IMousePointerShapeChangedEvent">IMousePointerShapeChangedEvent</link>.
13789	</desc>
13790	</const>
13791	<const name="OnMouseCapabilityChanged" value="44">
13792	<desc>
13793	See <link to="IMouseCapabilityChangedEvent">IMouseCapabilityChangedEvent</link>.
13794	</desc>
13795	</const>
13796	<const name="OnKeyboardLedsChanged" value="45">
13797	<desc>
13798	See <link to="IKeyboardLedsChangedEvent">IKeyboardLedsChangedEvent</link>.
13799	</desc>
13800	</const>
13801	<const name="OnStateChanged" value="46">
13802	<desc>
13803	See <link to="IStateChangedEvent">IStateChangedEvent</link>.
13804	</desc>
13805	</const>
13806	<const name="OnAdditionsStateChanged" value="47">
13807	<desc>
13808	See <link to="IAdditionsStateChangedEvent">IAdditionsStateChangedEvent</link>.
13809	</desc>
13810	</const>
13811	<const name="OnNetworkAdapterChanged" value="48">
13812	<desc>
13813	See <link to="INetworkAdapterChangedEvent">INetworkAdapterChangedEvent</link>.
13814	</desc>
13815	</const>
13816	<const name="OnSerialPortChanged" value="49">
13817	<desc>
13818	See <link to="ISerialPortChangedEvent">ISerialPortChangedEvent</link>.
13819	</desc>
13820	</const>
13821	<const name="OnParallelPortChanged" value="50">
13822	<desc>
13823	See <link to="IParallelPortChangedEvent">IParallelPortChangedEvent</link>.
13824	</desc>
13825	</const>
13826	<const name="OnStorageControllerChanged" value="51">
13827	<desc>
13828	See <link to="IStorageControllerChangedEvent">IStorageControllerChangedEvent</link>.
13829	</desc>
13830	</const>
13831	<const name="OnMediumChanged" value="52">
13832	<desc>
13833	See <link to="IMediumChangedEvent">IMediumChangedEvent</link>.
13834	</desc>
13835	</const>
13836	<const name="OnVRDPServerChanged" value="53">
13837	<desc>
13838	See <link to="IVRDPServerChangedEvent">IVRDPServerChangedEvent</link>.
13839	</desc>
13840	</const>
13841	<const name="OnUSBControllerChanged" value="54">
13842	<desc>
13843	See <link to="IUSBControllerChangedEvent">IUSBControllerChangedEvent</link>.
13844	</desc>
13845	</const>
13846	<const name="OnUSBDeviceStateChanged" value="55">
13847	<desc>
13848	See <link to="IUSBDeviceStateChangedEvent">IUSBDeviceStateChangedEvent</link>.
13849	</desc>
13850	</const>
13851	<const name="OnSharedFolderChanged" value="56">
13852	<desc>
13853	See <link to="ISharedFolderChangedEvent">ISharedFolderChangedEvent</link>.
13854	</desc>
13855	</const>
13856	<const name="OnRuntimeError" value="57">
13857	<desc>
13858	See <link to="IRuntimeErrorEvent">IRuntimeErrorEvent</link>.
13859	</desc>
13860	</const>
13861	<const name="OnCanShowWindow" value="58">
13862	<desc>
13863	See <link to="ICanShowWindowEvent">ICanShowWindowEvent</link>.
13864	</desc>
13865	</const>
13866	<const name="OnShowWindow" value="59">
13867	<desc>
13868	See <link to="IShowWindowEvent">IShowWindowEvent</link>.
13869	</desc>
13870	</const>
13871	<const name="OnCPUChanged" value="60">
13872	<desc>
13873	See <link to="ICPUChangedEvent">ICPUChangedEvent</link>.
13874	</desc>
13875	</const>
13876	<const name="OnRemoteDisplayInfoChanged" value="61">
13877	<desc>
13878	See <link to="IRemoteDisplayInfoChangedEvent">IRemoteDisplayInfoChangedEvent</link>.
13879	</desc>
13880	</const>
13881	<const name="OnEventSourceChanged" value="62">
13882	<desc>
13883	See <link to="IEventSourceChangedEvent">IEventSourceChangedEvent</link>.
13884	</desc>
13885	</const>
13886	<const name="OnCPUPriorityChanged" value="63">
13887	<desc>
13888	See <link to="ICPUPriorityChangedEvent">ICPUPriorityChangedEvent</link>.
13889	</desc>
13890	</const>
13891	<!-- Last event marker -->
13892	<const name="Last" value="64">
13893	<desc>
13894	Must be last event, used for iterations and structures relying on numerical event values.
13895	</desc>
13896	</const>
13897
13898	</enum>
13899
13900	<interface
13901	name="IEventSource" extends="$unknown"
13902	uuid="3c670618-f727-4fe9-94d2-8243f489a033"
13903	wsmap="managed"
13904	>
13905	<desc>
13906	Event source. Generally, any object which could generate events can be an event source,
13907	or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S),
13908	an event source can work with listeners in either active or passive mode. In active mode it is up to
13909	the IEventSource implementation to call <link to="IEventListener::handleEvent" />, in passive mode the
13910	event source keeps track of pending events for each listener and returns available events on demand.
13911
13912	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
13913	</desc>
13914
13915	<method name="createListener">
13916	<desc>
13917	Creates a new listener object, useful for passive mode.
13918	</desc>
13919	<param name="listener" type="IEventListener" dir="return"/>
13920	</method>
13921
13922	<method name="registerListener">
13923	<desc>
13924	Register an event listener.
13925
13926	<note>
13927	To avoid system overload, the VirtualBox server process checks if passive event
13928	listeners call <link to="IEventSource::getEvent"/> frequently enough. In the
13929	current implementation, if more than 100 pending events are detected for a passive
13930	event listener, it is forcefully unregistered by the system, and further
13931	<link to="#getEvent" /> calls will return @c VBOX_E_OBJECT_NOT_FOUND.
13932	</note>
13933	</desc>
13934	<param name="listener" type="IEventListener" dir="in">
13935	<desc>Listener to register.</desc>
13936	</param>
13937	<param name="interesting" type="VBoxEventType" dir="in" safearray="yes">
13938	<desc>
13939	Event types listener is interested in. One can use wildcards like -
13940	<link to="VBoxEventType::Any"/> to specify wildcards, matching more
13941	than one event.
13942	</desc>
13943	</param>
13944	<param name="active" type="boolean" dir="in">
13945	<desc>
13946	Which mode this listener is operating in.
13947	In active mode, <link to="IEventListener::handleEvent" /> is called directly.
13948	In passive mode, an internal event queue is created for this this IEventListener.
13949	For each event coming in, it is added to queues for all interested registered passive
13950	listeners. It is then up to the external code to call the listener's
13951	<link to="IEventListener::handleEvent" /> method. When done with an event, the
13952	external code must call <link to="#eventProcessed" />.
13953	</desc>
13954	</param>
13955	</method>
13956
13957	<method name="unregisterListener">
13958	<desc>
13959	Unregister an event listener. If listener is passive, and some waitable events are still
13960	in queue they are marked as processed automatically.
13961	</desc>
13962	<param name="listener" type="IEventListener" dir="in">
13963	<desc>Listener to unregister.</desc>
13964	</param>
13965	</method>
13966
13967	<method name="fireEvent">
13968	<desc>
13969	Fire an event for this source.
13970	</desc>
13971	<param name="event" type="IEvent" dir="in">
13972	<desc>Event to deliver.</desc>
13973	</param>
13974	<param name="timeout" type="long" dir="in">
13975	<desc>
13976	Maximum time to wait for event processing (if event is waitable), in ms;
13977	0 = no wait, -1 = indefinite wait.
13978	</desc>
13979	</param>
13980	<param name="result" type="boolean" dir="return">
13981	<desc>true if an event was delivered to all targets, or is non-waitable.</desc>
13982	</param>
13983	</method>
13984
13985	<method name="getEvent">
13986	<desc>
13987	Get events from this peer's event queue (for passive mode). Calling this method
13988	regularly is required for passive event listeners to avoid system overload;
13989	see <link to="IEventSource::registerListener" /> for details.
13990
13991	<result name="VBOX_E_OBJECT_NOT_FOUND">
13992	Listener is not registered, or autounregistered.
13993	</result>
13994	</desc>
13995	<param name="listener" type="IEventListener" dir="in">
13996	<desc>Which listener to get data for.</desc>
13997	</param>
13998	<param name="timeout" type="long" dir="in">
13999	<desc>
14000	Maximum time to wait for events, in ms;
14001	0 = no wait, -1 = indefinite wait.
14002	</desc>
14003	</param>
14004	<param name="event" type="IEvent" dir="return">
14005	<desc>Event retrieved, or null if none available.</desc>
14006	</param>
14007	</method>
14008
14009	<method name="eventProcessed">
14010	<desc>
14011	Must be called for waitable events after a particular listener finished its
14012	event processing. When all listeners of a particular event have called this
14013	method, the system will then call <link to="IEvent::setProcessed" />.
14014	</desc>
14015	<param name="listener" type="IEventListener" dir="in">
14016	<desc>Which listener processed event.</desc>
14017	</param>
14018	<param name="event" type="IEvent" dir="in">
14019	<desc>Which event.</desc>
14020	</param>
14021	</method>
14022
14023	</interface>
14024
14025	<interface
14026	name="IEventListener" extends="$unknown"
14027	uuid="67099191-32e7-4f6c-85ee-422304c71b90"
14028	wsmap="managed"
14029	>
14030	<desc>
14031	Event listener. An event listener can work in either active or passive mode, depending on the way
14032	it was registered.
14033	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
14034	</desc>
14035
14036	<method name="handleEvent">
14037	<desc>
14038	Handle event callback (called directly by IEventSource in active mode, or could be
14039	called by event processor thread in passive mode).
14040	</desc>
14041	<param name="event" type="IEvent" dir="in">
14042	<desc>Event available.</desc>
14043	</param>
14044	</method>
14045
14046	</interface>
14047
14048	<interface
14049	name="IEvent" extends="$unknown"
14050	uuid="0ca2adba-8f30-401b-a8cd-fe31dbe839c0"
14051	wsmap="managed"
14052	>
14053	<desc>
14054	Abstract parent interface for VirtualBox events. Actual events will typically implement
14055	a more specific interface which derives from this (see below).
14056
14057	<b>Introduction to VirtualBox events</b>
14058
14059	Generally speaking, an event (represented by this interface) signals that something
14060	happened, while an event listener (see <link to="IEventListener" />) represents an
14061	entity that is interested in certain events. In order for this to work with
14062	unidirectional protocols (i.e. web services), the concepts of passive and active
14063	listener are used.
14064
14065	Event consumers can register themselves as listeners, providing an array of
14066	events they are interested in (see <link to="IEventSource::registerListener" />).
14067	When an event triggers, the listener is notified about the event. The exact
14068	mechanism of the notification depends on whether the listener was registered as
14069	an active or passive listener:
14070
14071	<ul>
14072	<li>An active listener is very similar to a callback: it is a function invoked
14073	by the API. As opposed to the callbacks that were used in the API before
14074	VirtualBox 3.3 however, events are now objects with an interface hierarchy.
14075	</li>
14076
14077	<li>Passive listeners are somewhat tricker to implement, but do not require
14078	a client function to be callable, which is not an option with scripting
14079	languages or web service clients. Internally the <link to="IEventSource" />
14080	implementation maintains an event queue for each passive listener, and
14081	newly arrived events are put in this queue. When the listener calls
14082	<link to="IEventSource::getEvent"/>, first element from its internal event
14083	queue is returned. When the client completes processing of an event,
14084	the <link to="IEventSource::eventProcessed" /> function must be called,
14085	acknowledging that the event was processed. It supports implementing
14086	waitable events. On passive listener unregistration, all events from its
14087	queue are auto-acknowledged.
14088	</li>
14089	</ul>
14090
14091	Waitable events are useful in situations where the event generator wants to track
14092	delivery or a party wants to wait until all listeners have completed the event. A
14093	typical example would be a vetoable event (see <link to="IVetoEvent" />) where a
14094	listeners might veto a certain action, and thus the event producer has to make
14095	sure that all listeners have processed the event and not vetoed before taking
14096	the action.
14097
14098	A given event may have both passive and active listeners at the same time.
14099
14100	<b>Using events</b>
14101
14102	Any VirtualBox object capable of producing externally visible events provides an
14103	@c eventSource read-only attribute, which is of the type <link to="IEventSource" />.
14104	This event source object is notified by VirtualBox once something has happened, so
14105	consumers may register event listeners with this event source. To register a listener,
14106	an object implementing the <link to="IEventListener" /> interface must be provided.
14107	For active listeners, such an object is typically created by the consumer, while for
14108	passive listeners <link to="IEventSource::createListener" /> should be used. Please
14109	note that a listener created with @c createListener() must not be used as an active listener.
14110
14111	Once created, the listener must be registered to listen for the desired events
14112	(see <link to="IEventSource::registerListener" />), providing an array of
14113	<link to="VBoxEventType" /> enums. Those elements can either be the individual
14114	event IDs or wildcards matching multiple event IDs.
14115
14116	After registration, the callback's <link to="IEventListener::handleEvent" /> method is
14117	called automatically when the event is triggered, while passive listeners have to call
14118	<link to="IEventSource::getEvent" /> and <link to="IEventSource::eventProcessed" /> in
14119	an event processing loop.
14120
14121	The IEvent interface is an abstract parent interface for all such VirtualBox events
14122	coming in. As a result, the standard use pattern inside <link to="IEventListener::handleEvent" />
14123	or the event processing loop is to check the <link to="#type" /> attribute of the event and
14124	then cast to the appropriate specific interface using @c QueryInterface().
14125	</desc>
14126
14127	<attribute name="type" readonly="yes" type="VBoxEventType">
14128	<desc>
14129	Event type.
14130	</desc>
14131	</attribute>
14132
14133	<attribute name="source" readonly="yes" type="IEventSource">
14134	<desc>
14135	Source of this event.
14136	</desc>
14137	</attribute>
14138
14139	<attribute name="waitable" readonly="yes" type="boolean">
14140	<desc>
14141	If we can wait for this event being processed. If false, waitProcessed() returns immediately,
14142	and setProcessed() doesn't make sense. Non-waitable events are generally better performing,
14143	as no additional overhead associated with waitability imposed.
14144	Waitable events are needed when one need to be able to wait for particular event processed,
14145	for example for vetoable changes, or if event refers to some resource which need to be kept immutable
14146	until all consumers confirmed events.
14147	</desc>
14148	</attribute>
14149
14150	<method name="setProcessed">
14151	<desc>
14152	Internal method called by the system when all listeners of a particular event have called
14153	<link to="IEventSource::eventProcessed" />. This should not be called by client code.
14154	</desc>
14155	</method>
14156
14157	<method name="waitProcessed">
14158	<desc>
14159	Wait until time outs, or this event is processed. Event must be waitable for this operation to have
14160	described semantics, for non-waitable returns true immediately.
14161	</desc>
14162	<param name="timeout" type="long" dir="in">
14163	<desc>
14164	Maximum time to wait for event processeing, in ms;
14165	0 = no wait, -1 = indefinite wait.
14166	</desc>
14167	</param>
14168	<param name="result" type="boolean" dir="return">
14169	<desc>If this event was processed before timeout.</desc>
14170	</param>
14171	</method>
14172	</interface>
14173
14174
14175	<interface
14176	name="IMachineEvent" extends="IEvent"
14177	uuid="92ed7b1a-0d96-40ed-ae46-a564d484325e"
14178	wsmap="managed" id="MachineEvent"
14179	>
14180	<desc>Base abstract interface for all machine events.</desc>
14181
14182	<attribute name="machineId" readonly="yes" type="uuid" mod="string">
14183	<desc>ID of the machine this event relates to.</desc>
14184	</attribute>
14185
14186	</interface>
14187
14188	<interface
14189	name="IMachineStateChangedEvent" extends="IMachineEvent"
14190	uuid="5748F794-48DF-438D-85EB-98FFD70D18C9"
14191	wsmap="managed" autogen="VBoxEvent" id="OnMachineStateChanged"
14192	>
14193	<desc>Machine state change event.</desc>
14194
14195	<attribute name="state" readonly="yes" type="MachineState">
14196	<desc>New execution state.</desc>
14197	</attribute>
14198	</interface>
14199
14200	<interface
14201	name="IMachineDataChangedEvent" extends="IMachineEvent"
14202	uuid="6AA70A6C-0DCA-4810-8C5C-457B278E3D49"
14203	wsmap="managed" autogen="VBoxEvent" id="OnMachineDataChanged"
14204	>
14205	<desc>
14206	Any of the settings of the given machine has changed.
14207	</desc>
14208	</interface>
14209
14210	<interface
14211	name="IMediumRegisteredEvent" extends="IEvent"
14212	uuid="53fac49a-b7f1-4a5a-a4ef-a11dd9c2a458"
14213	wsmap="managed" autogen="VBoxEvent" id="OnMediumRegistered"
14214	>
14215	<desc>
14216	The given medium was registered or unregistered
14217	within this VirtualBox installation.
14218	</desc>
14219
14220	<attribute name="mediumId" readonly="yes" type="uuid" mod="string">
14221	<desc>ID of the medium this event relates to.</desc>
14222	</attribute>
14223
14224	<attribute name="mediumType" readonly="yes" type="DeviceType">
14225	<desc>Type of the medium this event relates to.</desc>
14226	</attribute>
14227
14228	<attribute name="registered" type="boolean" readonly="yes">
14229	<desc>
14230	If @c true, the medium was registered, otherwise it was
14231	unregistered.
14232	</desc>
14233	</attribute>
14234	</interface>
14235
14236	<interface
14237	name="IMachineRegisteredEvent" extends="IMachineEvent"
14238	uuid="c354a762-3ff2-4f2e-8f09-07382ee25088"
14239	wsmap="managed" autogen="VBoxEvent" id="OnMachineRegistered"
14240	>
14241	<desc>
14242	The given machine was registered or unregistered
14243	within this VirtualBox installation.
14244	</desc>
14245
14246	<attribute name="registered" type="boolean" readonly="yes">
14247	<desc>
14248	If @c true, the machine was registered, otherwise it was
14249	unregistered.
14250	</desc>
14251	</attribute>
14252	</interface>
14253
14254	<interface
14255	name="ISessionStateChangedEvent" extends="IMachineEvent"
14256	uuid="714a3eef-799a-4489-86cd-fe8e45b2ff8e"
14257	wsmap="managed" autogen="VBoxEvent" id="OnSessionStateChanged"
14258	>
14259	<desc>
14260	The state of the session for the given machine was changed.
14261	<see>IMachine::sessionState</see>
14262	</desc>
14263
14264	<attribute name="state" type="SessionState" readonly="yes">
14265	<desc>
14266	New session state.
14267	</desc>
14268	</attribute>
14269	</interface>
14270
14271	<interface
14272	name="IGuestPropertyChangedEvent" extends="IMachineEvent"
14273	uuid="3f63597a-26f1-4edb-8dd2-6bddd0912368"
14274	wsmap="managed" autogen="VBoxEvent" id="OnGuestPropertyChanged"
14275	>
14276	<desc>
14277	Notification when a guest property has changed.
14278	</desc>
14279
14280	<attribute name="name" readonly="yes" type="wstring">
14281	<desc>
14282	The name of the property that has changed.
14283	</desc>
14284	</attribute>
14285
14286	<attribute name="value" readonly="yes" type="wstring">
14287	<desc>
14288	The new property value.
14289	</desc>
14290	</attribute>
14291
14292	<attribute name="flags" readonly="yes" type="wstring">
14293	<desc>
14294	The new property flags.
14295	</desc>
14296	</attribute>
14297
14298	</interface>
14299
14300	<interface
14301	name="ISnapshotEvent" extends="IMachineEvent"
14302	uuid="21637b0e-34b8-42d3-acfb-7e96daf77c22"
14303	wsmap="managed" id="SnapshotEvent"
14304	>
14305	<desc>Base interface for all snapshot events.</desc>
14306
14307	<attribute name="snapshotId" readonly="yes" type="uuid" mod="string">
14308	<desc>ID of the snapshot this event relates to.</desc>
14309	</attribute>
14310
14311	</interface>
14312
14313	<interface
14314	name="ISnapshotTakenEvent" extends="ISnapshotEvent"
14315	uuid="d27c0b3d-6038-422c-b45e-6d4a0503d9f1"
14316	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotTaken"
14317	>
14318	<desc>
14319	A new snapshot of the machine has been taken.
14320	<see>ISnapshot</see>
14321	</desc>
14322	</interface>
14323
14324	<interface
14325	name="ISnapshotDeletedEvent" extends="ISnapshotEvent"
14326	uuid="c48f3401-4a9e-43f4-b7a7-54bd285e22f4"
14327	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotDeleted"
14328	>
14329	<desc>
14330	Snapshot of the given machine has been deleted.
14331
14332	<note>
14333	This notification is delivered <b>after</b> the snapshot
14334	object has been uninitialized on the server (so that any
14335	attempt to call its methods will return an error).
14336	</note>
14337
14338	<see>ISnapshot</see>
14339	</desc>
14340	</interface>
14341
14342	<interface
14343	name="ISnapshotChangedEvent" extends="ISnapshotEvent"
14344	uuid="07541941-8079-447a-a33e-47a69c7980db"
14345	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotChanged"
14346	>
14347	<desc>
14348	Snapshot properties (name and/or description) have been changed.
14349	<see>ISnapshot</see>
14350	</desc>
14351	</interface>
14352
14353	<interface
14354	name="IMousePointerShapeChangedEvent" extends="IEvent"
14355	uuid="a6dcf6e8-416b-4181-8c4a-45ec95177aef"
14356	wsmap="managed" autogen="VBoxEvent" id="OnMousePointerShapeChanged"
14357	>
14358	<desc>
14359	Notification when the guest mouse pointer shape has
14360	changed. The new shape data is given.
14361	</desc>
14362
14363	<attribute name="visible" type="boolean" readonly="yes">
14364	<desc>
14365	Flag whether the pointer is visible.
14366	</desc>
14367	</attribute>
14368	<attribute name="alpha" type="boolean" readonly="yes">
14369	<desc>
14370	Flag whether the pointer has an alpha channel.
14371	</desc>
14372	</attribute>
14373	<attribute name="xhot" type="unsigned long" readonly="yes">
14374	<desc>
14375	The pointer hot spot X coordinate.
14376	</desc>
14377	</attribute>
14378	<attribute name="yhot" type="unsigned long" readonly="yes">
14379	<desc>
14380	The pointer hot spot Y coordinate.
14381	</desc>
14382	</attribute>
14383	<attribute name="width" type="unsigned long" readonly="yes">
14384	<desc>
14385	Width of the pointer shape in pixels.
14386	</desc>
14387	</attribute>
14388	<attribute name="height" type="unsigned long" readonly="yes">
14389	<desc>
14390	Height of the pointer shape in pixels.
14391	</desc>
14392	</attribute>
14393	<attribute name="shape" type="octet" safearray="yes" readonly="yes">
14394	<desc>
14395	Shape buffer arrays.
14396
14397	The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
14398	followed by a 32-bpp XOR (color) mask.
14399
14400	For pointers without alpha channel the XOR mask pixels are 32
14401	bit values: (lsb)BGR0(msb). For pointers with alpha channel
14402	the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
14403
14404	An AND mask is used for pointers with alpha channel, so if the
14405	callback does not support alpha, the pointer could be
14406	displayed as a normal color pointer.
14407
14408	The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
14409	size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
14410	height</tt>. The padding bits at the end of each scanline are
14411	undefined.
14412
14413	The XOR mask follows the AND mask on the next 4-byte aligned
14414	offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
14415	Bytes in the gap between the AND and the XOR mask are undefined.
14416	The XOR mask scanlines have no gap between them and the size of
14417	the XOR mask is: <tt>cXor = width * 4 * height</tt>.
14418
14419	<note>
14420	If @a shape is 0, only the pointer visibility is changed.
14421	</note>
14422	</desc>
14423	</attribute>
14424	</interface>
14425
14426	<interface
14427	name="IMouseCapabilityChangedEvent" extends="IEvent"
14428	uuid="d633ad48-820c-4207-b46c-6bd3596640d5"
14429	wsmap="managed" autogen="VBoxEvent" id="OnMouseCapabilityChanged"
14430	>
14431	<desc>
14432	Notification when the mouse capabilities reported by the
14433	guest have changed. The new capabilities are passed.
14434	</desc>
14435	<attribute name="supportsAbsolute" type="boolean" readonly="yes">
14436	<desc>
14437	Supports absolute coordinates.
14438	</desc>
14439	</attribute>
14440	<attribute name="supportsRelative" type="boolean" readonly="yes">
14441	<desc>
14442	Supports relative coordinates.
14443	</desc>
14444	</attribute>
14445	<attribute name="needsHostCursor" type="boolean" readonly="yes">
14446	<desc>
14447	If host cursor is needed.
14448	</desc>
14449	</attribute>
14450	</interface>
14451
14452	<interface
14453	name="IKeyboardLedsChangedEvent" extends="IEvent"
14454	uuid="6DDEF35E-4737-457B-99FC-BC52C851A44F"
14455	wsmap="managed" autogen="VBoxEvent" id="OnKeyboardLedsChanged"
14456	>
14457	<desc>
14458	Notification when the guest OS executes the KBD_CMD_SET_LEDS command
14459	to alter the state of the keyboard LEDs.
14460	</desc>
14461	<attribute name="numLock" type="boolean" readonly="yes">
14462	<desc>
14463	NumLock status.
14464	</desc>
14465	</attribute>
14466	<attribute name="capsLock" type="boolean" readonly="yes">
14467	<desc>
14468	CapsLock status.
14469	</desc>
14470	</attribute>
14471	<attribute name="scrollLock" type="boolean" readonly="yes">
14472	<desc>
14473	ScrollLock status.
14474	</desc>
14475	</attribute>
14476	</interface>
14477
14478	<interface
14479	name="IStateChangedEvent" extends="IEvent"
14480	uuid="4376693C-CF37-453B-9289-3B0F521CAF27"
14481	wsmap="managed" autogen="VBoxEvent" id="OnStateChanged"
14482	>
14483	<desc>
14484	Notification when the execution state of the machine has changed.
14485	The new state is given.
14486	</desc>
14487	<attribute name="state" type="MachineState" readonly="yes">
14488	<desc>
14489	New machine state.
14490	</desc>
14491	</attribute>
14492	</interface>
14493
14494	<interface
14495	name="IAdditionsStateChangedEvent" extends="IEvent"
14496	uuid="D70F7915-DA7C-44C8-A7AC-9F173490446A"
14497	wsmap="managed" autogen="VBoxEvent" id="OnAdditionsStateChanged"
14498	>
14499	<desc>
14500	Notification when a Guest Additions property changes.
14501	Interested callees should query IGuest attributes to
14502	find out what has changed.
14503	</desc>
14504	</interface>
14505
14506	<interface
14507	name="INetworkAdapterChangedEvent" extends="IEvent"
14508	uuid="08889892-1EC6-4883-801D-77F56CFD0103"
14509	wsmap="managed" autogen="VBoxEvent" id="OnNetworkAdapterChanged"
14510	>
14511	<desc>
14512	Notification when a property of one of the
14513	virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
14514	changes. Interested callees should use INetworkAdapter methods and
14515	attributes to find out what has changed.
14516	</desc>
14517	<attribute name="networkAdapter" type="INetworkAdapter" readonly="yes">
14518	<desc>
14519	Network adapter that is subject to change.
14520	</desc>
14521	</attribute>
14522	</interface>
14523
14524	<interface
14525	name="ISerialPortChangedEvent" extends="IEvent"
14526	uuid="3BA329DC-659C-488B-835C-4ECA7AE71C6C"
14527	wsmap="managed" autogen="VBoxEvent" id="OnSerialPortChanged"
14528	>
14529	<desc>
14530	Notification when a property of one of the
14531	virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
14532	Interested callees should use ISerialPort methods and attributes
14533	to find out what has changed.
14534	</desc>
14535	<attribute name="serialPort" type="ISerialPort" readonly="yes">
14536	<desc>
14537	Serial port that is subject to change.
14538	</desc>
14539	</attribute>
14540	</interface>
14541
14542	<interface
14543	name="IParallelPortChangedEvent" extends="IEvent"
14544	uuid="813C99FC-9849-4F47-813E-24A75DC85615"
14545	wsmap="managed" autogen="VBoxEvent" id="OnParallelPortChanged"
14546	>
14547	<desc>
14548	Notification when a property of one of the
14549	virtual <link to="IMachine::getParallelPort">parallel ports</link>
14550	changes. Interested callees should use ISerialPort methods and
14551	attributes to find out what has changed.
14552	</desc>
14553	<attribute name="parallelPort" type="IParallelPort" readonly="yes">
14554	<desc>
14555	Parallel port that is subject to change.
14556	</desc>
14557	</attribute>
14558	</interface>
14559
14560	<interface
14561	name="IStorageControllerChangedEvent" extends="IEvent"
14562	uuid="715212BF-DA59-426E-8230-3831FAA52C56"
14563	wsmap="managed" autogen="VBoxEvent" id="OnStorageControllerChanged"
14564	>
14565	<desc>
14566	Notification when a
14567	<link to="IMachine::mediumAttachments">medium attachment</link>
14568	changes.
14569	</desc>
14570	</interface>
14571
14572	<interface
14573	name="IMediumChangedEvent" extends="IEvent"
14574	uuid="0FE2DA40-5637-472A-9736-72019EABD7DE"
14575	wsmap="managed" autogen="VBoxEvent" id="OnMediumChanged"
14576	>
14577	<desc>
14578	Notification when a
14579	<link to="IMachine::mediumAttachments">medium attachment</link>
14580	changes.
14581	</desc>
14582	<attribute name="mediumAttachment" type="IMediumAttachment" readonly="yes">
14583	<desc>
14584	Medium attachment that is subject to change.
14585	</desc>
14586	</attribute>
14587	</interface>
14588
14589	<interface
14590	name="ICPUChangedEvent" extends="IEvent"
14591	uuid="D0F0BECC-EE17-4D17-A8CC-383B0EB55E9D"
14592	wsmap="managed" autogen="VBoxEvent" id="OnCPUChanged"
14593	>
14594	<desc>
14595	Notification when a CPU changes.
14596	</desc>
14597	<attribute name="cpu" type="unsigned long" readonly="yes">
14598	<desc>
14599	The CPU which changed.
14600	</desc>
14601	</attribute>
14602	<attribute name="add" type="boolean" readonly="yes">
14603	<desc>
14604	Flag whether the CPU was added or removed.
14605	</desc>
14606	</attribute>
14607	</interface>
14608
14609	<interface
14610	name="ICPUPriorityChangedEvent" extends="IEvent"
14611	uuid="657fe2fe-a75a-4cb6-8cf9-072aa41e7d75"
14612	wsmap="managed" autogen="VBoxEvent" id="OnCPUPriorityChanged"
14613	>
14614	<desc>
14615	Notification when the CPU priority changes.
14616	</desc>
14617	<attribute name="priority" type="unsigned long" readonly="yes">
14618	<desc>
14619	The new CPU priority value. (1-100)
14620	</desc>
14621	</attribute>
14622	</interface>
14623
14624	<interface
14625	name="IVRDPServerChangedEvent" extends="IEvent"
14626	uuid="726038B6-6279-4A7A-8037-D041693D1915"
14627	wsmap="managed" autogen="VBoxEvent" id="OnVRDPServerChanged"
14628	>
14629	<desc>
14630	Notification when a property of the
14631	<link to="IMachine::VRDPServer">VRDP server</link> changes.
14632	Interested callees should use IVRDPServer methods and attributes to
14633	find out what has changed.
14634	</desc>
14635	</interface>
14636
14637	<interface
14638	name="IRemoteDisplayInfoChangedEvent" extends="IEvent"
14639	uuid="65B556C5-2A99-47D8-B311-FC177F0914CD"
14640	wsmap="managed" autogen="VBoxEvent" id="OnRemoteDisplayInfoChanged"
14641	>
14642	<desc>
14643	Notification when the status of the VRDP server changes. Interested callees
14644	should use <link to="IConsole::remoteDisplayInfo">IRemoteDisplayInfo</link>
14645	attributes to find out what is the current status.
14646	</desc>
14647	</interface>
14648
14649	<interface
14650	name="IUSBControllerChangedEvent" extends="IEvent"
14651	uuid="93BADC0C-61D9-4940-A084-E6BB29AF3D83"
14652	wsmap="managed" autogen="VBoxEvent" id="OnUSBControllerChanged"
14653	>
14654	<desc>
14655	Notification when a property of the virtual
14656	<link to="IMachine::USBController">USB controller</link> changes.
14657	Interested callees should use IUSBController methods and attributes to
14658	find out what has changed.
14659	</desc>
14660	</interface>
14661
14662	<interface
14663	name="IUSBDeviceStateChangedEvent" extends="IEvent"
14664	uuid="806da61b-6679-422a-b629-51b06b0c6d93"
14665	wsmap="managed" autogen="VBoxEvent" id="OnUSBDeviceStateChanged"
14666	>
14667	<desc>
14668	Notification when a USB device is attached to or detached from
14669	the virtual USB controller.
14670
14671	This notification is sent as a result of the indirect
14672	request to attach the device because it matches one of the
14673	machine USB filters, or as a result of the direct request
14674	issued by <link to="IConsole::attachUSBDevice"/> or
14675	<link to="IConsole::detachUSBDevice"/>.
14676
14677	This notification is sent in case of both a succeeded and a
14678	failed request completion. When the request succeeds, the
14679	@a error parameter is @c null, and the given device has been
14680	already added to (when @a attached is @c true) or removed from
14681	(when @a attached is @c false) the collection represented by
14682	<link to="IConsole::USBDevices"/>. On failure, the collection
14683	doesn't change and the @a error parameter represents the error
14684	message describing the failure.
14685	</desc>
14686	<attribute name="device" type="IUSBDevice" readonly="yes">
14687	<desc>
14688	Device that is subject to state change.
14689	</desc>
14690	</attribute>
14691	<attribute name="attached" type="boolean" readonly="yes">
14692	<desc>
14693	@c true if the device was attached and @c false otherwise.
14694	</desc>
14695	</attribute>
14696	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
14697	<desc>
14698	@c null on success or an error message object on failure.
14699	</desc>
14700	</attribute>
14701	</interface>
14702
14703	<interface
14704	name="ISharedFolderChangedEvent" extends="IEvent"
14705	uuid="B66349B5-3534-4239-B2DE-8E1535D94C0B"
14706	wsmap="managed" autogen="VBoxEvent" id="OnSharedFolderChanged"
14707	>
14708	<desc>
14709	Notification when a shared folder is added or removed.
14710	The @a scope argument defines one of three scopes:
14711	<link to="IVirtualBox::sharedFolders">global shared folders</link>
14712	(<link to="Scope_Global">Global</link>),
14713	<link to="IMachine::sharedFolders">permanent shared folders</link> of
14714	the machine (<link to="Scope_Machine">Machine</link>) or <link
14715	to="IConsole::sharedFolders">transient shared folders</link> of the
14716	machine (<link to="Scope_Session">Session</link>). Interested callees
14717	should use query the corresponding collections to find out what has
14718	changed.
14719	</desc>
14720	<attribute name="scope" type="Scope" readonly="yes">
14721	<desc>
14722	Scope of the notification.
14723	</desc>
14724	</attribute>
14725	</interface>
14726
14727	<interface
14728	name="IRuntimeErrorEvent" extends="IEvent"
14729	uuid="883DD18B-0721-4CDE-867C-1A82ABAF914C"
14730	wsmap="managed" autogen="VBoxEvent" id="OnRuntimeError"
14731	>
14732	<desc>
14733	Notification when an error happens during the virtual
14734	machine execution.
14735
14736	There are three kinds of runtime errors:
14737	<ul>
14738	<li><i>fatal</i></li>
14739	<li><i>non-fatal with retry</i></li>
14740	<li><i>non-fatal warnings</i></li>
14741	</ul>
14742
14743	<b>Fatal</b> errors are indicated by the @a fatal parameter set
14744	to @c true. In case of fatal errors, the virtual machine
14745	execution is always paused before calling this notification, and
14746	the notification handler is supposed either to immediately save
14747	the virtual machine state using <link to="IConsole::saveState"/>
14748	or power it off using <link to="IConsole::powerDown"/>.
14749	Resuming the execution can lead to unpredictable results.
14750
14751	<b>Non-fatal</b> errors and warnings are indicated by the
14752	@a fatal parameter set to @c false. If the virtual machine
14753	is in the Paused state by the time the error notification is
14754	received, it means that the user can <i>try to resume</i> the machine
14755	execution after attempting to solve the problem that caused the
14756	error. In this case, the notification handler is supposed
14757	to show an appropriate message to the user (depending on the
14758	value of the @a id parameter) that offers several actions such
14759	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
14760	wants to retry, the notification handler should continue
14761	the machine execution using the <link to="IConsole::resume"/>
14762	call. If the machine execution is not Paused during this
14763	notification, then it means this notification is a <i>warning</i>
14764	(for example, about a fatal condition that can happen very soon);
14765	no immediate action is required from the user, the machine
14766	continues its normal execution.
14767
14768	Note that in either case the notification handler
14769	<b>must not</b> perform any action directly on a thread
14770	where this notification is called. Everything it is allowed to
14771	do is to post a message to another thread that will then talk
14772	to the user and take the corresponding action.
14773
14774	Currently, the following error identifiers are known:
14775	<ul>
14776	<li><tt>"HostMemoryLow"</tt></li>
14777	<li><tt>"HostAudioNotResponding"</tt></li>
14778	<li><tt>"VDIStorageFull"</tt></li>
14779	<li><tt>"3DSupportIncompatibleAdditions"</tt></li>
14780	</ul>
14781	</desc>
14782	<attribute name="fatal" type="boolean" readonly="yes">
14783	<desc>
14784	Whether the error is fatal or not.
14785	</desc>
14786	</attribute>
14787	<attribute name="id" type="wstring" readonly="yes">
14788	<desc>
14789	Error identifier.
14790	</desc>
14791	</attribute>
14792	<attribute name="message" type="wstring" readonly="yes">
14793	<desc>
14794	Optional error message.
14795	</desc>
14796	</attribute>
14797	</interface>
14798
14799
14800	<interface
14801	name="IEventSourceChangedEvent" extends="IEvent"
14802	uuid="e7932cb8-f6d4-4ab6-9cbf-558eb8959a6a"
14803	waitable="yes"
14804	wsmap="managed" autogen="VBoxEvent" id="OnEventSourceChanged"
14805	>
14806	<desc>
14807	Notification when an event source state changes (listener added or removed).
14808	</desc>
14809
14810	<attribute name="listener" type="IEventListener" readonly="yes">
14811	<desc>
14812	Event listener which has changed.
14813	</desc>
14814	</attribute>
14815
14816	<attribute name="add" type="boolean" readonly="yes">
14817	<desc>
14818	Flag whether listener was added or removed.
14819	</desc>
14820	</attribute>
14821	</interface>
14822
14823	<interface
14824	name="IExtraDataChangedEvent" extends="IEvent"
14825	uuid="024F00CE-6E0B-492A-A8D0-968472A94DC7"
14826	wsmap="managed" autogen="VBoxEvent" id="OnExtraDataChanged"
14827	>
14828	<desc>
14829	Notification when machine specific or global extra data
14830	has changed.
14831	</desc>
14832	<attribute name="machineId" type="uuid" mod="string" readonly="yes">
14833	<desc>
14834	ID of the machine this event relates to.
14835	Null for global extra data changes.
14836	</desc>
14837	</attribute>
14838	<attribute name="key" type="wstring" readonly="yes">
14839	<desc>
14840	Extra data key that has changed.
14841	</desc>
14842	</attribute>
14843	<attribute name="value" type="wstring" readonly="yes">
14844	<desc>
14845	Extra data value for the given key.
14846	</desc>
14847	</attribute>
14848	</interface>
14849
14850	<interface
14851	name="IVetoEvent" extends="IEvent"
14852	uuid="9a1a4130-69fe-472f-ac10-c6fa25d75007"
14853	wsmap="managed"
14854	>
14855	<desc>Base abstract interface for veto events.</desc>
14856
14857	<method name="addVeto">
14858	<desc>
14859	Adds a veto on this event.
14860	</desc>
14861	<param name="reason" type="wstring" dir="in">
14862	<desc>
14863	Reason for veto, could be null or empty string.
14864	</desc>
14865	</param>
14866	</method>
14867
14868	<method name="isVetoed">
14869	<desc>
14870	If this event was vetoed.
14871	</desc>
14872	<param name="result" type="boolean" dir="return">
14873	<desc>
14874	Reason for veto.
14875	</desc>
14876	</param>
14877	</method>
14878
14879	<method name="getVetos">
14880	<desc>
14881	Current veto reason list, if size is 0 - no veto.
14882	</desc>
14883	<param name="result" type="wstring" dir="return" safearray="yes">
14884	<desc>
14885	Array of reasons for veto provided by different event handlers.
14886	</desc>
14887	</param>
14888	</method>
14889
14890	</interface>
14891
14892	<interface
14893	name="IExtraDataCanChangeEvent" extends="IVetoEvent"
14894	uuid="245d88bd-800a-40f8-87a6-170d02249a55"
14895	wsmap="managed" autogen="VBoxEvent" id="OnExtraDataCanChange"
14896	waitable="true"
14897	>
14898	<desc>
14899	Notification when someone tries to change extra data for
14900	either the given machine or (if @c null) global extra data.
14901	This gives the chance to veto against changes.
14902	</desc>
14903	<attribute name="machineId" type="uuid" mod="string" readonly="yes">
14904	<desc>
14905	ID of the machine this event relates to.
14906	Null for global extra data changes.
14907	</desc>
14908	</attribute>
14909	<attribute name="key" type="wstring" readonly="yes">
14910	<desc>
14911	Extra data key that has changed.
14912	</desc>
14913	</attribute>
14914	<attribute name="value" type="wstring" readonly="yes">
14915	<desc>
14916	Extra data value for the given key.
14917	</desc>
14918	</attribute>
14919	</interface>
14920
14921	<interface
14922	name="ICanShowWindowEvent" extends="IVetoEvent"
14923	uuid="adf292b0-92c9-4a77-9d35-e058b39fe0b9"
14924	wsmap="managed" autogen="VBoxEvent" id="OnCanShowWindow"
14925	waitable="true"
14926	>
14927	<desc>
14928	Notification when a call to
14929	<link to="IMachine::canShowConsoleWindow"/> is made by a
14930	front-end to check if a subsequent call to
14931	<link to="IMachine::showConsoleWindow"/> can succeed.
14932
14933	The callee should give an answer appropriate to the current
14934	machine state using event veto. This answer must
14935	remain valid at least until the next
14936	<link to="IConsole::state">machine state</link> change.
14937	</desc>
14938	</interface>
14939
14940	<interface
14941	name="IShowWindowEvent" extends="IEvent"
14942	uuid="B0A0904D-2F05-4D28-855F-488F96BAD2B2"
14943	wsmap="managed" autogen="VBoxEvent" id="OnShowWindow"
14944	waitable="true"
14945	>
14946	<desc>
14947	Notification when a call to
14948	<link to="IMachine::showConsoleWindow"/>
14949	requests the console window to be activated and brought to
14950	foreground on the desktop of the host PC.
14951
14952	This notification should cause the VM console process to
14953	perform the requested action as described above. If it is
14954	impossible to do it at a time of this notification, this
14955	method should return a failure.
14956
14957	Note that many modern window managers on many platforms
14958	implement some sort of focus stealing prevention logic, so
14959	that it may be impossible to activate a window without the
14960	help of the currently active application (which is supposedly
14961	an initiator of this notification). In this case, this method
14962	must return a non-zero identifier that represents the
14963	top-level window of the VM console process. The caller, if it
14964	represents a currently active process, is responsible to use
14965	this identifier (in a platform-dependent manner) to perform
14966	actual window activation.
14967
14968	This method must set @a winId to zero if it has performed all
14969	actions necessary to complete the request and the console
14970	window is now active and in foreground, to indicate that no
14971	further action is required on the caller's side.
14972	</desc>
14973	<attribute name="winId" type="unsigned long long">
14974	<desc>
14975	Platform-dependent identifier of the top-level VM console
14976	window, or zero if this method has performed all actions
14977	necessary to implement the <i>show window</i> semantics for
14978	the given platform and/or this VirtualBox front-end.
14979	</desc>
14980	</attribute>
14981	</interface>
14982
14983	<module name="VBoxSVC" context="LocalServer">
14984	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
14985	namespace="virtualbox.org">
14986	<interface name="IVirtualBox" default="yes"/>
14987	</class>
14988	</module>
14989
14990	<module name="VBoxC" context="InprocServer" threadingModel="Free">
14991	<class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
14992	namespace="virtualbox.org">
14993	<interface name="ISession" default="yes"/>
14994	</class>
14995
14996	<class name="Console" uuid="577230FF-164F-4CAC-8548-312D8275A4A7"
14997	namespace="virtualbox.org">
14998	<interface name="IConsole" default="yes"/>
14999	</class>
15000	</module>
15001
15002	</library>
15003
15004	</idl>
15005
15006	<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->

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

Download in other formats:

Original Format